Roan provides the method
type to describe change ringing methods, not to be
confused with CLOS methods. A method
can only describe what the Central Council of
Church Bell Ringers Framework for
Method Ringing (FMR) calls a static method, a method that can be viewed as a fixed
sequence of changes, including jump changes; while this includes nearly all methods rung
and named to date, it does exclude, for example, Dixonoids. A method
has a name, a
stage, classifacation details, and an associated place-notation, though any or all of
these may be nil
. In the case of the stage or place notation nil
indicates
that the corresponding value is not known; the same is also true if the name is
nil
, except for the case of Little Bob, which in the taxonomy of the FMR has no
name. The stage, if known, should be a stage
, and the name and place notation, if
known, should be strings.
The classification follows the taxonomy in the FMR and consists of a class
and
three boolean attributes for jump methods, differential methods and little methods. The
class
may be nil
, for principles and pure differentials; one of the keywords
:bob
, :place
, :surprise
, :delight
, :treble-bob
,
:alliance
, :treble-place
or:hybrid
, naming the corresponding class;
or :hunt
indicating a method with one or more hunt bells that does not fall into
any of the named classes, which can only apply to jump methods. The classification
consists merely of details stored in the method
object, and does not necessary
correspond to the actual classification of the method described by the
place-notation
, if supplied. The classification can be set to match the place
notation by calling classify-method
.
Similarly the name does not necessarily correspond to the name by which the place notation
is known, unless the method
has been looked up from a suitable library.
See Methods library.
Because ringing methods and their classes are unrelated to CLOS methods and classes, the
roan
package shadows the symbols common-lisp:method
,
common-lisp:method-name
and common-lisp:class-name
.
Describes a change ringing method, typically including its name, stage, classification and place notation.
Creates a new method
instance, with the specified name, stage,
classification and place-notation.
If stage is not provided, it defaults to
the current value of *default-stage*
; to create a method
with no stage
:stage nil
must be explicitly supplied.
A type-error
is signaled if stage is supplied and is neither nil
nor a
stage
; if either of name or place-notation are supplied and are neither
nil
nor a string; or if class
is supplied and is neither nil
nor one
of the keywords :bob
, :place
, :surprise
, :delight
,
:treble-bob
, :alliance
, :treble-place
or :hybrid
. A
inconsistent-method-specification-error
is signaled if the various classification
details cannot occur together, such as a little principle.
Return the name, classification details, stage and place notation of method, or
nil
. A non-nil value returned by method-name
or method-place-notation
is a string; by method-stage
a stage
(that is, an integer); and by
method-class
one of the keywords :bob
, :place
, :surprise
,
:delight
, :treble-bob
, :alliance
, :treble-place
, or
:hybrid
. The predicates method-jump-p
, method-differential-p
and
method-little-p
return generalized booleans.
These functions all signal a type-error
if method is not a method
.
Note that method-jump-p
reflects the classification stored in method, while
method-contains-jump-changes-p
reflects the place notation of method, and
they may not agree.
All these functions may be used with setf
to set the relevant attributes of
method. No checking is done that the string supplied as the
method-place-notation
is, in fact, valid place notation; however, a subsequent
attempt to use invalid place notation, for example by method-changes
or
method-lead-head
, will signal an error. Attempting to set the name or place
notation to anything but a string or nil
, the class to anything but nil
or
one of the appropriate keywords, or the stage to anything but a stage
or nil
signals a type-error
.
See method-contains-jump-changes-p
Returns a new method
whose name and place notation are equal
to those
of method, and with the same classification as method. Signals a
type-error
if method is not a method
.
Returns a string containing as much of the method’s title as is known. If
show-unknown, a generalized boolean defaulting to false, is true then an unknown
name is described as "Unknown", and otherwise is simply omitted. Signals a
type-error
if method is not a method
.
The one argument case can be used with setf
, in which case it potentially sets any
or all of the name, classification and stage of method. There is an ambiguity when
parsing method titles in that there being no explicit class named can indicate with that
the method has no class (principles and pure differentials) or that the class is Hybrid.
When parsing titles for setf
an absence of a class name is taken to mean that there
is no class. Also, if there is no stage name specified when using setf
with
method-title
the stage is set to nil
; *default-stage*
is not
consulted.
(method-title (method "Advent" :class :surprise :stage 8)) ⇒ "Advent Surprise Major" (method-title (method :name "Grandsire" :class :bob :stage 9)) ⇒ "Grandsire Caters" (method-title (method :stage 8)) ⇒ "Major" (method-title (method :class :delight :stage 8) t) ⇒ "Unknown Delight Major (method-title (method :name "Advent" :class :surprise :stage nil)) ⇒ "Advent Surprise" (method-title (method :name "Slinky" :stage 12 :class :place :little t :differential t)) ⇒ "Slinky Differential Little Place Maximimus" (method-title (method :name "Stedman" :stage 11)) ⇒ "Stedman Cinques" (method-title (method :name "Meson" :class :hybrid :little t :stage 12)) ⇒ "Meson Maximus"
Creates a new method
instance, with its name, classification and stage
as specified by title, and with the given place-notation.
If the title does not include a stage name, the stage of the result is the current value
of *default-stage*
.
Note that it is not possible to distinguish hybrid methods from non-jump principles, nor
jump methods with hunt bells from those without, from their titles. By convention, if no
hunt bell class is specified in title a principle, that is a method without hunt
bells, is assumed. If in some specific use this is not correct it can be corrected by
setting method-class
, and possibly method-little-p
, of the resulting method
as desired.
A type-error
is signaled if title is not a string, or if place-notation
is neither a string nor nil
.
(let ((m (method-from-title "Advent Surprise Major"))) (list (method-title m) (method-class m) (method-stage m))) ⇒ ("Advent" :surprise 8)
If string is a suitable name for a method, returns a version appropriate for
comparison with other comparable names, and otherwise returns nil
.
The Central Council of Church Bell Ringers Framework for Method Ringing (FMR), appendix B describes a syntax for method names and their comparisons. This function both determines whether or not they fit within the syntax described by the FMR, and, if so, provides a canonical representation for them suitable for comparing whether or not two apparently different names will be considered the same when describing a method. This comparable representation is not intended for presentation to end users, but rather just for comparing names for equivalence.
Signals a type-error
if string is not a string.
(comparable-method-name "New Cambridge") ⇒ "new cambridge" (comparable-method-name "London No.3") ⇒ "london no 3" (comparable-method-name "mäkčeň E=mc²") ⇒ "makcen e mc2" (comparable-method-name "Two is Too Many Spaces") ⇒ nil (comparable-method-name "Ελληνικά is Greek to me") ⇒ nil
Signaled in circumstances when the various classification details provided cannot occur together, such as a little principle.
• Methods library |
Roan provides a library of method definitions, derived from the
Central Council of Church Bell
Ringers Methods Library. These are augmented with a handful of other methods not yet in
the CCCBR Library, jump methods and common alternative names for a few
methods (lookup-method-info). As delivered with Roan this library is only up to
date as of the date a version of Roan was released. However, if a network connection is
available, the library can be updated to the most recent version made available by the
Council by using update-method-library
. The Council typically updates their library
weekly.
The library can be interrogated with the lookup-methods
,
lookup-method-by-title
and lookup-methods-by-notation
functions.
Additional information such as dates and places of first peals containing the methods
is available for some of the methods using lookup-method-info
.
The lookup-methods
function returns a list of named method
s whose name,
classification and/or stage match those provided. If only a subset of these properties
are provided, the return list will contain all known methods that have the provided
ones.
If name is provided, it should be a string or nil
, and all the methods
returned will have that name. The Central Council of Church Bell Ringers
Framework for Method
Ringing (FMR), appendix C defines the form method names may take, and a mechanism for
comparing them that is more complex than simply comparing strings for equality. For
example, "London No.3"
and "London no 3"
are considered the same names.
The lookup-methods
function uses this mechanism. See comparable-method-name.
The name may also contain ‘*’ wildcard characters. Such a wildcard matches a
series of zero or more consecutive characters. Since the ‘*’ is not a character
allowed in method names by the FMR there is no ambiguity: occurrences of ‘*’ in
name are always wildcard characters. Wildcards are applicable only to name,
and not to any of the other arguments to lookup-methods
.
If stage is provided, it should be a stage
, that is a small integer. All the
methods that are returned will have that stage. While a method
object can have
an indeterminate stage, represented by nil
, all the methods returned by
lookup-methods
will have a definite stage, and nil
is not an allowed
value for the stage argument.
If class is provided, it should be nil
or one of the keywords :bob
,
:place
, :surprise
, :delight
, :treble-bob
,
:treble-place
, :alliance
, :hybrid
or :blank
. With the
exception of :blank
, all the methods returned will have the specified class. The
value :blank
matches either nil
, meaning no explicit class, or
:hybrid
; when writing a method’s title according to the FMR the hybrid class and no
class are indistinguishable, since “hybrid” is not included in the title.
If supplied, the generalized booleans little, differential and jump indicate that the returned methods should or should not have these properties. If these parameters are not supplied all otherwise matching methods in the library will be returned without regard to whether or not they have these properties.
If the title of a method is known, it can be found in the library by using
lookup-method-by-title
. The title should be a string. If a method
with
that title is in the library, it is returned. Otherwise nil
is returned, unless the
generalized Boolean errorp it true (it is false by default), in which case an error
is signaled. In general there should never be two or more different methods in the library
with the same title. Matching on the title is done using the FMR’s mechanism for comparing
names. Wildcards cannot be used with lookup-method-by-title
.
If the place notation of a method is known, and its name in the library is sought,
lookup-methods-by-notation
is available. The notation-or-changes should
be either a string, in which case it viewed as place notation, or a list of rows
,
representing changes all of the same stage. The stage should be a stage
; if
not provided or nil
the current value of *default-stage*
is used. If
notation-or-changes is a list of changes, the value of stage is ignored,
the stage of those changes being used instead. Two lists are returned. The first is of
methods that have the provided place notation (or corresponding changes). The second is of
methods that are rotations of methods with the given place notation. Either or both lists
may be empty if no suitable methods are found in the library.
There is no guarantee of what order methods are in the lists returned by
lookup-methods
or lookup-methods-by-notation
. Instances of the “same”
method returned by different invocations of these functions will typically not be
eq
.
A type-error
is signaled if stage is not a stage
(or, in the case of
lookup-methods-by-notation
, nil
); name is not a string or nil
;
notation-or-changes is neither a string nor a non-empty list of row
s;
changes is not a non-empty list of row
s; or if class is not one the
allowed values. A parse-error
is signaled if notation-or-changes is a string
and is not parseable as place notation at stage. An error
is signaled if
changes is a list of row
s, but they are not all of stage stage (or of
*default-stage*
if stage is nil
). A method-library-error
is
signaled if the method library file cannot be read or is of the wrong format.
(mapcar #'method-place-notation (lookup-methods :name "Advent" :class :surprise :stage 8)) ⇒ ("36x56.4.5x5.6x4x5x4x7,8") (mapcar #'method-title (lookup-methods :name "london no 3" :class :surprise :stage 10)) ⇒ ("London No.3 Surprise Royal") (method-place-notation (lookup-method-by-title "Advent Surprise Major")) ⇒ "36x56.4.5x5.6x4x5x4x7,8" (lookup-methods :name "No such method") ⇒ nil
(mapcar #'method-title (lookup-methods :name "Cambridge*" :class :surprise :stage 8)) ⇒ ("Cambridge Blue Surprise Major" "Cambridge Surprise Major" "Cambridgeshire Surprise Major")
(multiple-value-bind (n r) (lookup-methods-by-notation "36x56.4.5x5.6x4x5x4x7,8" 8) (list (mapcar #'method-title n) (mapcar #'method-title r))) ⇒ (("Advent Surprise Major") nil) (multiple-value-bind (n r) (lookup-methods-by-notation "1.3" 3) (list (mapcar #'method-title n) (mapcar #'method-title r))) ⇒ (("Reverse Original Singles") ("Original Singles")) (method-place-notation (lookup-method-by-title "Original Singles")) ⇒ "3.1"
Roan’s method library also stores metadata about many of the methods it contains. Each
kind of such metadata is described by a keyword, which is passed to this function as
key. The title-or-method may be a string or a method
. If a string, it
is the title of the method about which the metadata is sought. If the metadata indicated
by key is available for the method it is returned; the type of the return value
depends upon the kind of metadata sought. If no such metadata is available, including
if key is a not yet supported type of metadata or if title-or-method
does
not correspond to any method in the library, nil
is returned.
Currently supported values for key are
:first-towerbell-peal
Returns a string describing the first performance of the method on tower bells. No distinction if made between ringing the method on its own or ringing it in spliced.
:first-handbell-peal
Returns a string describing the first performance of the method on hand bells. No distinction if made between ringing the method on its own or ringing it in spliced.
:complib-id
Returns an integer, which is used to index information about the method on
Composition Library. This can also be used to distinguish those
methods added to those from the Central Council, as the added methods do not have a
:complib-id
, while all those from the Council do.
Others may be added in future versions of Roan.
Signals a type-error
if title-or-method is neither a string nor a
method
, or if key is not a keyword.
(lookup-method-info "Advent Surprise Major" :first-towerbell-peal) ⇒ "1988-07-31 Boston, MA (Advent)" (lookup-method-info (first (lookup-methods-by-notation "36x56.4.5x5.6x4x5x4x7,8")) :complib-id) ⇒ 20042 (lookup-method-info "Advent Surprise Major" :no-such-info) ⇒ nil
Queries the remote server containing the CCCBR’s Methods Library. If that remote
file has changed since the one Roan’s library was built from was downloaded, it fetches
the new one and uses it to build an updated Roan method library. If the generalized
boolean force is true it fetches the remote file and rebuilds Roan’s library
without regard to whether the remote one has changed. If the library is updated, returns
an integer, the number of methods the updated library contains; if the library is not
updated because the remote version hasn’t changed returns nil
.
May signal any of a variety of file system or network errors if network access is not available, or unreliable, or if there are other difficulties downloading and processing the remote file.
Returns eight values describing the current Roan method libary. All are strings. They are:
update-method-library
decides whether or not the Roan method library needs
updating.
Signaled when a method library file cannot be read. Contains two
potentially useful slots accessible with file-error-pathname
and
method-library-error-description
.
Replaces method’s place-notation by an equivalent string in canonical form, and
returns that canonical notation as a string. Unless overriden by keyword arguments this is
a compact version with leading and lying changes elided according to :lead-end
format as for write-place-notation
, partitioned with a comma, if possible, with
upper case letters for high number bells and a lower case ‘x’ for cross. The behavior
can be changed by passing keyword arguments as for write-place-notation
. If
method has no place-notation or no stage, this function does nothing, and returns
nil
; in particular, if there is place-notation but no stage, the place-notation
will be unchanged.
Signals a type-error
if method is not a method
, and signals an error
if any of the keyword arguments do not have suitable values for passing to
write-place-notation
. Signals a parse-error
if the place notation string
cannot be properly parsed as place notation at method’s stage.
See canonicalize-place-notation and write-place-notation.
(let ((m (method :stage 6 :place-notation "-16.X.14-6X16"))) (canonicalize-method-place-notation m) (method-place-notation m)) ⇒ "x1x4,6"
If method’s stage and place-notation have been set returns a fresh list of
row
s, representing changes, that constitute a plain lead of method, and
otherwise returns nil
. Signals a type-error
if method is not a
method
. Signals a parse-error
if the place notation string cannot be
properly parsed as place notation at method’s stage.
(method-changes (method :stage 6 :place-notation "x2,6")) ⇒ (!214365 !124365 !214365 !132546)
If method’s stage and place-notation have been set and method contains one or
more jump changes returns true, and otherwise returns nil
. Note that even if the
place notation is set and implies jump changes, if the stage is not set
method-contains-jump-changes-p
will still return nil
.
Note that this function reflects the place notation of method while
method-jump-p
reflects the classification stored in the method, and they may not
agree.
Signals a type-error
if method is not a method
. Signals a
parse-error
if the place notation string cannot be properly parsed as place
notation at method’s stage.
(method-contains-jump-changes-p (method :place-notation "x3x4x2x3x4x5,2" :stage 6)) ⇒ nil (method-contains-jump-changes-p (method :place-notation "x3x(24)x2x(35)x4x5,2" :stage 6)) ⇒ t (method-contains-jump-changes-p (method :stage 6)) ⇒ nil (method-contains-jump-changes-p (method :place-notation "x3x(24)x2x(35)x4x5,2" :stage nil)) ⇒ nil
If method’s stage and place-notation have been set returns a row
, the lead
head generated by one plain lead of method, and otherwise nil
. If
method has a one lead plain course the result will be rounds. Signals a
type-error
if method is not a method
. Signals a parse-error
if
the place notation string cannot be properly parsed as place notation at method’s
stage.
(method-lead-head (method-from-title "Little Bob Major" "x1x4,2")) ⇒ !16482735
If method’s stage and place-notation have been set returns a positive integer,
the number of leads in a plain course of method, and otherwise nil
. Signals a
type-error
if method is not a method
. Signals a parse-error
if
the place notation string cannot be properly parsed as place notation at method’s
stage.
(method-lead-count (method-from-title "Cambridge Surprise Minor" "x3x4x2x3x4x5,2")) ⇒ 5 (method-lead-count (method-from-title "Cromwell Tower Block Surprise Minor" "3x3.4x2x3x4x3,6")) ⇒ 1 (method-lead-count (method-from-title "Bexx Differential Bob Minor" "x1x1x23,2")) ⇒ 6
If method’s stage and place-notation have been set returns a fresh list of
row
s, starting with rounds, that constitute the first lead of the plain course of
method, and otherwise returns nil
. The lead head that starts the next lead is
not included. Signals a type-error
if method is not a method
. Signals
a parse-error
if the place notation string cannot be properly parsed as place
notation at method’s stage.
(method-plain-lead (method :stage 6 :place-notation "x2,6")) ⇒ (!123456 !214365 !213456 !124365)
If method’s stage and place-notation have been set returns a positive integer,
the length of one lead of method, and otherwise nil
. Signals a
type-error
if method is not a method
. Signals a parse-error
if
the place notation string cannot be properly parsed as place notation at method’s
stage.
(method-lead-length (method-from-title "Cambridge Surprise Minor" "x3x4x2x3x4x5,2")) ⇒ 24
If method’s stage and place-notation have been set returns a positive integer,
the length of a plain course of method, and otherwise nil
. Signals a
type-error
if method is not a method
. Signals a parse-error
if
the place notation string cannot be properly parsed as place notation at method’s
stage.
(method-course-length (method :title "Cambridge Surprise Minor" :place-notation "x3x4x2x3x4x5,2")) ⇒ 120 (method-course-length (method :title "Cromwell Tower Block Minor" :place-notation "3x3.4x2x3x4x3,6")) ⇒ 24 (method-course-length (method :title "Bexx Differential Bob Minor" :place-notation "x1x1x23,2")) ⇒ 72
If method’s stage and place-notation have been set returns a fresh list of the
row
s that constitute a plain course of method, and otherwise nil
. The
list returned will start with rounds, and end with the row
immediately preceding the
final rounds. Signals a type-error
if method is not a method
. Signals
a parse-error
if the place notation string cannot be properly parsed as place
notation at method’s stage.
If method has a non-nil stage and place notation set, returns true if
method’s plain course is true and nil
otherwise. If method does not
have a non-nil stage or place notation a no-place-notation-error
is signaled if the
generalized boolean error-if-no-place-notation is true, and otherwise nil
is
returned; if error-if-no-place-notation is not supplied it defaults to true. Signals
a type-error
if method is not a method
. Signals a parse-error
if the place notation string cannot be properly parsed as place notation at method’s
stage.
(method-true-plain-course-p (method :title "Little Bob Minor" :place-notation "x1x4,2")) ⇒ t (method-true-plain-course-p (method :title "Unnamed Little Treble Place Minor" :place-notation "x5x4x2,2")) ⇒ nil
If method’s stage and place-notation have been set method-hunt-bells
returns a fresh list of bell
s (that is, small integers, with the treble represented
by zero) that are hunt bells of method (that is, that return to their starting place
at each lead head), and otherwise returns nil
. The bells in the list are ordered in
increasing numeric order. Note that for a method with no hunt bells this function will
also return nil
.
Signals a type-error
if method is not a method
, and signal a
parse-error
if the place notation string cannot be properly parsed as place
notation at method’s stage.
(method-hunt-bells (method-from-title "Grandsire Doubles" "3,1.5.1.5.1")) ⇒ (0 1)
If method’s stage and place-notation have been set returns a list of lists of
bell
s (that is, small integers, with the treble represented by zero) that are
working bells of method (that is, that do not return to their starting place at each
lead head), and otherwise returns nil
. The sublists each represent a cycle of
working bells. For example, for a major method with Plain Bob lead heads, there will be
one sublist returned, of length seven, containing the bells 1 through 7; while for a
differential method there will be at least two sublists returned. Each of the sublists is
ordered starting with the smallest bell in that sublist, and then in the order the place
bells follow one another in the method. Within the overall, top-level list the sublists
are ordered such that the first element of each sublist occur in increasing numeric order.
Note that for a method with no working bells (which will then have a one lead plain
course) this function also returns nil
. Signals a type-error
if method
is not a method
. Signals a parse-error
if the place notation string cannot
be properly parsed as place notation at method’s stage.
(method-working-bells (method :stage 7 :place-notation "7.1.7.47,27")) ⇒ ((1 4 5) (2 6 3))
Returns the lead head code for method, as a keyword, if its stage and place
notation are set and it has Plain Bob or Grandsire lead ends, and otherwise returns
nil
. No methods below minimus are considered to have such lead ends, nor is rounds
considered such a lead end. When not nil
the result is a keyword whose name
consists of a single letter, possibly followed by a digit.
The CCCBR’s various collections of methods have, for several decades, used succinct codes, typically single letters or, more recently, single letters followed by digits, to denote various lead ends for the methods they contain. While the choices made have in the past varied by collection, in recent decades a consistent set of codes has been used, which is now codified in the Central Council of Church Bell Ringers Framework for Method Ringing (FMR), appendix C. While these codes actually describe both a row and a change adjacent to that row, and thus two different rows, the FMR calls them "lead head codes", so that phrasing is also used here.
There is currently (as of July 2019) an issue with the definitions of these codes in the
FMR, where those for Grandsire-like methods do not correctly correspond to common
practice. For example, most ringers would consider Itchingfield Slow Bob Doubles and
Longford Bob Doubles to have the same lead ends. However, the current FMR definition says
that the former has ’c’ Grandsire lead ends, and the latter does not. This is currently
under discussion for correction in the next revision of the FMR. The
method-lead-head-code
function is implemented assuming that this will be corrected
in the next revision of the FMR to match common practice. For example, it considers
neither Itchingfield Slow Bob nor Longford Bob as having Grandsire lead ends.
It is also worth noting that, for some of the less common cases, the lead end codes defined in the FMR differ from those used in earlier CCCBR collections.
Signals a type-error
if method is not a method
, and a
parse-error
if method’s place notation cannot be interpreted at its stage.
(method-lead-head-code (lookup-method-by-title "Advent Surprise Major")) ⇒ :h (method-lead-head-code (lookup-method-by-title "Zanussi Surprise Maximus")) ⇒ :j2 (method-lead-head-code (lookup-method-by-title "Sgurr Surprise Royal")) ⇒ :d (method-lead-head-code (lookup-method-by-title "Twerton Little Bob Caters")) ⇒ :q2 (method-lead-head-code (lookup-method-by-title "Grandsire Royal")) ⇒ :p (method-lead-head-code (lookup-method-by-title "Double Glasgow Surprise Major")) ⇒ nil
Returns true if and only if the method has an even lead length and conventional
palindromic symmetry with apices at its half-lead and lead-end. Note that this means
it is false for methods such as Grandsire. Signals a type-error
if method is
not a method
. Signals a no-place-notation-error
if method’s stage or
place notation are not set. Signals a parse-error
if method’s place notation
cannot be interpreted at its stage.
(method-conventionally-symmetric-p (lookup-method-by-title "Advent Surprise Major")) ⇒ t (method-conventionally-symmetric-p (lookup-method-by-title "Grandsire Caters")) ⇒ nil
Returns true if and only if the changes constituting a lead of method-1 are the same as those constituting a lead of method-2, possibly rotated. If the changes are the same even without rotation that is considered a trivial rotation, and also returns true. Note that if method-1 and method-2 are of different stages the result will always be false.
Signals a no-place-notation-error
if either argument does not have its stage or
place notation set. Signals a type-error
if either argument is not a method
.
Signals a parse-error
if the place notation of either argument cannot be parsed as
place notation at its stage.
(method-rotations-p (method :stage 5 :place-notation "3,1.5.1.5.1") (method :stage 5 :place-notation "5.1.5.1,1.3")) ⇒ t (method-rotations-p (method :stage 5 :place-notation "3,1.5.1.5.1") (method :stage 5 :place-notation "3,1.5.1.5.1")) ⇒ t (method-rotations-p (method :stage 5 :place-notation "3,1.5.1.5.1") (method :stage 5 :place-notation "3,1.3.1.5.1") ⇒ nil (method-rotations-p (method :stage 5 :place-notation "3,1.5.1.5.1") (method :stage 7 :place-notation "5.1.5.1,1.3")) ⇒ nil)
If method has its stage and place notation set returns a string uniquely
identifying, using equal
, the changes of a lead of this method, invariant under
rotation. That is, if, and only if, two methods are rotations, possibly trivially so, of
one another their method-canonical-rotation-key
s will always be equal
. While
a string, the value is essentially an opaque type and should generally not be displayed to
an end user or otherwise have its structure depended upon, though it can be printed and
read back in again. While, within one version of Roan, this key can be counted on to be
the same in different sessions and on different machines, it may change between versions
of Roan. If method does not have both its stage and place notation set
method-canonical-rotation-key
returns nil
.
Signals a type-error
if method is not a method
. Signals a
parse-error
if method’s place notation cannot be properly parsed at its
stage.
(method-canonical-rotation-key (lookup-method "Cambridge Surprise" 8)) ⇒ "bAvzluTjWO5P" (method-canonical-rotation-key (method :stage 8 :place-notation "5x6x7,x4x36x25x4x3x2")) ⇒ "bAvzluTjWO5P" (method-canonical-rotation-key (method :stage 8 :place-notation "x1x4,2")) ⇒ "bEvy3Zo" (method-canonical-rotation-key (method :stage 10 :place-notation "x1x4,2")) ⇒ "Oi3Jd2sC" (method-canonical-rotation-key (method) ⇒ nil
Assigns the classification fields of method to match the classification assigned
by the Central Council of Church Bell Ringers
Framework for Method
Ringing (FMR) for the place notation contained in that method
, and returns the
method. Signals a type-error
if method is not a method
. Signals a
no-place-notation-error
if either the stage or place notation of method are
not set. Signals a parse-error
if the value of the place notation field cannot be
interpreted as place notation at the stage of method.
(method-title (classify-method (method :stage 8 :place-notation "x3x6x5x45,2")) t) ⇒ "Unnamed Differential Little Surprise Major"
Signaled in circumstances when the changes constituting a method are
needed but are not available because the method’s place notation or stage is empty.
Contains one potentially useful slot accessbile with
no-place-notation-error-method
. Note, however, that many functions that make use
of a method’s place notation and stage will return nil
rather than signaling this
error if either is not present.
Draws the blue line of method as a Scalable Vector Graphics (SVG) image. The method should have its stage and place notation set. While Roan only writes SVG format images, many other pieces of software, such as ImageMagick, are able to convert SVG images to other formats.
The destination can be
blueline
.
t
:
the SVG will be written to *standard-output*
, and the value of
*standard-output*
is returned as the value of the
call to blueline
.
if-exists :supersede
, and the truename of the resulting file is returned.
vector-push-extend
, which is
returned.
nil
:
the SVG will be written to a new string, which is returned.
Several keyword parameters can be used to control details of the image produced
Controls the distribution of leads into columns. For differentials, or methods with
multiple, equal length cycles of working bells, each cycle always starts a new column.
Within a cycle the value of layout controls the number of leads in a column. If it
is a non-negative integer, this is the maximum number of rows in a column; though if the
lead length exceeds this value each column will contain one lead. If nil
this is
no limit to the number of leads in a column, each cycle of working bells then filling a
column.The special value :grid
may also be supplied, in which case only a single
column is used for a single lead, with all the bells blue lines combined into it as a grid.
The default value for layout is 100
.
Controls which hunt bells are displayed specially. Those not displayed specially, are
treated as working bells. If a bell
, that is, a small, non-negative integer less
than the stage of method, this is the hunt bell displayed specially; a list of
bell
s may also be supplied, for multiple hunt bells. If a supplied bell
is
not actually a hunt bell of method it is ignored. The keyword first
is
equivalent to supplying whatever the smallest hunt bell of method is. The keyword
:all
is equivalent to supplying a list of all the hunt bells of method. The
keyword :working
treats all of the hunt bells as working bells. If hunt-bell
is nil
no hunt bells are displayed. The default value for hunt-bell is
:first
.
Controls which working bell of each cycle is drawn first, the others following on in the
order in which they are rung. This can be a bell
, or a list thereof, or one of the
keywords :natural
, :largest
or :smallest
. If :natural
for
each cycle the largest bell that makes a place across the lead end is chosen; if there
is no such bell in a cycle the largest bell in that cycle is used. For methods with
Grandsire-like palindromic symmetry the first row of the lead is used instead of the
lead end. The default value for working-bell is :natural
.
If non-null figures will also be drawn, in addition to the blue line. If t
they will
be drawn for all leads. If :lead
only for the first lead of each cycle. If
:half
and the method has the usual palindromic symmetry around the half lead,
with one additional change at the lead end, they will only be drawn for the first
half-lead; otherwise :half
is equivalent to :lead
. If :head
the
figures will only be drawn for the first lead head in each column. The default value for
figures is nil
.
if non-null the place notation will be drawn to the left of the blue lines. If t
it
will be drawn for the first lead in each column. If :lead
it will only be drawn for
the first columnn. If :half
and the method has the usual palindromic symmetry
around the half lead, with one additional change at the lead end, it will only be drawn
for the first half lead, plus at the lead end; otherwise :half
is equivalent to
:lead
. The default value for place-notation
is nil
.
May have a value of nil
, :dot
or :label
. If non-null dots are drawn
where each place bell starts, and if :label
a label is drawn to the right of the
blue line at each place bell’s start. The default value for place-bells is
:label
.
For an example, execute something like the following, and open the resulting file in a browser:
(blueline #P"/tmp/bastow.svg" (lookup-method-by-title "Bastow Little Bob Minor") :layout 12 :figures :lead :place-notation :half)
Default values for the keyword arguments to this function can be set by assigning a
property list of keywords and values to the variable *blueline-default-parameters*
.
(equal (blueline nil (lookup-method-by-title "Advent Surprise Major") :layout nil :figures t :place-notation :lead) (let ((*blueline-default-parameters* '(:layout nil :figures t :place-notation :lead))) (blueline nil (lookup-method-by-title "Advent Surprise Major")))) ⇒ t
Signals a type-error
if destination is not a stream, pathname, string with a
fill pointer or one of the symbols t
or nil
; if method is not a
method
; if layout is not non-negative integer, nil
or the keyword
:grid
; if hunt-bell is not a bell
, list of bells, nil
or one
one of the keywords :first
, :all
or :working
. if working-bell
is not a bell
, list of bells, or one of the symbols :natural
,
:largest
or smallest
; if figures is not one of the keywords
:none
, :head
, :half
, :lead
or :always
; if
place-notation is not one of the keywords :none
, :half
, :lead
or :always
; or if place-bells is not nil
or one of the keywords
:dot
or:label
. Signals a no-place-notation-error
if method
doesn’t have both its stage and place notation set. Can signal various errors if an I/O
error occurs trying to write to a stream or create a file.