Here is the documentation for those who'd like to extend or modify this software. For changes by version number, see the changes page.
Methods are represented by
structures, each of which has the descriptive information
nbells and the change data
single, each of
which is a list of changes, where a change is a string (used as a
vector of small numbers; an actual vector of numbers would work, too)
in which each element is the number of the place that the bell in that
place goes to next, the places being numbered, and the string indexed,
from 1 up i.e. the 0th element is not used. (See the description of ringing:ring-one-change for more details
of how to use it.)
(defstruct change-ringing-method title nbells plain ; work plus plain lead end work ; just the work, no lead end plain-lead-end ; just the lead end bob single original-description-string)
The methods parsed from a file are kept in an alist of method name
to method definitions, where a method definition is a list of lead end
code (as a lisp symbol such as
mx) and place notation (as
a string). To get the list of methods for a file, use
which uses a cache.
To get the
change-ringing-method for a method by name,
(ringing:find-named-method method-name). If
you want to find whether the method exists, give a non-nil optional
second argument (otherwise it gives an error if the method is not
known). This reads the appropriate file for you automatically.
If given a
ringing:find-named-method returns it. There is also a
ringing:method-name which takes a
change-ringing-method and returns the name of it, or,
given a string, returns the string. Use this in preference to
change-ringing-method-title, for flexibility. By using
these two functions, many functions in the emacs-ringing system can
take either a method name or a method data structure, converting it
(defstruct user-mistakes:method method ; back to actual method structure leads ; array of user-mistakes:lead structures )
(defstruct user-mistakes:lead method ; back to user-mistakes:method place ; which place bell row-faults ; each kind of fault, per row ; (including the non-faults! ; this is as count vector [ down places up ] which-row ; where we are attempts ; how many times we've tried this lead perfects ; how many times we've rung this lead perfectly total-faults ; how many faults we've made on this lead altogether latest-faults ; how many faults we've made last time we rang this )
The list of method groups is stored as an alist of group names to group definitions, where a group definition is as follows:
(defstruct method-groups:method-group "Description of a group of methods." title stage ;; There are two forms of this: if stage=0, methods is an alist of method ;; names (in their short form, e.g. "Cambridge") to nil; if stage>0, it ;; is an alist of method names (in their full form, e.g. "Cambridge Surprise Major") ;; to method structures. methods code-letters title-style-default style-default layout-default)where
methodsis an alist of method names to
change-ringing-methods (when the group has been instantiated at a particular stage) or nil (if the group hasn't specified what stage it's at, and the user hasn't been asked). You should get the backbone of the list of groups via the function
method-groups:all-groups(which will handle the ephemeral groups for you) and the group definition bodies via
method-groups:group-methods, which will fill in the
change-ringing-methods (they may be
nilin the result of
The elisp files linked to below may not be present individually on the server, but when you've downloaded the package, they will be reachable from your local copy of this file, which is included in the archive for download.
beer.el(Basis Emacs Engine for Ringing)
ringing:ring-from-rounds, but the most useful routines to understand are
(ringing:ring-one-change row change)
changeand returns the result. The arguments may both be strings or vectors (they are usually strings). Its arguments are as follows:
" 123456\n"(character 0 of the string, and any characters beyond those used by the method, are copied over unchanged, which may be useful for marking lines in various ways; my higher-level code in this software stores a newline at the end of each row, so it is automatically inserted in the buffer as results are displayed). It doesn't matter what the characters in here are; they'll normally either be numbers (or letters for higher-numbered bells) but could be dots, spaces and asterisks for drawing just the line bells, for example.
[ 0 2 1 4 3 6 5 ].
(ringing:ring-changes row changes continue-fn continue-args display-fn display-args)
changes; each time it first calls
ringing:ring-one-changeand then calls
display-argsare then used similarly, but the result is ignored.
ringing:ring-changesreturns the resulting row when all of
changes(including any continuations added by
fn) have been used.
continue-fnis normally used for adding lead ends.
(ringing:ring-from-rounds method continue-function continue-args display-function display-args)
beer.el. It is similar to
ringing:ring-changesbut sets up rounds as the starting point, and initializes various useful variables. There is also
ringing:ring-from-rounds-plain, which is similar (and has the same arguments) but skips anything to do with displaying the results -- it is meant for proving compositions, etc.
(ringing:advance-changes row changes)
rowand works forward
changes, without any callbacks.
(ringing:retreat-changes row changes)
changes, without any callbacks.
*for the blue line, and
.for the red line. Optionally, real lines are drawn between the rows, using
mini-ropes.el(q.v.) but will probably sometime get sound added.
# Plain methods p Plainbob p Stclementscollegebobwhere the code at the start of the line is the non-numeric part of the name of the file to look in in the method library, and the rest of the line is the name of the method. Comment lines begin with a
ringing:check-touch, which checks whether a given composition is true; may be supplied with rows rung so far to check against, so it can be used incrementally to see whether you can add a particular sequence of calls to something you've already started.