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

5 Methods

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.

Type: method

Describes a change ringing method, typically including its name, stage, classification and place notation.

Function: method &key name jump differential little class stage 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.

Function: method-name method
Function: method-jump-p method
Function: method-differential-p method
Function: method-little-p method
Function: method-class method
Function: method-stage method
Function: method-place-notation method

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

Function: copy-method method

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.

Function: method-title method &optional show-unknown

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"
Function: method-from-title title &optional place-notation

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)
Function: comparable-method-name string

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
Type: inconsistent-method-specification-error

Signaled in circumstances when the various classification details provided cannot occur together, such as a little principle.


Up: Methods   [Contents][Index]

5.1 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.

Function: lookup-methods &key name jump differential little class stage
Function: lookup-method-by-title title &optional errorp
Function: lookup-methods-by-notation notation-or-changes &optional stage

The lookup-methods function returns a list of named methods 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 rows; changes is not a non-empty list of rows; 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 rows, 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"
Function: lookup-method-info title-or-method key

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
Function: update-method-library &optional force

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.

Function: method-library-details

Returns eight values describing the current Roan method libary. All are strings. They are:

  1. A description of the CCCBR Method Library, extracted from the file from which the Roan library was constructed
  2. The date and time the file on the remote server was last modified, according to that server.
  3. The “entity tag” (ETag) of the remote file, as provided by the server. This is an opaque identifier that changes for each version of the remote file. Querying the current Etag is how update-method-library decides whether or not the Roan method library needs updating.
  4. The URL used to fetch the remote file from which the Roan library was built.
  5. The source-id provided in the remote file, that is a CCCBR version stamp.
  6. The date the CCCBR library was built, according to the contents of the file downloaded from the remote server. This may or may not be the same as the date the file on the remote server was last modified.
  7. A unique identifier for the current version of the Roan library. This will change whenever the Roan library is rebuilt, even if the resulting contents are unchanged.
  8. The date and time the current version of the Roan library was built.
Type: method-library-error

Signaled when a method library file cannot be read. Contains two potentially useful slots accessible with file-error-pathname and method-library-error-description.

5.2 Functions of the place notation of methods

Function: canonicalize-method-place-notation method &key comma elide cross upper-case allow-jump-changes

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"
Function: method-changes method

If method’s stage and place-notation have been set returns a fresh list of rows, 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)
Function: method-contains-jump-changes-p method

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
Function: method-lead-head method

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
Function: method-lead-count method

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
Function: method-plain-lead method

If method’s stage and place-notation have been set returns a fresh list of rows, 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)
Function: method-lead-length method

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
Function: method-course-length method

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
Function: method-plain-course method

If method’s stage and place-notation have been set returns a fresh list of the rows 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.

Function: method-true-plain-course-p method &optional error-if-no-place-notation

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
Function: method-hunt-bells method

If method’s stage and place-notation have been set method-hunt-bells returns a fresh list of bells (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)
Function: method-working-bells method

If method’s stage and place-notation have been set returns a list of lists of bells (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))
Function: method-lead-head-code method

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
Function: method-conventionally-symmetric-p method

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
Function: method-rotations-p method-1 method-2

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)
Function: method-canonical-rotation-key method

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-keys 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
Function: classify-method method

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"
Type: no-place-notation-error

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.

5.3 Drawing blue lines

Function: blueline destination method &rest keys &key layout hunt-bell working-bell figures place-notation place-bells

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

Several keyword parameters can be used to control details of the image produced

layout

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.

hunt-bell

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 bells 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.

working-bell

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.

figures

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.

place-notation

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.

place-bells

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.


Up: Methods   [Contents][Index]