Next: , Up: Top   [Contents][Index]

1 Introduction

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.


Next: , Up: Introduction   [Contents][Index]

1.1 Obtaining and installing Roan

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: , Previous: , Up: Introduction   [Contents][Index]

1.2 Reporting bugs

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


Next: , Previous: , Up: Introduction   [Contents][Index]

1.3 A note on examples

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: , Up: Introduction   [Contents][Index]

1.4 The roan package

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
Package: roan

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.

Function: use-roan &key package syntax modify

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: , Up: Introduction   [Contents][Index]