Next: Fundamental Types, Up: Top [Contents][Index]
Roan is a library of Common Lisp code for writing applications related to change ringing. It is roughly comparable to the Ringing Class Library, although that is for the C++ programming language, and the two libraries differ in many other ways.
Roan provides
While this manual describes Roan, it is neither a tutorial on Lisp nor one on change ringing. If you don’t know Common Lisp or don’t know about change ringing, much of this manual is likely to be confusing.
Roan is distributed under an MIT open source license. While you should read it for complete details, it largely means that you can just use Roan for nearly anything you like. See License. Roan also loads and uses a variety of other libraries. See dependencies.
• Obtaining and installing Roan | ||
• Reporting bugs | ||
• A note on examples | ||
• The roan package |
Next: Reporting bugs, Up: Introduction [Contents][Index]
While Quicklisp is not required to run Roan, it is recommended.
With Quicklisp installed and configured, you can download and install Roan by simply
evaluating (ql:quickload :roan)
.
Quicklisp’s quickload
function, above, will also pull in all the other libraries
upon which Roan depends; if you don’t use Quicklisp you will have to ensure that those
libraries are available and loaded. If you don’t want to use Quicklisp, and prefer to load
Roan by hand, the repository for Roan itself is at
https://bitbucket.org/dfmorrison/roan, and
both current and previous versions can be downloaded from the tags pane of the Downloads
page, https://bitbucket.org/dfmorrison/roan/downloads/?tab=tags.
Note that Quicklisp creates a new distribution about once a month, so there may be a log of that duration between when a new version is available in the Bitbucket repository and when that version is available in Quicklisp. If you need it sooner, you may need to download it yourself from Bitbucket.
Roan has been tested with at least
but should also work in other, modern Common Lisp implementations that support the libraries on which Roan depends. See dependencies.
Next: A note on examples, Previous: Obtaining and installing Roan, Up: Introduction [Contents][Index]
The best way to report bugs is to submit them with Roan’s Bitbucket issue tracker. If that doesn’t work for you you can also send mail to Don Morrison <dfm@ringing.org>.
It would be helpful, and will be more likely to lead to successful resolution of the bug, if a bug report includes
(asdf:component-version (asdf:find-system :roan))
(roan:method-library-details)
Next: The roan package, Previous: Reporting bugs, Up: Introduction [Contents][Index]
Examples in this manual are typically of the form
(caddr '(1 2 3 4)) ⇒ 3
That is, an expression, followed by ‘⇒’ and a printed representation of the result of evaluating that expression. That right hand side is typically not exactly as the REPL (Read Eval Print Loop) might print it: for example, symbols will usually be shown in lower case while most Lisp implementation’s REPLs will use upper case; and things like hash-sets that have indeterminate order may result in different orders of elements of lists.
Occasionally, though, examples will look like
CL-USER> (+ 1 2 3) 6 CL-USER> (values (+ 1 2 3) (cons 'a 'b)) 6 (A . B) CL-USER>
In this case the example is a transcript of an interaction with a REPL. None of the examples makes explicit note of which of these two styles is being used, it being assumed the reader can easily deduce this from their appearances.
Previous: A note on examples, Up: Introduction [Contents][Index]
All the symbols used by Roan to name functions, variables and so on are in the roan
package. When using them from another package, such as cl-user
, they should be
prefixed with an explicit roan:
.
CL-USER> *package* #<Package "COMMON-LISP-USER"> CL-USER> roan:+maximum-stage+ 24
Alternatively all the external symbols of the roan
package can be imported into a
package with use-package
, or the :use
option to defpackage
. There is
the slight complication, however, that the roan
package shadows the symbols
method
, method-name
, class
and class-name
from the
common-lisp
package. This is done because methods and their classes are important
concepts in change ringing, albeit ones unrelated to CLOS methods and classes. Typically
method
, method-name
, class
and class-name
should be shadowed
in other packages that use the roan
package. This can be done with
shadowing-import-from
, or the :shadowing-import
option to defpackage
.
Note that the original Common Lisp symbols will still be available as cl:method
,
cl:method-name
, cl:class
and cl:class-name
. See use-roan.
MY-PACKAGE> *package* #<Package "MY-PACKAGE"> MY-PACKAGE> (package-use-list *) (#<Package "COMMON-LISP">) MY-PACKAGE> (shadowing-import '(roan:method roan:method-name)) T MY-PACKAGE> (use-package :roan) T MY-PACKAGE> +maximum-stage+ 24
Contains the symbols used by Roan. The roan
package shadows three symbols from the
common-lisp
package: method
, method-name
, class
and
class-name
. The functions and so on attached to these symbols in the
common-lisp
package are usually only needed when doing introspection, and the
shadowing should rarely cause difficulties.
A convenience function for using the roan
package. Causes package,
which defaults to the current value of *package*
, to inherit all the external
symbols of the roan
package, shadowing method
, method-name
and
class-name
.
If the generalized boolean syntax is true, the default, it also enables use of Roan’s ‘!’ and ‘#!’ read macros, by calling roan-syntax with a true first argument; the value of modify is passed as a second argument to roan-syntax.
Signals a type-error
if package is not a package designator. Signals a
package-error
if package is the keyword
package.
MY-PACKAGE> *package* #<Package "MY-PACKAGE"> MY-PACKAGE> (package-use-list *) (#<Package "COMMON-LISP">) MY-PACKAGE> (rowp '!13276548) NIL MY-PACKAGE> (roan:use-roan) T MY-PACKAGE> +maximum-stage+ 24 MY-PACKAGE> (rowp '!13276548) T
Previous: A note on examples, Up: Introduction [Contents][Index]