The roan Reference Manual

3.1.1 roan/roan.asd

Source

roan.asd.

Parent Component

roan (system).

ASDF Systems

roan.

---

3.1.2 roan/package.lisp

Source

roan.asd.

Parent Component

roan (system).

Packages

roan.

---

3.1.3 roan/readtables.lisp

Dependency

package.lisp (file).

Source

roan.asd.

Parent Component

roan (system).

Public Interface

• roan-syntax (macro).
• use-roan (function).

Internals

• %roan-syntax (function).
• *previous-readtables* (special variable).
• simple-package-error (condition).

---

3.1.4 roan/util.lisp

Dependency

package.lisp (file).

Source

roan.asd.

Parent Component

roan (system).

Public Interface

• do-hash-set (macro).
• hash-set (function).
• hash-set (structure).
• hash-set-adjoin (function).
• hash-set-adjoin-list-elements (function).
• hash-set-clear (function).
• hash-set-copy (function).
• hash-set-count (function).
• hash-set-delete (function).
• hash-set-difference (function).
• hash-set-elements (function).
• hash-set-empty-p (function).
• hash-set-intersection (function).
• hash-set-member (function).
• hash-set-nadjoin (function).
• hash-set-nadjoin-list-elements (function).
• hash-set-ndifference (function).
• hash-set-nintersection (function).
• hash-set-nunion (function).
• hash-set-p (function).
• hash-set-pop (function).
• hash-set-proper-subset-p (function).
• hash-set-remove (function).
• hash-set-subset-p (function).
• hash-set-union (function).
• make-hash-set (function).
• map-hash-set (function).
• print-object (method).
• print-object (method).
• print-object (method).

Internals

• %extreme-hash-set (function).
• %hash-set-nintersection (function).
• %hash-set-nunion (function).
• %make-hash-set (function).
• %with-lock (function).
• *collapsable-whitespace-scanner* (special variable).
• *contains-collapsable-whitespace-scanner* (special variable).
• *threading-p* (special variable).
• +utf-8-external-format+ (special variable).
• add-entry (function).
• byte-left (function).
• cache-count (function).
• cache-entry (class).
• cache-entry-table (reader method).
• cache-size (reader method).
• check-type* (macro).
• checked-hash-set-table (function).
• clause-for-in-hash-set-1 (macro).
• clrcache (function).
• collapse-whitespace (function).
• define-thread-local (macro).
• deflock (macro).
• entry-key (reader method).
• (setf entry-key) (writer method).
• entry-value (reader method).
• (setf entry-value) (writer method).
• equal-byte-specifiers (function).
• get-entry (macro).
• get-newest-key (function).
• get-newest-value (function).
• (setf getcache) (setf expander).
• getcache (function).
• hash-set-table (reader).
• lru-cache (class).
• make-lru-cache (function).
• move-entry (function).
• newest-entry (reader method).
• (setf newest-entry) (writer method).
• next-entry (reader method).
• (setf next-entry) (writer method).
• oldest-entry (reader method).
• (setf oldest-entry) (writer method).
• previous-entry (reader method).
• (setf previous-entry) (writer method).
• prin1-hash-set (function).
• putcache (function).
• remcache (function).
• remove-entry (function).
• same-type-p (function).
• thread-call (function).
• with-lock (macro).
• with-roan-file (macro).
• with-warnings-muffled (macro).

---

3.1.5 roan/roan.lisp

Dependencies

• package.lisp (file).
• util.lisp (file).

Source

roan.asd.

Parent Component

roan (system).

Public Interface

• *cross-character* (special variable).
• *default-stage* (special variable).
• *print-bells-upper-case* (special variable).
• +maximum-stage+ (constant).
• +minimum-stage+ (constant).
• alter-stage (function).
• bell (type).
• bell-at-position (function).
• bell-from-name (function).
• bell-name (function).
• bells-list (function).
• bells-vector (function).
• canonicalize-place-notation (function).
• changep (function).
• cycles (function).
• generate-rows (generic function).
• in-course-p (function).
• inverse (function).
• involutionp (function).
• make-load-form (method).
• ngenerate-rows (generic function).
• npermute-by-collection (generic function).
• npermute-collection (generic function).
• order (function).
• parse-place-notation (function).
• parse-row (function).
• permutation-closure (function).
• permute (function).
• permute-by-collection (generic function).
• permute-by-inverse (function).
• permute-collection (generic function).
• permutef (macro).
• place-notation-error (function).
• place-notation-string (function).
• placesp (function).
• position-of-bell (function).
• print-object (method).
• read-place-notation (function).
• read-row (function).
• reversed-row (function).
• rounds (function).
• roundsp (function).
• row (function).
• row (structure).
• row-string (function).
• rowp (function).
• stage (function).
• stage (type).
• stage-from-name (function).
• stage-name (function).
• tenors-fixed-p (function).
• which-grandsire-lead-head (function).
• which-plain-bob-lead-head (function).
• write-place-notation (function).
• write-row (function).

Internals

• %assemble-row (function).
• %bells-vector (type).
• %fill-bells-vector (function).
• %in-course-p (function).
• %make-row (function).
• %npermute-hash-set (function).
• %parse-change (function).
• %parse-place-notation (function).
• %permute (function).
• %placesp (function).
• %roundsp (function).
• %tenors-fixed-p (function).
• %write-place-notation (function).
• *change-cache* (special variable).
• +bell-names+ (constant).
• +change-cache-size+ (constant).
• +char-code-array-length+ (constant).
• +cross-changes+ (constant).
• +extended-place-notation-scanner+* (constant).
• +hunt-changes+ (constant).
• +initial-cross-character+ (constant).
• +initial-print-bells-upper-case+ (constant).
• +named-bells+ (constant).
• +named-stages+ (constant).
• +place-notation-chars+ (constant).
• +place-notation-fragment-scanner+ (constant).
• +rounds-bell-array+ (constant).
• +stage-names+ (constant).
• changes-info (function).
• copy-row (function).
• generate-rows-error (function).
• generate-rows-initial-row (function).
• jump-change-error (function).
• jump-change-error (condition).
• nunfold (function).
• permute-collection-type-error (function).
• row-bells (reader).
• (setf row-bells) (writer).
• row-creation-error (function).
• row-creation-error (condition).
• row-creation-parse-error (condition).
• sharp-bang-reader (function).
• split-palindromic-changes (function).
• test-jump-palindrome (function).
• test-ordinary-palindrome (function).
• which-lead-head (function).
• with-bell-property-resolver (macro).
• with-initial-format-characters (macro).

---

3.1.6 roan/pattern.lisp

Dependencies

• package.lisp (file).
• util.lisp (file).
• roan.lisp (file).

Source

roan.asd.

Parent Component

roan (system).

Public Interface

• add-pattern (function).
• add-patterns (function).
• format-pattern (function).
• make-match-counter (function).
• match-counter (structure).
• match-counter-counts (function).
• (setf match-counter-handstroke-p) (setf expander).
• match-counter-handstroke-p (function).
• match-counter-labels (function).
• match-counter-pattern (function).
• match-counter-stage (reader).
• named-row-pattern (generic function).
• parse-pattern (function).
• pattern-parse-error (function).
• pattern-parse-error (condition).
• print-object (method).
• record-matches (function).
• remove-all-patterns (function).
• remove-pattern (function).
• reset-match-counter (function).
• row-match-error (function).
• row-match-error (condition).
• row-match-p (function).

Internals

• %counts (function).
• %make-match-counter (function).
• %rows-match-p (function).
• *dfa-stage* (special variable).
• *dfa-states* (special variable).
• *last-nfa-id* (special variable).
• *nfa-stage* (special variable).
• *pattern-cache* (special variable).
• *pattern-parse-state* (special variable).
• +initial-match-counter-size+ (constant).
• +pattern-cache-size+ (constant).
• +pattern-characters+ (constant).
• +pattern-token+* (constant).
• +run-token+* (constant).
• add-transition (function).
• advance-token (function).
• build-dfa-state (function).
• build-nfa (generic function).
• current-token (function).
• def-named-row (macro).
• dfa-state (class).
• empty-transition (reader method).
• (setf empty-transition) (writer method).
• ensure-valid-bell (function).
• ensure-valid-bell-class (function).
• ensure-valid-run (function).
• follow-empty-transitions (function).
• format-pattern-element (generic function).
• get-final (reader method).
• get-final (reader method).
• logiorf (macro).
• make-dfa (function).
• make-dfa-state (function).
• make-match-counter-dfas (function).
• make-nfa (function).
• make-nfa-state (function).
• make-pattern-parse-state (function).
• make-row-count (function).
• match-counter-%handstroke-p (reader).
• (setf match-counter-%handstroke-p) (writer).
• match-counter-dfas (reader).
• (setf match-counter-dfas) (writer).
• match-counter-patterns-table (reader).
• match-counter-patterns-vector (reader).
• (setf match-counter-patterns-vector) (writer).
• named-row-definition (function).
• nfa-id (function).
• nfa-state (class).
• parse-alternative (function).
• parse-bell-class (function).
• parse-disjunction (function).
• parse-element (function).
• parse-run (function).
• pattern-parse-error-index (reader method).
• (setf pattern-parse-error-index) (writer method).
• pattern-parse-error-message (reader method).
• (setf pattern-parse-error-message) (writer method).
• pattern-parse-error-pattern (reader method).
• (setf pattern-parse-error-pattern) (writer method).
• pattern-parse-state (class).
• pattern-parse-state-end-p (function).
• row-count (structure).
• row-count-backstroke (reader).
• (setf row-count-backstroke) (writer).
• row-count-double-row-p (reader).
• (setf row-count-double-row-p) (writer).
• row-count-handstroke (reader).
• (setf row-count-handstroke) (writer).
• row-count-label (reader).
• (setf row-count-label) (writer).
• row-count-pattern (reader).
• (setf row-count-pattern) (writer).
• set-final (writer method).
• signature (function).
• total-bells (function).
• transitions (reader method).
• transitions (reader method).

---

3.1.7 roan/method.lisp

Dependencies

• package.lisp (file).
• util.lisp (file).
• roan.lisp (file).

Source

roan.asd.

Parent Component

roan (system).

Public Interface

• *blueline-default-parameters* (special variable).
• *method-library-path* (special variable).
• blueline (function).
• call (function).
• call (structure).
• call-application-error (function).
• call-application-error (condition).
• call-apply (function).
• canonicalize-method-place-notation (function).
• class-name (function).
• classify-method (function).
• comparable-method-name (function).
• copy-method (function).
• fch-group (function).
• fch-group (structure).
• fch-group-elements (reader).
• fch-group-name (reader).
• fch-group-parity (reader).
• fch-groups-string (function).
• inappropriate-method-error (condition).
• inappropriate-method-error-details (reader method).
• inappropriate-method-error-method (reader method).
• inconsistent-method-specification-error (condition).
• lookup-method-by-title (function).
• lookup-method-info (function).
• lookup-methods (function).
• lookup-methods-by-notation (function).
• method (function).
• method (class).
• method-canonical-rotation-key (function).
• method-changes (function).
• (setf method-class) (setf expander).
• method-class (function).
• method-contains-jump-changes-p (function).
• method-conventionally-symmetric-p (function).
• method-course-length (function).
• (setf method-differential-p) (setf expander).
• method-differential-p (function).
• method-falseness (function).
• method-from-title (function).
• method-hunt-bells (function).
• (setf method-jump-p) (setf expander).
• method-jump-p (function).
• method-lead-count (function).
• method-lead-head (function).
• method-lead-head-code (function).
• method-lead-length (function).
• method-library-details (function).
• method-library-error (condition).
• method-library-error-description (reader method).
• (setf method-little-p) (setf expander).
• method-little-p (function).
• method-name (method).
• method-name (reader method).
• (setf method-name) (writer method).
• (setf method-name) (method).
• method-place-notation (method).
• method-place-notation (reader method).
• (setf method-place-notation) (writer method).
• (setf method-place-notation) (method).
• method-plain-course (function).
• method-plain-lead (function).
• method-rotations-p (function).
• (setf method-stage) (setf expander).
• method-stage (function).
• (setf method-title) (setf expander).
• method-title (function).
• method-true-plain-course-p (function).
• method-working-bells (function).
• mixed-stage-fch-groups-error (condition).
• no-place-notation-error (condition).
• parse-method-title (function).
• print-object (method).
• print-object (method).
• print-object (method).
• update-method-library (function).

Internals

• %blueline (function).
• %get-call-changes (macro).
• %get-changes (function).
• %get-contains-jump-changes-p (function).
• %get-course-length (function).
• %get-hunt-bells (function).
• %get-lead-count (function).
• %get-lead-head (function).
• %get-lead-head-code (function).
• %get-lead-length (function).
• %get-plain-course (function).
• %get-plain-lead (function).
• %get-working-bells (function).
• %method-classification (method).
• %method-classification (reader method).
• (setf %method-classification) (writer method).
• %update-changes (function).
• %update-course-length (function).
• %update-lead-count (function).
• %update-lead-head-code (function).
• %update-lead-length (function).
• %update-plain-course (function).
• %update-plain-lead (function).
• *blueline-figures-lead-head* (special variable).
• *blueline-method* (special variable).
• *blueline-row-height* (special variable).
• *blueline-stream* (special variable).
• *fch-groups-by-course-head* (special variable).
• *fch-groups-by-name* (special variable).
• *last-fch-group-index* (special variable).
• *method-library* (special variable).
• *method-traits-cache* (special variable).
• *rows-distinct-p-hash-table* (special variable).
• *xml-file* (special variable).
• +blueline-column-spacing+ (constant).
• +blueline-dot-size+ (constant).
• +blueline-figures-size+ (constant).
• +blueline-figures-x-offset+ (constant).
• +blueline-figures-y-offset+ (constant).
• +blueline-first-hunt-bell-colors+ (constant).
• +blueline-first-hunt-bell-width+ (constant).
• +blueline-horizontal-increment+ (constant).
• +blueline-horizontal-margin+ (constant).
• +blueline-inter-cycle-gap+ (constant).
• +blueline-labels-circle-radius+ (constant).
• +blueline-labels-circle-x-offset+ (constant).
• +blueline-labels-circle-y-offset+ (constant).
• +blueline-labels-left-margin+ (constant).
• +blueline-labels-right-margin+ (constant).
• +blueline-labels-size+ (constant).
• +blueline-labels-vertical-offset+ (constant).
• +blueline-no-figure-ratio+ (constant).
• +blueline-place-notation-character-width+ (constant).
• +blueline-place-notation-margin+ (constant).
• +blueline-place-notation-offset+ (constant).
• +blueline-place-notation-size+ (constant).
• +blueline-plus-length+ (constant).
• +blueline-vertical-margin+ (constant).
• +blueline-vertical-offset+ (constant).
• +blueline-working-bell-color+ (constant).
• +blueline-working-bell-width+ (constant).
• +call-changes-vector-length+ (constant).
• +class-field+ (constant).
• +class-names+ (constant).
• +classes+ (constant).
• +conventional-symmetry-scanner+ (special variable).
• +default-method-libary-size+ (constant).
• +differential-field+ (constant).
• +extra-methods+ (constant).
• +huffman-table+ (constant).
• +incidence-initial-hash-set-size+ (constant).
• +jump-field+ (constant).
• +lead-head-codes+ (constant).
• +little-field+ (constant).
• +method-library-format-version+ (constant).
• +method-library-magic-string+ (constant).
• +method-name-character-data+ (constant).
• +method-source+ (constant).
• +method-source-entry+ (constant).
• +method-title-scanner+ (special variable).
• +method-traits-cache-size+ (constant).
• +path-types+ (constant).
• +row-signature-shift+ (constant).
• +stage-field+ (constant).
• +status-ok+ (constant).
• +summary-initial-hash-set-size+ (constant).
• +suppress-class+ (constant).
• add-library-method (function).
• bell-list-p (function).
• blueline-format (function).
• call-application-error-call (reader method).
• call-application-error-details (reader method).
• call-application-error-method (reader method).
• call-changes (reader).
• call-following (reader).
• call-fraction (reader).
• call-from-end (reader).
• call-offset (reader).
• call-place-notation (reader).
• call-replace (reader).
• canonical-rotation (function).
• canonical-rotation-key (function).
• class-from-name (function).
• clear-method-traits (function).
• comparableize-string (function).
• compare-rows (function).
• convert-xml-method-file (function).
• copy-method-library (function).
• create-fch-group (function).
• cross-sections (function).
• define-method-boolean (macro).
• define-method-trait (macro).
• download-zipped-methods (function).
• draw-column (function).
• draw-dot (function).
• draw-figures (function).
• draw-label (function).
• draw-line (function).
• draw-place-notation (function).
• encode-place-notation (function).
• encoded-classification (type).
• falseness-groups (function).
• fch-group-index (reader).
• fch-group-p (function).
• fch-lessp (function).
• fch-list-f (macro).
• find-name-prefix (function).
• get-accessor-names (function).
• get-call-changes (macro).
• get-headers (function).
• get-method-traits (function).
• get-single-element-by-tag-name (function).
• headers-extract (function).
• jump-allowed-path-little-p (function).
• make-call (function).
• make-fch-group (function).
• make-method-library (function).
• make-method-traits (function).
• method-details (function).
• method-library (structure).
• method-library-additional-data (reader).
• (setf method-library-additional-data) (writer).
• method-library-etag (function).
• method-library-metadata (reader).
• (setf method-library-metadata) (writer).
• method-library-methods (reader).
• (setf method-library-methods) (writer).
• method-library-no-name-count (reader).
• (setf method-library-no-name-count) (writer).
• method-library-p (function).
• method-library-parse-error (function).
• method-library-rotation-keys (reader).
• (setf method-library-rotation-keys) (writer).
• method-traits (structure).
• method-traits-changes (reader).
• (setf method-traits-changes) (writer).
• method-traits-classification (reader).
• (setf method-traits-classification) (writer).
• method-traits-contains-jump-changes-p (reader).
• (setf method-traits-contains-jump-changes-p) (writer).
• method-traits-course-length (reader).
• (setf method-traits-course-length) (writer).
• method-traits-hunt-bells (reader).
• (setf method-traits-hunt-bells) (writer).
• method-traits-lead-count (reader).
• (setf method-traits-lead-count) (writer).
• method-traits-lead-head (reader).
• (setf method-traits-lead-head) (writer).
• method-traits-lead-head-code (reader).
• (setf method-traits-lead-head-code) (writer).
• method-traits-lead-length (reader).
• (setf method-traits-lead-length) (writer).
• method-traits-plain-course (reader).
• (setf method-traits-plain-course) (writer).
• method-traits-plain-lead (reader).
• (setf method-traits-plain-lead) (writer).
• method-traits-principal-hunt-bells (reader).
• (setf method-traits-principal-hunt-bells) (writer).
• method-traits-secondary-hunt-bells (reader).
• (setf method-traits-secondary-hunt-bells) (writer).
• method-traits-working-bells (reader).
• (setf method-traits-working-bells) (writer).
• name-recognizers (function).
• name-spaces-p (function).
• no-place-notation-error-method (reader method).
• no-place-notation-error-method (reader method).
• parse-method-id (function).
• parse-method-library-description (function).
• parse-peal (function).
• parse-prototype (function).
• partition-hunt-bells (function).
• path-attributes-non-jump (function).
• plain-class-type (function).
• publish-trait (function).
• read-method-library (function).
• rotate-cycle (function).
• row-list-less-p (function).
• rows-distinct-p (function).
• set-method-class (function).
• set-method-differential-p (function).
• set-method-jump-p (function).
• set-method-little-p (function).
• set-method-stage (function).
• set-method-title (function).
• sort-fch-set (function).
• text (function).
• treble-dodging-class-type (function).
• unzip-xml-file (function).

---

5.1.1 Constants

Constant: +maximum-stage+ ¶

The largest number of bells supported, 24.

Package

roan.

Source

roan.lisp.

Constant: +minimum-stage+ ¶

The smallest number of bells supported, 2.

Package

roan.

Source

roan.lisp.

---

5.1.2 Special variables

Special Variable: *blueline-default-parameters* ¶

Package

roan.

Source

method.lisp.

Special Variable: *cross-character* ¶

The character used by default as “cross” when writing place notation. Must be a character designator for one of @code{#\x}, @code{#\X} or @code{#\-}. Its initial default value is a lower case @samp{x}, @code{#\x}.

Package

roan.

Source

roan.lisp.

Special Variable: *default-stage* ¶

An integer, the default value for optional or keyword arguments to many functions that must have a stage specified. @xref{write-row,,@code{write-row}}, @ref{row-string,,@code{row-string}}, @ref{write-place-notation,,@code{write-place-notation}} and @ref{place-notation-string,,@code{place-notation-string}}.

Package

roan.

Source

roan.lisp.

Special Variable: *method-library-path* ¶

Package

roan.

Source

method.lisp.

Special Variable: *print-bells-upper-case* ¶

When printing bell names that are letters, whether or not to use upper case letters by default. It is a generalized boolean, with an initial default value of @code{t}.

Package

roan.

Source

roan.lisp.

---

5.1.3 Macros

Macro: do-hash-set ((var set &optional result-form) &body body) ¶

===lambda: ((var set &optional result-form) &body body)
Evaluates the @var{body}, an implicit @code{progn}, repeatedly with the symbol @code{var} bound to the elements of the @code{hash-set} @var{set}. Returns the result of evaluating @var{result-form}, which defaults to @code{nil}, after the last iteration. A value may be returned by using @code{return} or @code{return-from nil}, in which case @var{result-form} is not evaluated. The order in which the elements of @var{set} are bound to @code{var} for evaluating @var{body} is undefined. With one exception the behavior is undefined if @var{body} attempts to modify the contents of @var{set}: @var{function} may call @code{hash-set-delete} to delete the current element, but no other. A @code{type-error} is signaled if @var{set} is not a @code{hash-set}.
@example
@group
(let ((r nil))
(do-hash-set (e (hash-set !135246 !123456 !531246) r)
(push (list e (in-course-p e) r))))
@result{} ((!531246 nil) (!123456 t) (!135246 nil))
@end group
@end example

Package

roan.

Source

util.lisp.

Macro: permutef (place &rest changes) ¶

===lambda: (row &rest changes)
Permutes @var{row}, which should be a location suitable as the first argument to @code{setf} containing a @code{row}, by @var{changes}, updating @var{row} to contain the result, and returns it. Signals a @code{type-error} if the value @var{row} contains is not a @code{row} or if any of the @var{changes} are not @code{row}s.

Package

roan.

Source

roan.lisp.

Macro: roan-syntax (&optional on-off modify) ¶

Turns on or off the read macros for @samp{!} and @samp{#!}, for reading rows and place notation.

If the generalized boolean @var{on-off} is true, the default, it turns on these read macros. Unless the generalized boolean @var{modify} is false, the default, it first pushes the current read table onto a stack, modifying a copy of it and making that copy the current read table. If @var{modify} is true it makes no copy and instead modifies the current readtable in place.

If @var{on-off} is false it restores the previous readtable by popping the stack. If the stack is empty it sets the readtable to a new, standard one. When @var{on-off} is false @var{modify} is ignored.

This is performed in an @code{eval-when} context to ensure it happens at compile time as well as load and execute time.

An alternative to using @code{roan-syntax} is to use @url{https://github.com/melisgl/named-readtables/, Named Readtables}. Roan defines two such readtables with names @code{:roan} and @code{:roan+interpol}. The former augments the initial Common Lisp read table with Roan’s read macros, and the latter also adds the syntax from @url{http://edicl.github.io/cl-interpol/,CL-INTERPOL}.

Package

roan.

Source

readtables.lisp.

---

5.1.4 Setf expanders

Setf Expander: (setf match-counter-handstroke-p) (counter) ¶

Package

roan.

Source

pattern.lisp.

Reader

match-counter-handstroke-p (function).

Setf Expander: (setf method-class) (method) ¶

Package

roan.

Source

method.lisp.

Reader

method-class (function).

Writer

set-method-class (function).

Setf Expander: (setf method-differential-p) (method) ¶

Package

roan.

Source

method.lisp.

Reader

method-differential-p (function).

Writer

set-method-differential-p (function).

Setf Expander: (setf method-jump-p) (method) ¶

Package

roan.

Source

method.lisp.

Reader

method-jump-p (function).

Writer

set-method-jump-p (function).

Setf Expander: (setf method-little-p) (method) ¶

Package

roan.

Source

method.lisp.

Reader

method-little-p (function).

Writer

set-method-little-p (function).

Setf Expander: (setf method-stage) (method) ¶

Package

roan.

Source

method.lisp.

Reader

method-stage (function).

Writer

set-method-stage (function).

Setf Expander: (setf method-title) (method) ¶

Package

roan.

Source

method.lisp.

Reader

method-title (function).

Writer

set-method-title (function).

---

5.1.5 Ordinary functions

Function: add-pattern (counter label pattern &optional double-row-p) ¶

Adds one or more patterns to those matched by the @code{match-counter} @var{count}.
A single pattern, @var{pattern}, is added, with label @var{label}, by @code{add-pattern}. If the generalized boolean @var{double-row-p} is true two rows (which typically should be consecutive) will be matched against @var{pattern}, and others one row; if not supplied @var{double-row-p} is @code{nil}. Multiple patterns may be added together with @code{add-patterns}: @var{lists} should be a list of lists, where the sublists are of the form @code{(@var{label} @var{pattern} &optional @var{double-row-p})}, and the patterns are added in the order given. In either case the @var{pattern} may be either a string or list structure that is a parsed pattern, such as returned by @code{parse-pattern}. If @var{label} is @code{equalp} to the label of a pattern already added to @var{counter} that pattern will be replaced, and its corresponding counts reset to zero. Either function reeturns @var{counter}. Either signals a @code{type-error} if @var{counter} is not a @code{match-counter}. Signals an error if any of the @var{pattern}s are not an appropriate pattern for the stage of @var{counter}.

Package

roan.

Source

pattern.lisp.

Function: add-patterns (counter lists) ¶

===merge: add-pattern

Package

roan.

Source

pattern.lisp.

Function: alter-stage (row &optional new-stage) ¶

If there is a @code{row}, @var{r}, of stage @var{new-stage} such that
@code{(equalp (permute (rounds @var{new-stage}) @var{r}) @var{row})} then returns @var{r}, and otherwise @code{nil}. That is, it returns a row of the @var{new-stage} such that the first bells are as in @var{row}, and any new or omitted bells are in rounds order. If not supplied @var{new-stage} defaults to the current value of @code{*default-stage*}. Signals a @code{type-err} if @var{row} is not a @code{row} or @var{new-stage} is not a @code{stage}.
@example
@group
(alter-stage !54321 10) @result{} !5432167890
(alter-stage !5432167890 6) @result{} !543216
(alter-stage !54321 4) @result{} nil
(alter-stage !5432167890 4) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: bell-at-position (row position) ¶

The @code{bell-at-position} function returns the @code{bell} (that is, a small integer) at the given @var{position} in the @var{row}. The @code{position-of-bell} function returns position of @var{bell} in @var{row}, or @code{nil} if @var{bell} does not appear in @var{row}. The indexing into @var{row} is zero-based; so, for example, the leading bell is at position 0, not 1. Signals an error if @var{row} is not a @code{row}, or if @var{position} is not a non-negative integer or is too large for the stage of @var{row} @example
@group
(bell-at-position !13572468 3) @result{} 6
(bell-name (bell-at-position !13572468 3)
@result{} #\7
(position-of-bell 6 !13572468) @result{} 3
(position-of-bell (bell-from-name #7) !13572468)
@result{} 3
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: bell-from-name (char) ¶

Returns the @code{bell} denoted by the character designator @var{char}, or @code{nil} if it is not a character designator denoting a bell. The determination is case-insensitive. @example
@group
(bell-from-name "8") @result{} 7
(bell-from-name "E") @result{} 10
(map ’list #’bell-from-name "135246") @result{} (0 2 4 1 3 5)
(bell-from-name "%") @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: bell-name (bell &optional upper-case) ¶

Returns a character denoting this @var{bell}, or @code{nil} if @var{bell} is not a @code{bell}. If the character is alphabetic, an upper case letter is returned if the generalized boolean @var{upper-case} is true, and otherwise a lower case letter. If @var{upper-case} is not supplied it defaults to the current value of @code{*print-bells-upper-case*}.
@example
@group
(bell-name 0) @result{} #\1
(map ’string #’bell-name
(loop for i from 0 below +maximum-stage+
collect i))
@result{} "1234567890ETABCDFGHJKLMN"
(bell-name -1) @result{} nil
(bell-name +maximum-stage+) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: bells-list (row) ¶

The @code{bells-list} function returns a fresh list of @code{bell}s (small, non-negative integers, zero-based), the bells of @var{row}, in the same order that they appear in @var{row}. The @code{bells-vector} function returns a vector of @code{bell}s (small, non-negative integers, zero-based), the bells of @var{row}, in the same order that they appear in @var{row}. If @var{vector} is not supplied or is @code{nil} a freshly created, simple general vector is returned.
@example
@group
(bells-list !13572468) @result{} (0 2 4 6 1 3 5 7)
(bells-vector !142536) @result{} #(0 3 1 4 2 5)
@end group
@end example

If a non-nil @var{vector} is supplied the @code{bell}s are copied into it and it is returned. If @var{vector} is longer than the stage of @var{row} only the first elements of @var{vector}, as many as the stage of @var{row}, are over-written; the rest are unchanged. If @var{vector} is shorter than the stage of @var{row}, then, if it is adjustable, it is adjusted to be exactly as long as the stage of @var{row}, and otherwise an error is signaled without any modifications made to the contents of @var{vector} or its fill-pointer, if any. If @var{vector} has a fill-pointer and is long enough to hold all the bells of @var{row}, possibly after adjustment, its fill-pointer is set to the stage of @var{row}.

A @code{type-error} is signaled if @var{row} is not a @code{row}. An error is signled if @var{vector} is neither @code{nil} nor a @code{vector} with an element type that is a supertype of @code{bell}, and of sufficient length or adjustable.

Package

roan.

Source

roan.lisp.

Function: bells-vector (row &optional vector) ¶

===merge: bells-list

Package

roan.

Source

roan.lisp.

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

Draws the blue line of @var{method} as a Scalable Vector Graphics (SVG) image. The @var{method} should have its stage and place notation set. While Roan only writes SVG format images, many other pieces of software, such as @url{https://imagemagick.org/,ImageMagick}, are able to convert SVG images to other formats.

The @var{destination} can be
@itemize
@item
A text stream, open for writing:
the SVG will be written to this stream, and the stream is returned as the value of the call to @code{blueline}.

@item
The symbol @code{t}:
the SVG will be written to @code{*standard-output*}, and the value of @code{*standard-output*} is returned as the value of the
call to @code{blueline}.

@item
A pathname:
an SVG file will be written to this pathname, which will be opened with
@code{if-exists :supersede}, and the truename of the resulting file is returned.

@item
A string with a fill pointer:
the SVG will be appended to this string, as by @code{vector-push-extend}, which is returned.

@item
The symbol @code{nil}:
the SVG will be written to a new string, which is returned.
@end itemize

Several keyword parameters can be used to control details of the image produced
@table @var
@item 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 @var{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 @code{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 @code{: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 @var{layout} is @code{100}.

@item hunt-bell
Controls which hunt bells are displayed specially. Those not displayed specially, are treated as working bells. If a @code{bell}, that is, a small, non-negative integer less than the stage of @var{method}, this is the hunt bell displayed specially; a list of @code{bell}s may also be supplied, for multiple hunt bells. If a supplied @code{bell} is not actually a hunt bell of @var{method} it is ignored. The keyword @code{first} is equivalent to supplying whatever the smallest hunt bell of @var{method} is. The keyword @code{:all} is equivalent to supplying a list of all the hunt bells of @var{method}. The keyword @code{:working} treats all of the hunt bells as working bells. If @var{hunt-bell} is @code{nil} no hunt bells are displayed. The default value for @var{hunt-bell} is @code{:first}.

@item 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 @code{bell}, or a list thereof, or one of the keywords @code{:natural}, @code{:largest} or @code{:smallest}. If @code{: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 @var{working-bell} is @code{:natural}.

@item figures
If non-null figures will also be drawn, in addition to the blue line. If @code{t} they will be drawn for all leads. If @code{:lead} only for the first lead of each cycle. If @code{:half} and the @var{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 @code{:half} is equivalent to @code{:lead}. If @code{:head} the figures will only be drawn for the first lead head in each column. The default value for @var{figures} is @code{nil}.

@item place-notation
if non-null the place notation will be drawn to the left of the blue lines. If @code{t} it will be drawn for the first lead in each column. If @code{:lead} it will only be drawn for the first columnn. If @code{:half} and the @var{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 @code{:half} is equivalent to @code{:lead}. The default value for @code{place-notation} is @code{nil}.

@item place-bells
May have a value of @code{nil}, @code{:dot} or @code{:label}. If non-null dots are drawn where each place bell starts, and if @code{:label} a label is drawn to the right of the blue line at each place bell’s start. The default value for @var{place-bells} is @code{:label}.
@end table

For an example, execute something like the following, and open the resulting file in a browser:
@example
@group
(blueline #P"/tmp/bastow.svg"
(lookup-method-by-title "Bastow Little Bob Minor")
:layout 12
:figures :lead
:place-notation :half)
@end group
@end example

Default values for the keyword arguments to this function can be set by assigning a property list of keywords and values to the variable @code{*blueline-default-parameters*}. @example
@group
(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"))))
@result{} t
@end group
@end example

Signals a @code{type-error} if @var{destination} is not a stream, pathname, string with a fill pointer or one of the symbols @code{t} or @code{nil}; if @var{method} is not a @code{method}; if @var{layout} is not non-negative integer, @code{nil} or the keyword @code{:grid}; if @var{hunt-bell} is not a @code{bell}, list of bells, @code{nil} or one one of the keywords @code{:first}, @code{:all} or @code{:working}. if @var{working-bell} is not a @code{bell}, list of bells, or one of the symbols @code{:natural}, @code{:largest} or @code{smallest}; if @var{figures} is not one of the keywords @code{:none}, @code{:head}, @code{:half}, @code{:lead} or @code{:always}; if @var{place-notation} is not one of the keywords @code{:none}, @code{:half}, @code{:lead} or @code{:always}; or if @var{place-bells} is not @code{nil} or one of the keywords @code{:dot} or@code{:label}. Signals a @code{no-place-notation-error} if @var{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.

Package

roan.

Source

method.lisp.

Function: call (place-notation &key from-end offset fraction replace following following-replace) ¶

Creates and returns a @code{call}, which modifies the changes of a lead of a @code{method}. The @var{place-notation} argument is a string of place notation, the changes corresponding to which will be added to or replace changes in a a lead of the @code{method} when applying the @code{code}. The @var{place-notation} may be @code{nil}, in which case no changes are added or replace existing ones. The @var{offset}, a non-negative integer, is the position at which to begin modifying the lead, and is measured from the beginning of the lead if the generalized boolean @var{from-end} is false, and from the end, otherwise. This can be further modifed by @var{fraction} which is multiplied by the lead length; the offset is counted forward or backward from that product. The @code{fraction}, if non-nill, must be a ratio greater than @code{0} and less than @code{1}, whose denominator evenly divides the lead length. The non-negative integer @var{replace} is the number of changes in the lead to be deleted or replaced. It is typically equal to the length of @var{changes}, which results in exact replacement of changes in the lead, but may be greater or less than that length, in which case the resulting lead is of a different length than a plain lead.

If either or both of @var{following} or @var{following-replace} are supplied the call is intended to also apply to the subsequent lead. These operate just like @var{place-notation} and @var{replace}, but on the subsequent lead, and always at the begining of that lead. This use also depends upon the caller of @code{call-apply} making correct use of its second return value.

If @var{replace} is not supplied or is @code{nil} it defaults to the number of changes represented by the @var{place-notation}. If @var{offset} is not supplied or is @code{nil}, it defaults to @code{0} if @var{from-end} is false, and otherwise to the value of @var{replace}, which may itself have been defaulted from the value of @var{place-notation}. The default value of @var{from-end} is @code{t}. The default value of @var{fraction} is @code{nil}. If @var{following} is supplied but @var{following-replace} is not, @var{following-replace} defaults to the number of changes represetned by @var{following}. If @var{following-replace} is supplied but @var{following} is not, @var{following} defaults to @code{nil}.

A @code{parse-error} is signaled if either @var{place-notation} or @var{following} is non-@code{nil} but not interpretable as place notation at the stage of @var{method}. A @code{type-error} is signaled if @var{offset} is supplied and is neither @code{nil} nor a non-negative integer; if @var{replace} is supplied and is neither @code{nil} nor a non-negative integer; @var{fraction} is supplied and is neither @code{nil} nor a ratio between @code{0} and @code{1}, exclusive; or if @var{following-replace} is supplied and is neither @code{nil} nor a non-negative integer.

Package

roan.

Source

method.lisp.

Function: call-application-error (call method message &rest args) ¶

Package

roan.

Source

method.lisp.

Function: call-apply (method &rest calls) ¶

Applies zero or more @var{calls} to a lead of @var{method}. Returns two values, the first a list of @code{row}s constituting the changes of the modified lead and the second @code{nil} or a @code{call}, such that the call should be applied to the succeeding lead. This second value is only non-nil for complex calls that affect two consecutive leads, as are encountered in doubles variations. One or more of the @var{calls} may be @code{nil}, in which case they are ignored, just as if they had not been supplied. If no non-nil @var{calls} are supplied returns a list of the changes constituting a plain lead of @var{method}.

When multiple @var{calls} are supplied the indices of all are computed relative to the length and position within the plain lead, before the application of any others of the calls. For example, a half-lead call that replaces the 7th’s in Cambridge Major continues to replace that change even if an earlier call removes or adds several changes.

Signals a @code{type-error} if @var{method} is not a @code{method} or if any of the @var{calls} are neither a @code{call} nor @code{nil}. Signals a @code{parse-error} if @var{method} does not have its stage or place-notation defined. Signals a @code{call-application-error} in any of the following circumstances: if the stage of @var{method} is such that the place notation or following place notation of one or more of the @var{calls} is inapplicable; if an attempt is made to apply a fractional lead @code{call} where the denominator of the fraction does not evenly divide the lead length; if the @code{call} would be positioned, or replace changes, that lie outside the lead; if a @code{call} with following changes does not replace changes up to the end of the first lead, or an attempt is made to applly two or more @code{call}s with following place notation to the same lead.

Package

roan.

Source

method.lisp.

Function: canonicalize-method-place-notation (method &rest keys &key comma &allow-other-keys) ¶

===lambda: (method &key comma elide cross upper-case allow-jump-changes)
Replaces @var{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 @code{:lead-end} format as for @code{write-place-notation}, partitioned with a comma, if possible, with upper case letters for high number bells and a lower case @samp{x} for cross. The behavior can be changed by passing keyword arguments as for @code{write-place-notation}. If @var{method} has no place-notation or no stage, this function does nothing, and returns @code{nil}; in particular, if there is place-notation but no stage, the place-notation will be unchanged.

Signals a @code{type-error} if @var{method} is not a @code{method}, and signals an error if any of the keyword arguments do not have suitable values for passing to @code{write-place-notation}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage. @xref{canonicalize-place-notation} and @ref{write-place-notation}.
@example
@group
(let ((m (method :stage 6
:place-notation "-16.X.14-6X16"))) (canonicalize-method-place-notation m)
(method-place-notation m))
@result{} "x1x4,6"
@end group
@end example

Package

roan.

Source

method.lisp.

Function: canonicalize-place-notation (string-or-changes &rest keys &key stage comma &allow-other-keys) ¶

===lambda: (string-or-changes &key stage comma elide cross upper-case allow-jump-changes) Returns a string representing the place notation in a canonical form. If @var{string-or-changes} is a string it should be parseable as place notation at @var{stage}, which defaults to the current value of @code{*default-stage*}, and otherwise it should be a list of @code{row}s, all of the same stage. Unless overridden by the other keyword arguments, which have the same effects as for @code{write-place-notation}, the canonical form is a compact one using lower case @samp{x} for cross, upper case letters for high place names, @code{lead-end} style elision of external places, a comma for unfolding if possible, and notating jump changes as jumps within parentheses.

Signals a @code{type-error} if @var{string-or-changes} is neither a string nor a list, or if it is a list containing anything other than @code{row}s. Signals a @code{parse-error} if @var{string-or-changes} is a string and is not parseable at @var{stage}, or if @var{stage} is not a @code{stage}. Signals an error if @var{cross} is not a suitable character designator, if @var{allow-jump-changes} is not one of its allowed values, or if @var{string-or-changes} is a list containing @code{row}s of different stages. @xref{write-place-notation}.
@example
@group
(multiple-value-list
(canonicalize-place-notation "-16.X.14-6X1" :stage 6))
@result{} ("x1x4,6" t)
(multiple-value-list
(canonicalize-place-notation "-3-[134265]-1T-" :stage 12))
@result{} ("x3x(24)x1x" nil)
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: changep (row) ¶

True if and only if @var{row} is a @code{row} representing a permutation with no bell moving more than one place.
@example
@group
(changep !214365) @result{} t
(changep !143265) @result{} nil
(changep |214365|) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: class-name (class) ¶

Package

roan.

Source

method.lisp.

Function: classify-method (method) ¶

Assigns the classification fields of @var{method} to match the classification assigned by the Central Council of Church Bell Ringers @url{https://cccbr.github.io/method_ringing_framework/, Framework for Method Ringing} (FMR) for the place notation contained in that @code{method}, and returns the method. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{no-place-notation-error} if either the stage or place notation of @var{method} are not set. Signals a @code{parse-error} if the value of the place notation field cannot be interpreted as place notation at the stage of @var{method}.
@example
@group
(method-title (classify-method
(method :stage 8 :place-notation "x3x6x5x45,2"))
t)
@result{} "Unnamed Differential Little Surprise Major"
@end group
@end example

Package

roan.

Source

method.lisp.

Function: comparable-method-name (string) ¶

If @var{string} is a suitable name for a method, returns a version appropriate for
comparison with other comparable names, and otherwise returns @code{nil}.

The Central Council of Church Bell Ringers
@url{https://cccbr.github.io/method_ringing_framework/, 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 @code{type-error} if @var{string} is not a string.
@example
@group
(comparable-method-name "New Cambridge")
@result{} "new cambridge"
(comparable-method-name "London No.3")
@result{} "london no 3"
(comparable-method-name "m@U{00E4}k@U{010D}e@U{0148} E=mc@U{00B2}")
@result{} "makcen e mc2"
(comparable-method-name "Two is Too Many Spaces")
@result{} nil
(comparable-method-name "@U{0395}@U{03BB}@U{03BB}@U{03B7}@U{03BD}@U{03B9}@U{03BA}@U{03AC} is Greek to me") @result{} nil
@end group
@end example

Package

roan.

Source

method.lisp.

Function: copy-method (method) ¶

Returns a new @code{method} whose name and place notation are @code{equal} to those of @var{method}, and with the same classification as @var{method}. Signals a @code{type-error} if @var{method} is not a @code{method}.

Package

roan.

Source

method.lisp.

Function: cycles (row) ¶

Returns a list of lists of bells. Each of the sublists is the orbit of all of its elements in @var{row}. One cycles are included. Thus, if @var{row} is a lead head, all the sublists of length one are hunt bells, all the rest being working bells; if there are two or more sublists of length greater than one the corresponding method is differential. The resulting sublists are each ordered such that the first bell is the lowest numbered bell in that cycle, and the remaining bells occur in the order in which a bell traverses the cycle. Within the top level list, the sublists are ordered such that the first bell of each sublist appear in ascending numerical order.
@example
@group
(cycles !13572468) @result{} ((0) (1 4 2) (3 5 6) (7))
(format nil "~@{(~@{~C~^,~@})~^, ~@}"
(mapcar #’(lambda (x) (mapcar #’bell-name x))
(cycles !13572468)))
@result{} "(1), (2,5,3), (4,6,7), (8)"
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: fch-group (item &optional higher-stage out-of-course) ¶

Returns an @code{fch-group} described by the provided arguments. The @var{item} can be either a @code{row} or a string designator.

If @var{item} is a @code{row} the @code{fch-group} that contains that row among its elements is returned. If it is not at an even stage, major or above, or if it is at an even stage royal or above but with any of the bells conventionally called the seven (and represented in Roan by the integer @code{6}) or higher out of their rounds positions, @code{nil} is returned. If @var{item} is a @code{row} at an even stage maximus or above, with the back bells in their home positions, it is treated as if it were the equivalent royal @code{row}. When @var{item} is a @code{row} neither @var{higher-stage} nor @var{out-of-course} may be supplied.

If @var{item} is a string designator the @code{fch-group} that has that name is returned. If the generalized boolean @var{higher-stage} is true a higher stage @code{fch-group} is returned and others a major one. In the case of higher stage groups if the generalized boolean @var{out-of-course} is true the group with the given name containing only out of course elements is returned, and otherwise the one with only in course elements. Both @var{higher-stage} and @var{out-of-course} default to @code{nil} if not supplied. If there is no @code{fch-group} with name @var{item} and the given properties @code{nil} is returned.

Signals a @code{type-error} if @var{item} is neither a @code{row} nor a string designator. Signals an error if @var{item} is a @code{row} and @var{higher-stage} or @var{out-of-course} is supplied.
@example
@group
(let ((g (fch-group !2436578)))
(list (fch-group-name g)
(fch-group-parity g)
(stage (first (fch-group-elements g)))))
@result{} ("B" nil 8)
(fch-group "a1" t nil) @result{} nil
(fch-group-elements (fch-group "a1" t t)) @result{} (!1234657890)
@end group
@end example

Package

roan.

Source

method.lisp.

Reader: fch-group-elements (instance) ¶

Package

roan.

Source

method.lisp.

Target Slot

elements.

Reader: fch-group-name (instance) ¶

Package

roan.

Source

method.lisp.

Target Slot

name.

Reader: fch-group-parity (instance) ¶

Package

roan.

Source

method.lisp.

Target Slot

parity.

Function: fch-groups-string (collection &rest more-collections) ¶

Returns a string succinctly describing a set of @code{fch-group}s, in a conventional order. The set of @code{fch-group}s is the union of all those contained in the arguments, each of which should be a sequence or @code{hash-set}, all of whose elements are @code{fch-group}s. The resulting string contains the names of the distinct @code{fch-group}s. If there are no groups @code{nil}, rather than an empty string, is returned.

For higher stages there are two sequences of group names in the string, separated by a solidus (@samp{/}); those before the solidus are in course and those after it out of course. For example, @code{"B/Da1"} represents the higher course in course elements of group B and out of course elements of groups D and a1.

The group names are presented in the conventional order. For major the groups containing in course, tenors together elements appear first, in alphabetical order; followed by those all of whose tenors together elements are out of course, in alphabetical order; finally followed by those all of whose elements are tenors parted. For higher stages the capital letter groups in each half of the string come first, in alphabetical order, followed by those with lower case names. Note that a lower case name can never appear before the solidus.

Signals a @code{type-error} if any of the arguments are not sequences or @code{hash-set}s, or if any of their elements is not an @code{fch-group}. Signals a @code{mixed-stage-fch-groups-error} if some of the elements are major and some are higher stage @code{fch-group}s.
@example
@group
(fch-groups-string (list (fch-group "a") (fch-group "B")))
@result{} "Ba"
(fch-groups-string #((fch-group "D" t t)
(fch-group "a1" t t))
(hash-set (fch-group "B" t)))
@result{} "B/Da1"
(fch-groups-string (list (fch-group "T" t nil)))
@result{} "T/"
(fch-groups-string (list (fch-group "T" t t)))
@result{} "/T"
@end group
@end example

Package

roan.

Source

method.lisp.

Function: format-pattern (tree &optional upper-case) ¶

Returns a string that if parsed with @code{parse-pattern}, would return the parse tree @var{tree}. Note that the generation of a suitable string from @var{tree} is not unique, and this function simply returns one of potentially many equivalent possibilities. The case of any bells represented by letters is controlled by @var{upper-case}, which defaults to the current value of @code{*print-bells-upper-case*}. Signals an error if tree is not a parse tree for a pattern.
@example
(format-pattern ’(:sequence 0 1 2 :any 7) t) @result{} "123*8"
@end example

Package

roan.

Source

pattern.lisp.

Function: hash-set (&rest initial-elements) ¶

Returns a new @code{hash-set} containing the elements of @var{initial-elements}. If no @var{initial-elements} are supplied, the returned @code{hash-set} is empty. @example
@group
(hash-set 1 :foo 2 :foo 1) @result{} #<HASH-SET 3>
(hash-set-elements (hash-set 1 :foo 2 :foo 1))
@result{} (1 2 :foo)
(hash-set-elements (hash-set)) @result{} nil
@end group
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-adjoin (set &rest elements) ¶

Returns a @code{hash-set} that contains all the elements of @var{set} to which have been added the @var{elements}, or the elements of the @var{list}. As usual duplicate elements are not added, though exactly which of any potential duplicates are retained is undefined. The @code{hash-set-adjoin} and @code{hash-set-adjoin-list-elements} functions do not modify @var{set} but might return it if no changes are needed; that is, the caller cannot depend upon it necessarily being a fresh copy. The @code{hash-set-nadjoin} and @code{hash-set-nadjoin-list-elements} functions modify @var{set} (if one or more of the elements is not already contained therein) and return it. Note that @code{hash-set-[n]adjoin-list-elements} differs from @code{(apply #’hash-set-[n]adjoin ...)} in that the latter can adjoin at most @code{call-arguments-limit} elements. Signals a @code{type-error} if @var{set} is not a @code{hash-set}.
@example
@group
(hash-set-elements (hash-set-adjoin (hash-set 1 2 3) 4 3 2))
@result{} (3 4 1 2)
@end group
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-adjoin-list-elements (set list) ¶

===merge: hash-set-adjoin 1

Package

roan.

Source

util.lisp.

Function: hash-set-clear (set) ¶

Removes all elements from @var{set}, and then returns the now empty @code{hash-set}. Signals a @code{type-error} if @var{set} is not a @code{hash-set}.

Package

roan.

Source

util.lisp.

Function: hash-set-copy (set &rest keys &key size rehash-size rehash-threshold) ¶

===lambda: (set &key size rehash-size rehash-threshold)
Returns a new @code{hash-set} containing the same elements as the @code{hash-set} @var{set}. If any of @var{size}, @var{rehash-size} or @var{rehash-threshold} are supplied they have the same meanings as the eponymous arguments to @code{copy-hash-table}. A @code{type-error} is signaled if @var{set} is not a @code{hash-set}.

Package

roan.

Source

util.lisp.

Function: hash-set-count (set) ¶

Returns a non-negative integer, the number of elements the @code{hash-set} @var{set} contains. Signals a @code{type-error} if @var{set} is not a @code{hash-set}. @example
@group
(hash-set-count (hash-set !1234 !1342 !1234)) @result{} 2
(hash-set-count (hash-set)) @result{} 0
@end group
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-delete (set &rest elements) ¶

Deletes from the @code{hash-set} @var{set} all elements @code{equalp} to elements of @var{elements}, and returns the modified set. Signals a @code{type-error} if @var{set} is not a @code{hash-set}.

Package

roan.

Source

util.lisp.

Function: hash-set-difference (set &rest more-sets) ¶

Returns a @code{hash-set} containing all the elements of @var{set} that are not contained in any of @var{more-sets}. The @code{hash-set-difference} version returns a fresh @code{hash-set}, and does not modify @var{set} or any of the @var{more-sets}. The @code{hash-set-ndifference} version modifies and returns @var{set}, but does not modify any of @var{more-sets}. Signals a @code{type-error} if @var{set} or any of @var{more-sets} are not @code{hash-set}s.
@example
@group
(hash-set-elements
(hash-set-difference
(hash-set !12345 !23451 !34512 !45123)
(hash-set !23451 !54321 !12345)))
@result{} (!34512 !45123)
@end group
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-elements (set) ¶

Returns a list of all the elements of the @code{hash-set} @var{set}. The order of the elements in the list is undefined, and may vary between two invocations of @code{hash-set-elements}. Signals a @code{type-error} if @var{set} is not a @code{hash-set}.
@example
(hash-set-elements (hash-set 1 2 1 3 1)) @result{} (3 2 1)
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-empty-p (set) ¶

True if and only if the @code{hash-set} @var{set} contains no elements. Signals a @code{type-error} if @var{set} is not a @code{hash-set}.

Package

roan.

Source

util.lisp.

Function: hash-set-intersection (set &rest more-sets) ¶

Returns a @code{hash-set} such at all of its elements are also elements of @var{set} and of all the @var{more-sets}. The @code{hash-set-intersection} function does not modify @var{set} or any of the @var{more-sets}, but may return any one of them unmodified if appropriate; the caller should not assume a fresh @code{hash-set} is returned. The @code{hash-set-nintersection} function always returns @var{set}, modifying it if necessary; it does not modify any of the @var{more-sets}. Signals a @code{type-error} if @var{set} or any of the @var{more-sets} are not @code{hash-set}s.
@example
@group
(coerce
(hash-set-elements
(hash-set-intersection
(apply #’hash-set (coerce "abcdef" ’list))
(apply #’hash-set (coerce "ACEG" ’list))))
’string)
@result{} "EaC"
@end group
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-member (item set) ¶

True if and only if @var{item} is an element of the @code{hash-set} @var{set}. Signals a @code{type-error} if @var{set} is not a @code{hash-set}. @example
@group
(hash-set-member !1342 (hash-set !1243 !1342)) @result{} t (hash-set-member !1342 (hash-set !12435 !12425)) @result{} nil
@end group
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-nadjoin (set &rest elements) ¶

===merge: hash-set-adjoin 2

Package

roan.

Source

util.lisp.

Function: hash-set-nadjoin-list-elements (set list) ¶

===merge: hash-set-adjoin 3

Package

roan.

Source

util.lisp.

Function: hash-set-ndifference (set &rest more-sets) ¶

===merge: hash-set-difference

Package

roan.

Source

util.lisp.

Function: hash-set-nintersection (set &rest more-sets) ¶

===merge: hash-set-intersection

Package

roan.

Source

util.lisp.

Function: hash-set-nunion (set &rest more-sets) ¶

===merge: hash-set-union

Package

roan.

Source

util.lisp.

Function: hash-set-p (object) ¶

Package

roan.

Source

util.lisp.

Function: hash-set-pop (set &optional error-p empty-value) ¶

Deletes an element from @var{set} and returns it. The particular element chosen to be removed and returned is undefined. If @var{set} is empty returns @var{empty-value} if the generalized Boolean @var{error-p} is false and otherwise signals an error. By default @var{error-p} is true and @var{empty-value} is @code{nil}. Signals a @code{type-error} if @var{set} is not a @code{hash-set}.

Package

roan.

Source

util.lisp.

Function: hash-set-proper-subset-p (subset superset) ¶

===merge: hash-set-subset-p

Package

roan.

Source

util.lisp.

Function: hash-set-remove (set &rest elements) ¶

Returns a new @code{hash-set} that contains all the elements of @var{set} that are not @code{equalp} to any of the @var{elements}. Signals a @code{type-error} if @var{set} is not a @code{hash-set}.

Package

roan.

Source

util.lisp.

Function: hash-set-subset-p (subset superset) ¶

The @code{hash-set-subset-p} predicate is true if and only if all elements of @var{subset} occur in @var{superset}. The @code{hash-set-proper-subset-p} predicate is true if and only that is the case and further that @code{subset} does not contain all the elements of @var{superset}. @code{type-error} is signaled if either argument is not a @code{hash-set}.
@example
@group
(hash-set-subset-p (hash-set 1) (hash-set 2 1) @result{} t
(hash-set-proper-subset-p (hash-set 1) (hash-set 2 1) @result{} t
(hash-set-subset-p (hash-set 1 2) (hash-set 2 1) @result{} t (hash-set-proper-subset-p (hash-set 1 2) (hash-set 2 1) @result{} nil (hash-set-subset-p (hash-set 1 3) (hash-set 2 1) @result{} nil (hash-set-proper-subset-p (hash-set 1 3) (hash-set 2 1) @result{} nil
@end group
@end example

Package

roan.

Source

util.lisp.

Function: hash-set-union (set &rest more-sets) ¶

Returns a @code{hash-set} containing all the elements that appear in @var{set} or in any of the @var{more-sets}. The @code{hash-set-union} function does not modify @var{set} or any of the @var{more-sets}, but may return any one of them unmodified if appropriate; the caller should not assume a fresh @code{hash-set} is returned. The @code{hash-set-nunion} function always returns @var{set}, modifying it if necessary; it does not modify any of the @var{more-sets}. Signals a @code{type-error} if @var{set} or any of the @var{more-sets} are not @code{hash-set}s.
@example
@group
(coerce
(hash-set-elements
(hash-set-union
(apply #’hash-set (coerce "abcdef" ’list))
(apply #’hash-set (coerce "ACEG" ’list))))
’string)
@result{} "FaeGbcd"
(hash-set-empty-p (hash-set-union)) @result{} t
@end group
@end example

Package

roan.

Source

util.lisp.

Function: in-course-p (row) ¶

True if and only if @var{row} is a @code{row} representing an even permutation. @example
@group
(in-course-p !132546) @result{} t
(in-course-p !214365) @result{} nil
(in-course-p "132546") @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: inverse (row) ¶

Returns the inverse of the @code{row} @var{row}. That is, the @code{row}, @var{r}, such that when @var{row} is permuted by @var{r}, the result is rounds. A theorem of group theory implies also that when @var{r} is permuted by @var{row} the result will also be rounds. Signals a @code{type-error} if @var{row} is not a @code{row}.
@example
@group
(inverse !13427586) @result{} !14236857
(inverse !14236857) @result{} !13427586
(inverse !12436587) @result{} !12436587
(inverse !12345678) @result{} !12345678
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: involutionp (row) ¶

True if and only if @var{row} is a @code{row} that is its own inverse. @example
@group
(involutionp !13248765) @result{} t
(involutionp !13425678) @result{} nil
(involutionp nil) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: lookup-method-by-title (title &optional errorp) ¶

===merge: lookup-methods 1

Package

roan.

Source

method.lisp.

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 @var{key}. The @var{title-or-method} may be a string or a @code{method}. If a string, it is the title of the method about which the metadata is sought. If the metadata indicated by @var{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 @var{key} is a not yet supported type of metadata or if @code{title-or-method} does not correspond to any method in the library, @code{nil} is returned.

Currently supported values for @var{key} are
@table @code
@item :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.

@item :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.

@item :complib-id
Returns an integer, which is used to index information about the method on @url{https://complib.org/,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 @code{:complib-id}, while all those from the Council do.
@end table
Others may be added in future versions of Roan.

Signals a @code{type-error} if @var{title-or-method} is neither a string nor a @code{method}, or if @var{key} is not a keyword.
@example
@group
(lookup-method-info "Advent Surprise Major" :first-towerbell-peal)
@result{} "1988-07-31 Boston, MA (Advent)"
(lookup-method-info
(first (lookup-methods-by-notation "36x56.4.5x5.6x4x5x4x7,8"))
:complib-id)
@result{} 20042
(lookup-method-info "Advent Surprise Major"
:no-such-info)
@result{} nil
@end group
@end example

Package

roan.

Source

method.lisp.

Function: lookup-methods (&key name jump differential little class stage) ¶

===summary===
Roan provides a library of method definitions, derived from the @url{https://cccbr.github.io/methods-library/index.html,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 (@ref{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 @code{update-method-library}. The Council typically updates their library weekly.

The library can be interrogated with the @code{lookup-methods}, @code{lookup-method-by-title} and @code{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 @code{lookup-method-info}.
===endsummary===
The @code{lookup-methods} function returns a list of named @code{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 @var{name} is provided, it should be a string or @code{nil}, and all the methods returned will have that name. The Central Council of Church Bell Ringers @url{https://cccbr.github.io/method_ringing_framework/, 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, @code{"London No.3"} and @code{"London no 3"} are considered the same names. The @code{lookup-methods} function uses this mechanism. @xref{comparable-method-name}.

The @var{name} may also contain @samp{*} wildcard characters. Such a wildcard matches a series of zero or more consecutive characters. Since the @samp{*} is not a character allowed in method names by the FMR there is no ambiguity: occurrences of @samp{*} in @var{name} are always wildcard characters. Wildcards are applicable only to @var{name}, and not to any of the other arguments to @code{lookup-methods}.

If @var{stage} is provided, it should be a @code{stage}, that is a small integer. All the methods that are returned will have that stage. While a @code{method} object can have an indeterminate stage, represented by @code{nil}, all the methods returned by @code{lookup-methods} will have a definite stage, and @code{nil} is not an allowed value for the @var{stage} argument.

If @var{class} is provided, it should be @code{nil} or one of the keywords @code{:bob}, @code{:place}, @code{:surprise}, @code{:delight}, @code{:treble-bob}, @code{:treble-place}, @code{:alliance}, @code{:hybrid} or @code{:blank}. With the exception of @code{:blank}, all the methods returned will have the specified class. The value @code{:blank} matches either @code{nil}, meaning no explicit class, or @code{: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 @var{little}, @var{differential} and @var{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 @code{lookup-method-by-title}. The @var{title} should be a string. If a @code{method} with that title is in the library, it is returned. Otherwise @code{nil} is returned, unless the generalized Boolean @var{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 @code{lookup-method-by-title}.

If the place notation of a method is known, and its name in the library is sought, @code{lookup-methods-by-notation} is available. The @var{notation-or-changes} should be either a string, in which case it viewed as place notation, or a list of @code{rows}, representing changes all of the same stage. The @var{stage} should be a @code{stage}; if not provided or @code{nil} the current value of @code{*default-stage*} is used. If @var{notation-or-changes} is a list of changes, the value of @var{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 @code{lookup-methods} or @code{lookup-methods-by-notation}. Instances of the “same” method returned by different invocations of these functions will typically not be @code{eq}.

A @code{type-error} is signaled if @var{stage} is not a @code{stage} (or, in the case of @code{lookup-methods-by-notation}, @code{nil}); @var{name} is not a string or @code{nil}; @var{notation-or-changes} is neither a string nor a non-empty list of @code{row}s; @var{changes} is not a non-empty list of @code{row}s; or if @var{class} is not one the allowed values. A @code{parse-error} is signaled if @var{notation-or-changes} is a string and is not parseable as place notation at @var{stage}. An @code{error} is signaled if @var{changes} is a list of @code{row}s, but they are not all of stage @var{stage} (or of @code{*default-stage*} if @var{stage} is @code{nil}). A @code{method-library-error} is signaled if the method library file cannot be read or is of the wrong format.
@example
@group
(mapcar #’method-place-notation
(lookup-methods :name "Advent"
:class :surprise
:stage 8))
@result{} ("36x56.4.5x5.6x4x5x4x7,8")
(mapcar #’method-title
(lookup-methods :name "london no 3"
:class :surprise
:stage 10))
@result{} ("London No.3 Surprise Royal")
(method-place-notation
(lookup-method-by-title "Advent Surprise Major"))
@result{} "36x56.4.5x5.6x4x5x4x7,8"
(lookup-methods :name "No such method")
@result{} nil
@end group
@group
(mapcar #’method-title
(lookup-methods :name "Cambridge*"
:class :surprise
:stage 8))
@result{} ("Cambridge Blue Surprise Major"
"Cambridge Surprise Major"
"Cambridgeshire Surprise Major")
@end group
@group
(multiple-value-bind (n r)
(lookup-methods-by-notation "36x56.4.5x5.6x4x5x4x7,8" 8)
(list
(mapcar #’method-title n)
(mapcar #’method-title r)))
@result{} (("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)))
@result{} (("Reverse Original Singles")
("Original Singles"))
(method-place-notation
(lookup-method-by-title "Original Singles"))
@result{} "3.1"
@end group
@end example

Package

roan.

Source

method.lisp.

Function: lookup-methods-by-notation (notation-or-changes &optional stage) ¶

===merge: lookup-methods 2

Package

roan.

Source

method.lisp.

Function: make-hash-set (&rest keys &key size rehash-size rehash-threshold initial-elements) ¶

===lambda: (&key size rehash-size rehash-threshold initial-elements)
Returns a new @code{hash-set}. If @var{initial-elements} is supplied and non-nil,
it must be a list of elements that the return value will contain; otherwise an empty set is returned. If any of @var{size}, @var{rehash-size} or @var{rehash-threshold} are supplied they have meanings analagous to the eponymous arguments to @code{make-hash-table}.

Package

roan.

Source

util.lisp.

Function: make-match-counter (&optional stage) ¶

Returns a fresh @code{match-counter}, initially containing no patterns, that is configured to attempt to match patterns against @code{row}s of @var{stage} bells. If not supplied, @var{stage} defaults to the current value of @code{*default-stage*}. Attempts to add patterns only appropriate for a different stage or match rows of a different stage with @code{record-matches} will signal an error.

Package

roan.

Source

pattern.lisp.

Function: map-hash-set (function set) ¶

Calls @var{function} on each element of the @code{hash-set} @var{set}, and returns @code{nil}. The order in which the elements of @var{set} have @var{function} applied to them is undefined. With one exception, the behavior is undefined if @var{function} attempts to modify the contents of @var{set}: @var{function} may call @code{hash-set-delete} to delete the current element, but no other. A @code{type-error} is signaled if @var{set} is not a @code{hash-set}.
@example
@group
(let ((r nil))
(map-hash-set #’(lambda (e)
(push (list e (in-course-p e)) r))
(hash-set !135246 !123456 !531246))
r)
@result{} ((!135246 nil) (!531246 nil) (!123456 t))
@end group
@end example

Package

roan.

Source

util.lisp.

Function: match-counter-counts (counter &optional label) ¶

Returns three values, the number of times the pattern with label @code{equalp} to @var{label} in @var{counter} has matched @code{row}s presented to it with @code{record-matches} since @var{counter} was reset or the relevent pattern was added to it. The first return value is the total number of matches, the second the number of matches at handstroke, and the third the number of matches at backstroke. If no @var{label} is supplied it instead returns three a-lists mapping the labels of the patterns in @var{counter} to the number of matches, again total, handstroke and backstroke. The elements of these a-lists are in the order in which the corresponding patterns were first added to @var{counter}. Returns @code{nil} if there is no pattern labeled @var{label}. Signals a @code{type-error} if @var{counter} is not a @code{match-counter}.

Package

roan.

Source

pattern.lisp.

Function: match-counter-handstroke-p (counter) ¶

Returns a generalized boolean indicating that the next row presented to @var{counter} will be a handstroke. Can be used with @code{setf} to tell @var{counter} whether or not it should consider the next row a handstroke or a backstroke. If not explicitly set again, either with @code{(setf match-counter-handstroke-p)}, or with the @var{handstroke-p} argument to @code{record-matches}, whether or not subsequent rows will be considered handstroke or backstroke will alternate. Signals a @code{type-error} if @var{counter} is not a @code{match-counter}.

Package

roan.

Source

pattern.lisp.

Setf expander for this function

(setf match-counter-handstroke-p).

Function: match-counter-labels (counter) ¶

Returns two lists, the labels of those patterns in @var{count} that are matched against a single row, and those that are matched against two rows. Both lists are in the order in which the corresponding patterns were first added to @var{counter}. Signals a @code{type-error} if @var{counter} is not a @code{match-counter}.

Package

roan.

Source

pattern.lisp.

Function: match-counter-pattern (counter label &optional as-string upper-case) ¶

Returns two values: the first is the pattern whose label in @var{count} is @code{equalp} to @var{label}, if any, and otherwise @code{nil}; the second is a generalized boolean if and only if the first value is non-nil and the pattern is to be matched against two rows rather than just one. If the generalized boolean @var{as-string} is true the pattern is returned as a string, as by @code{format-pattern}, with the case of any bells represented by letters controled by the generalized boolean @var{upper-case}; and otherwise as a parse tree, as by @code{parse-pattern}. A string return value may not be @code{string-equal} to that added to @var{counter}, but will match the same @code{row}s. If @var{as-string} is not supplied it defaults to true; if @var{upper-case} is not supplied it defaults to the current value of @code{*print-bells-upper-case*}. Signals a @code{type-error} if @var{counter} is not a @code{match-counter}.

Package

roan.

Source

pattern.lisp.

Reader: match-counter-stage (instance) ¶

Package

roan.

Source

pattern.lisp.

Target Slot

stage.

Function: method (&key name jump differential little class stage place-notation) ¶

Creates a new @code{method} instance, with the specified @var{name}, @var{stage}, @var{classification} and @var{place-notation}.
If @var{stage} is not provided, it defaults to
the current value of @code{*default-stage*}; to create a @code{method} with no stage @code{:stage nil} must be explicitly supplied.

A @code{type-error} is signaled if @var{stage} is supplied and is neither @code{nil} nor a @code{stage}; if either of @var{name} or @var{place-notation} are supplied and are neither @code{nil} nor a string; or if @code{class} is supplied and is neither @code{nil} nor one of the keywords @code{:bob}, @code{:place}, @code{:surprise}, @code{:delight}, @code{:treble-bob}, @code{:alliance}, @code{:treble-place} or @code{:hybrid}. A @code{inconsistent-method-specification-error} is signaled if the various classification details cannot occur together, such as a little principle.

Package

roan.

Source

method.lisp.

Function: method-canonical-rotation-key (method) ¶

If @var{method} has its stage and place notation set returns a string uniquely identifying, using @code{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 @code{method-canonical-rotation-key}s will always be @code{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 @var{method} does not have both its stage and place notation set @code{method-canonical-rotation-key} returns @code{nil}.

Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if @var{method}’s place notation cannot be properly parsed at its stage.
@example
@group
(method-canonical-rotation-key
(lookup-method "Cambridge Surprise" 8))
@result{} "bAvzluTjWO5P"
(method-canonical-rotation-key
(method :stage 8 :place-notation "5x6x7,x4x36x25x4x3x2"))
@result{} "bAvzluTjWO5P"
(method-canonical-rotation-key
(method :stage 8 :place-notation "x1x4,2"))
@result{} "bEvy3Zo"
(method-canonical-rotation-key
(method :stage 10 :place-notation "x1x4,2"))
@result{} "Oi3Jd2sC"

(method-canonical-rotation-key (method) @result{} nil
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-changes (method) ¶

If @var{method}’s stage and place-notation have been set returns a fresh list of @code{row}s, representing changes, that constitute a plain lead of @var{method}, and otherwise returns @code{nil}. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-changes (method :stage 6
:place-notation "x2,6"))
@result{} (!214365 !124365 !214365 !132546)
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-class (method) ¶

Package

roan.

Source

method.lisp.

Setf expander for this function

(setf method-class).

Function: method-contains-jump-changes-p (method) ¶

If @var{method}’s stage and place-notation have been set and method contains one or more jump changes returns true, and otherwise returns @code{nil}. Note that even if the place notation is set and implies jump changes, if the stage is not set @code{method-contains-jump-changes-p} will still return @code{nil}.

Note that this function reflects the place notation of @var{method} while @code{method-jump-p} reflects the classification stored in the method, and they may not agree.

Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-contains-jump-changes-p
(method :place-notation "x3x4x2x3x4x5,2"
:stage 6))
@result{} nil
(method-contains-jump-changes-p
(method :place-notation "x3x(24)x2x(35)x4x5,2"
:stage 6))
@result{} t
(method-contains-jump-changes-p
(method :stage 6))
@result{} nil
(method-contains-jump-changes-p
(method :place-notation "x3x(24)x2x(35)x4x5,2"
:stage nil))
@result{} nil
@end group
@end example

Package

roan.

Source

method.lisp.

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 @code{type-error} if @var{method} is not a @code{method}. Signals a @code{no-place-notation-error} if @var{method}’s stage or place notation are not set. Signals a @code{parse-error} if @var{method}’s place notation cannot be interpreted at its stage.
@example
@group
(method-conventionally-symmetric-p
(lookup-method-by-title "Advent Surprise Major"))
@result{} t
(method-conventionally-symmetric-p
(lookup-method-by-title "Grandsire Caters"))
@result{} nil
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-course-length (method) ¶

If @var{method}’s stage and place-notation have been set returns a positive integer, the length of a plain course of @var{method}, and otherwise @code{nil}. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-course-length
(method :title "Cambridge Surprise Minor"
:place-notation "x3x4x2x3x4x5,2"))
@result{} 120
(method-course-length
(method :title "Cromwell Tower Block Minor"
:place-notation "3x3.4x2x3x4x3,6"))
@result{} 24
(method-course-length
(method :title "Bexx Differential Bob Minor"
:place-notation "x1x1x23,2"))
@result{} 72
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-differential-p (method) ¶

Package

roan.

Source

method.lisp.

Setf expander for this function

(setf method-differential-p).

Function: method-falseness (method) ¶

Computes the most commonly considered kinds of internal falseness of the most common methods: those at even stages major or higher with a single hunt bell, the treble, and all the working bells forming one cycle, that is, not differential. Falseness is only considered with the treble fixed, as whole leads, and, for stages royal and above, with the seventh (that is, the bell roan denotes by @code{6}) and above fixed. Returns three values: a summary of the courses that are false; for methods that have Plain Bob lead ends and lead heads and the usual palindromic symmetry, the false course head groups that are present; and a description of the incidence of falseness.

The first value is a list of course heads, @code{row}s that have the treble and tenors fixed, such that the plain course is false against the courses starting with any of these course heads. Rounds is included only if the falseness occurs between rows at two different positions within the plain course. Course heads for major have just the tenor (that is, the bell represented in Roan by the integer @code{7}) fixed, while course heads for higher stages have all of the seventh and above (that is, bells represented in Roan by the integers @code{6} and larger) fixed in their rounds positions.

If @var{method} has Plain Bob lead ends and lead heads, and the usual palindromic symmetry, the second value returned is a list of @code{fch-group} objects, and otherwise the second value is @code{nil}. Note also that for methods that are completely clean in the context used by this function, for example plain royal methods, an empty list also will be returned. These two cases can be disambiguated by examining the first value returned.

There is some ambiguity in the interpretation of “A” falseness. In Roan a method is only said to have “A” falseness if its plain course is false. That is, the trivial falseness implied by a course being false against itself and against its reverse by virtue of containing exactly the same rows is not reported as “A” falseness. “A” falseness is only reported if there is some further, not-trivial falseness between rows at two different positions within the plain course.

The third value returned is a two dimensional, square array, each of the elements of that array being a possibly empty list of course heads. For element @var{e}, the list at @var{m},@var{n} of this array, lead @var{m} of the plain course of @var{method} is false against lead @var{n} of each of the courses starting with an element of @var{e}. The leads are counted starting with zero. That is, if @var{s} is the stage of @var{method}, then 0≤@var{m}<@var{s}-1 and 0≤@var{n}<@var{s}-1.

A @code{type-error} is signaled if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage. If @var{method} does not have its stage or place-notation set a @code{no-place-notation-error}. If @var{method} is not at an even stage major or above, does not have one hunt bell, the treble, or is differential, an @code{inappropriate-method-error} is signaled.
@example
@group
(multiple-value-bind (ignore1 groups ignore2)
(method-falseness
(method :stage 8
:place-notation "x34x4.5x5.36x34x3.2x6.3,8"))
(declare (ignore ignore1 ignore2)
(fch-groups-string groups))
@result{} "BDacZ"
(fch-groups-string
(second
(multiple-value-list
(method-falseness
(lookup-method "Zorin Surprise" 10)))))
@result{} "T/BDa1c"
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-from-title (title &optional place-notation) ¶

Creates a new @code{method} instance, with its name, classification and stage
as specified by @var{title}, and with the given @var{place-notation}.
If the title does not include a stage name, the stage of the result is the current value of @code{*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 @var{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 @code{method-class}, and possibly @code{method-little-p}, of the resulting method as desired.

A @code{type-error} is signaled if @var{title} is not a string, or if @var{place-notation} is neither a string nor @code{nil}.
@example
@group
(let ((m (method-from-title "Advent Surprise Major")))
(list (method-title m) (method-class m) (method-stage m)))
@result{} ("Advent" :surprise 8)
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-hunt-bells (method) ¶

If @var{method}’s stage and place-notation have been set @code{method-hunt-bells} returns a fresh list of @code{bell}s (that is, small integers, with the treble represented by zero) that are hunt bells of @var{method} (that is, that return to their starting place at each lead head), and otherwise returns @code{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 @code{nil}.

Signals a @code{type-error} if @var{method} is not a @code{method}, and signal a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-hunt-bells (method-from-title "Grandsire Doubles" "3,1.5.1.5.1"))
@result{} (0 1)
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-jump-p (method) ¶

Package

roan.

Source

method.lisp.

Setf expander for this function

(setf method-jump-p).

Function: method-lead-count (method) ¶

If @var{method}’s stage and place-notation have been set returns a positive integer, the number of leads in a plain course of @var{method}, and otherwise @code{nil}. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-lead-count
(method-from-title "Cambridge Surprise Minor" "x3x4x2x3x4x5,2"))
@result{} 5
(method-lead-count
(method-from-title "Cromwell Tower Block Surprise Minor" "3x3.4x2x3x4x3,6"))
@result{} 1
(method-lead-count
(method-from-title "Bexx Differential Bob Minor" "x1x1x23,2"))
@result{} 6
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-lead-head (method) ¶

If @var{method}’s stage and place-notation have been set returns a @code{row}, the lead head generated by one plain lead of @var{method}, and otherwise @code{nil}. If @var{method} has a one lead plain course the result will be rounds. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-lead-head (method-from-title "Little Bob Major" "x1x4,2"))
@result{} !16482735
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-lead-head-code (method) ¶

Returns the lead head code for @var{method}, as a keyword, if its stage and place

notation are set and it has Plain Bob or Grandsire lead ends, and otherwise returns @code{nil}. No methods below minimus are considered to have such lead ends, nor is rounds considered such a lead end. When not @code{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 @url{https://cccbr.github.io/method_ringing_framework/, 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 @code{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 @code{type-error} if @var{method} is not a @code{method}, and a @code{parse-error} if @var{method}’s place notation cannot be interpreted at its stage. @example
@group
(method-lead-head-code
(lookup-method-by-title "Advent Surprise Major"))
@result{} :h
(method-lead-head-code
(lookup-method-by-title "Zanussi Surprise Maximus"))
@result{} :j2
(method-lead-head-code
(lookup-method-by-title "Sgurr Surprise Royal"))
@result{} :d
(method-lead-head-code
(lookup-method-by-title "Twerton Little Bob Caters"))
@result{} :q2
(method-lead-head-code
(lookup-method-by-title "Grandsire Royal"))
@result{} :p
(method-lead-head-code
(lookup-method-by-title "Double Glasgow Surprise Major"))
@result{} nil
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-lead-length (method) ¶

If @var{method}’s stage and place-notation have been set returns a positive integer, the length of one lead of @var{method}, and otherwise @code{nil}. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-lead-length
(method-from-title "Cambridge Surprise Minor" "x3x4x2x3x4x5,2"))
@result{} 24
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-library-details () ¶

Returns eight values describing the current Roan method libary. All are strings. They are:
@enumerate
@item
A description of the CCCBR Method Library, extracted from the file from which the Roan library was constructed

@item
The date and time the file on the remote server was last modified, according to that server.

@item
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 @code{update-method-library} decides whether or not the Roan method library needs updating.

@item
The URL used to fetch the remote file from which the Roan library was built.

@item
The @var{source-id} provided in the remote file, that is a CCCBR version stamp.

@item
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.

@item
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.

@item
The date and time the current version of the Roan library was built.
@end enumerate

Package

roan.

Source

method.lisp.

Function: method-little-p (method) ¶

Package

roan.

Source

method.lisp.

Setf expander for this function

(setf method-little-p).

Function: method-plain-course (method) ¶

If @var{method}’s stage and place-notation have been set returns a fresh list of the @code{row}s that constitute a plain course of @var{method}, and otherwise @code{nil}. The list returned will start with rounds, and end with the @code{row} immediately preceding the final rounds. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.

Package

roan.

Source

method.lisp.

Function: method-plain-lead (method) ¶

If @var{method}’s stage and place-notation have been set returns a fresh list of @code{row}s, starting with rounds, that constitute the first lead of the plain course of @var{method}, and otherwise returns @code{nil}. The lead head that starts the next lead is not included. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-plain-lead (method :stage 6
:place-notation "x2,6"))
@result{} (!123456 !214365 !213456 !124365)
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-rotations-p (method-1 method-2) ¶

Returns true if and only if the changes constituting a lead of @var{method-1} are the same as those constituting a lead of @var{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 @var{method-1} and @var{method-2} are of different stages the result will always be false.

Signals a @code{no-place-notation-error} if either argument does not have its stage or place notation set. Signals a @code{type-error} if either argument is not a @code{method}. Signals a @code{parse-error} if the place notation of either argument cannot be parsed as place notation at its stage.
@example
@group
(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"))
@result{} 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"))
@result{} 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")
@result{} 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"))
@result{} nil)
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-stage (method) ¶

Package

roan.

Source

method.lisp.

Setf expander for this function

(setf method-stage).

Function: method-title (method &optional show-unknown) ¶

Returns a string containing as much of the @var{method}’s title as is known. If @var{show-unknown}, a generalized boolean defaulting to false, is not true then an unknown name is described as "Unknown", and otherwise is simply omitted. Signals a @code{type-error} if @var{method} is not a @code{method}.

The one argument case can be used with @code{setf}, in which case it potentially sets any or all of the name, classification and stage of @var{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 @code{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 @code{setf} with @code{method-title} the stage is set to @code{nil}; @code{*default-stage*} is not consulted.
@example
@group
(method-title (method "Advent" :class :surprise :stage 8))
@result{} "Advent Surprise Major"
(method-title (method :name "Grandsire" :class :bob :stage 9))
@result{} "Grandsire Caters"
(method-title (method :stage 8))
@result{} "Major"
(method-title (method :class :delight :stage 8) t)
@result{} "Unknown Delight Major
(method-title (method :name "Advent" :class :surprise :stage nil))
@result{} "Advent Surprise"
(method-title (method :name "Slinky" :stage 12 :class :place
:little t :differential t))
@result{} "Slinky Differential Little Place Maximimus"
(method-title (method :name "Stedman" :stage 11))
@result{} "Stedman Cinques"
(method-title (method :name "Meson" :class :hybrid
:little t :stage 12))
@result{} "Meson Maximus"
@end group
@end example

Package

roan.

Source

method.lisp.

Setf expander for this function

(setf method-title).

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

If @var{method} has a non-nil stage and place notation set, returns true if @var{method}’s plain course is true and @code{nil} otherwise. If @var{method} does not have a non-nil stage or place notation a @code{no-place-notation-error} is signaled if the generalized boolean @var{error-if-no-place-notation} is true, and otherwise @code{nil} is returned; if @var{error-if-no-place-notation} is not supplied it defaults to true. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-true-plain-course-p
(method :title "Little Bob Minor"
:place-notation "x1x4,2"))
@result{} t
(method-true-plain-course-p
(method :title "Unnamed Little Treble Place Minor"
:place-notation "x5x4x2,2"))
@result{} nil
@end group
@end example

Package

roan.

Source

method.lisp.

Function: method-working-bells (method) ¶

If @var{method}’s stage and place-notation have been set returns a list of lists of @code{bell}s (that is, small integers, with the treble represented by zero) that are working bells of @var{method} (that is, that do not return to their starting place at each lead head), and otherwise returns @code{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 @code{nil}. Signals a @code{type-error} if @var{method} is not a @code{method}. Signals a @code{parse-error} if the place notation string cannot be properly parsed as place notation at @var{method}’s stage.
@example
@group
(method-working-bells (method :stage 7
:place-notation "7.1.7.47,27"))
@result{} ((1 4 5) (2 6 3))
@end group
@end example

Package

roan.

Source

method.lisp.

Function: order (row) ¶

Returns a positive integer, the order of @var{row}: the minimum number of times it must be permuted by itself to produce rounds. A @code{type-error} is signaled if @var{row} is not a @code{row}.
@example
@group
(order !13527486) @result{} 7
(order !31256784) @result{} 15
(order !12345678) @result{} 1
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: parse-method-title (title) ¶

Package

roan.

Source

method.lisp.

Function: parse-pattern (pattern &optional stage) ¶

Converts a string representation of a pattern to its parse tree, and returns it. The @var{stage} is the stage for which @var{pattern} is parsed, and defaults to @code{*default-stage*}. If @var{pattern} is a non-empty list it is presumed to be a pattern parse tree and is returned unchanged. Signals a @code{type-error} if @var{pattern} is neither a string nor a non-empty list, or if @var{stage} is not a @code{stage}. Signals a @code{parse-error} if @var{pattern} is a string but cannot be parsed as a pattern, or contains bells above those appropriate for @var{stage}.
@example
@group
(parse-pattern "(?[234]*|*4-9%4?)*T" 12)
@result{}
(:sequence (:or (:sequence :one (:class 1 2 3) :any)
(:sequence :any (:run 3 8 4 t) :one))
:any
11)
@end group
@end example

Package

roan.

Source

pattern.lisp.

Function: parse-place-notation (string &key stage start end junk-allowed) ¶

===summary===
@cindex Lisp reader
@cindex reader macro
@cindex sharp bang
@cindex @code{#!} reader macro
@cindex place notation
@cindex palindromes
@cindex jump changes
@cindex involutions
@cindex London Treble Jump Minor
@cindex parentheses
@cindex brackets
@cindex @samp{(} in place notation
@cindex @samp{[} in place notation
@cindex dot
@cindex @samp{.} in place notation
@cindex comma
@cindex @samp{,} in place notation
@cindex @samp{x} in place notation
@cindex @samp{-} in place notation
@cindex @samp{)} following place notation
@cindex quote
Place notation manipulated by Roan is extended to support jump changes and comma as an unfolding operator for easy notation of palindromic sequences of changes.

Jump changes may be included in the place notation in two ways. Within changes may appear parenthesized pairs of places, indicating that the bell in the first place jumps to the second place. Thus the change (13)6 corresponds to the jump change 231546. As usual implied leading or lying places may be omitted, so that could also be written simply (13). However, just as with ordinary place notation, all internal places must be noted explicitly; for example, the change (13)(31) is illegal, and must be written (13)2(31). Using this notation the first half-lead of London Treble Jump Minor can be written 3x3.(24)x2x(35).4x4.3.

Jump changes may also be written by writing the full row between square brackets. So that same half-lead of London Treble Jump Minor could instead be notated 3x3[134265]x2x[214536]4x4.3. Or they can be mixed 3x3[134265]x2x(35).4x4.3.

Palindromes may be conveniently notated using a comma operator, which means the changes preceding the comma are rung backwads, following the last of the changes before the comma, which is not repeated; followed by the changes following the comma, similarly unfolded. Thus x3x4,2x3 is equivalent to x3x4x3x2x3x2. A piece of place notation may include at most one comma. Neither the changes before the comma nor after it may be empty. Any piece of place notation including a comma is necessarily of even length.

If jump changes appear in place notation that is being unfolded then when rung in reverse the jump changes are inverted; this makes no difference to ordinary changes, which are always involutions, but is important for jump changes that are not involutions. If the central change about which the unfolding operation takes place, that is the last change in a sequence of changes being unfolded, is not an involution an error is signaled. As an example, a plain lead of London Treble Jump Minor can be notated as 3x3.(24)x2x(35).4x4.3,2 which is equivalent to 3x3.(24)x2x(35).4x4.3.4x4.(53)x2x(42).3x3.2.

While place notation is normally written using dots (full stops) only between non-cross changes, @code{parse-place-notation} will accept, and ignore, them between any changes, adjacent to other dots, and before and after place notation to be parsed. This may simplify operation with other software that emits place notation with extraneous dots.

Just as Roan can augment the Lisp reader with @samp{!} to read @code{row}s, it can augment it with the @samp{#!} reader macro to read place notatation. The stage at which the place notation is to be interpreted can be written as an integer between the @samp{#} and the @samp{!}. If no explict stage is provided the current value (at read time) of @code{*default-stage*} is used. The sequence of place notation must be followed by a character that cannot appear in place notation, such as whitespace, or by end of file. There is an exception that an unbalanced close parenthesis will also end the reading; this allows using this to read place notation in lists and vectors without requiring whitespace following the place notation. The place notation may be extended with the comma unfolding operator, and with jump changes. The stage at which the place notation is being iterpreted is not considered in deciding which characters to consume; all that might apply as place notation at any stage will be consumed. If some are not appropriate an error will only be signaled after all the continguous, place notation characters have been read.

Note that, unlike @code{row}s, which are Lisp atoms, the result of reading place notation is a list, so @samp{#!} quotes it. This is appropriate in the usual case where the result of @samp{#!} is evaluated, but if used in a context where it is not evaluated care must be exercised.

This @samp{#!} syntax can be turned on and off by using @ref{roan-syntax}. By default it is off when Roan is loaded. It is also possible to control this syntax by using @url{https://github.com/melisgl/named-readtables/, Named Readtables}; see @ref{roan-syntax} for further details.
@example
@group
ROAN> #6!x2,1
(!214365 !124365 !214365 !132546)
ROAN> ’(symbol #6!x2,1 x #6!x2x1)
(SYMBOL ’(!214365 !124365 !214365 !132546) X
’(!214365 !124365 !214365 !132546))
ROAN> ‘(symbol ,#6!x2,1 x ,#6!x2x1)
(SYMBOL (!214365 !124365 !214365 !132546) X
(!214365 !124365 !214365 !132546))
ROAN> #6!x2
(!214365 !124365)
ROAN> (equalp #10!x1x4,2 #10!x1x4x1x2)
T
ROAN> #6!x3.(13)(64)
(!214365 !213546 !231645)
ROAN> #6!x3.(13).(64)
(!214365 !213546 !231546 !132645)
ROAN> #6!x3[231546](64)
(!214365 !213546 !231546 !132645)
@end group
@end example
===endsummary===
Parses place notation from @var{string}, returning a list of @code{row}s, representing changes, of stage @var{stage}. The place notation is parsed as applying to stage @var{stage}, which, if not supplied, defaults to current value of @code{*default-stage*}. Only that portion of @var{string} between @var{start} and @var{end} is parsed; @var{start} should be a non-negative integer, and @var{end} either an integer larger than @var{start} or @code{nil}, which latter is equivalent to the length of @var{string}. If @var{junk-allowed}, a generalized Boolean, is @code{nil}, the default, @var{string} must consist of the place notation parsed and nothing else; otherwise non-place notation characters may follow the place notation. For purposes of parsing @var{stage} is not initially considered: if the place notation is only appropriate for higher stages it will not terminate the parse even if @var{junk-allowed} is true, it will instead signal an error. Two values are returned. The first is a list of @code{row}s, the changes parsed. The second is the index of the next character in @var{string} following the place notation that was parsed.

If the section of @var{string} delimited by @var{start} and @var{end} does not contain place notation suitable for @var{stage} a @code{parse-error} is signaled. If @var{string} is not a string, @var{stage} is not a @code{stage} or @var{start} or @var{end} are not suitable bounding index designators a @code{type-error} is signaled. @example
@group
(multiple-value-list (parse-place-notation "x2.3" :stage 6))
@result{} ((!214365 !124365 !213546) 4)
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: parse-row (string &key start end junk-allowed) ¶

Contructs a @code{row} from the conventional symbols for bells in the section of string @var{string} delimited by @var{start} and @var{end}, possibly preceded or followed by whitespace. The treble can be elided, in which case it is assumed to be leading; a @code{parse-error} is signaled if any other bell is omitted. Bells represented by letters can be either upper or lower case. If @var{string} is not a string a @code{type-error} is signaled. If the generalized boolean @var{junk-allowed} is false, the default, an error will be signaled if additional non-whitespace characters follow the representation of a row. Returns two values: the @code{row} read and a non-negative integer, the index into the string of the next character following all those that were parsed, including any trailing whitespace; if parsing consumed the whole of @var{string}, the second value will be length of @var{string}.

Package

roan.

Source

roan.lisp.

Function: pattern-parse-error (&optional message &rest args) ¶

Package

roan.

Source

pattern.lisp.

Function: permutation-closure (&rest rows) ¶

Returns a list of distinct rows that can be generated by permuting, repeatedly if necessary, any of the @var{rows} by themselves or any others of the @var{rows}. If the @var{rows} are not all of the same stage, the lower stage ones are converted to the highest stage present before the closure operation is performed. The order of the returned rows is undefined. Signals a @code{type-error} if any of the @var{rows} is not a @code{row}.
@example
@group
(permutation-closure !13425 !1324 !123465)
@result{} (!143265 !142365 !124365 !142356 !143256 !124356
!134265 !132465 !123456 !123465 !132456 !134256)
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: permute (row &optional change &rest changes) ¶

===lambda: (row &rest changes)
Permutes @var{row} by the @var{changes} in turn. That is, @var{row} is first permuted by the first of the @var{changes}, then the resuling row is permuted by second of the @var{changes}, and so on. Returns the row resulting from applying all the changes. So long as one or more @var{changes} are supplied the returned @code{row} is always a freshly created one: @var{row} and none of the @var{changes} are modified (as you’d expect, since they are intended to be viewed as immutable). The @var{row} and all the @var{changes} should be @code{row}s.

At each step of permuting a row by a change, if the row is of higher stage than the change, only the first @var{stage} bells of the row are permuted, where @var{stage} is the stage of the change, all the remaining bells of the row being unmoved. If the row is of lower stage than the change, it is as if the row were extended with bells in their rounds’ positions for all the bells @var{stage} and above. Thus the result of each permuation step is a @code{row} whose stage is the larger of those of the row and the change.

If no @var{changes} are supplied @code{row} is returned. Signals a @code{type-error} if @var{row} or any of the @var{changes} are not @code{row}s.
@example
@group
(permute !34256 !35264) @result{} !145362
(permute !34125 !4321 !1342) @result{} !24315
(permute !4321 !654321) @result{} !651234
(let ((r !13572468))
(list (eq (permute r) r)
(equalp (permute r (rounds 8)) r)
(eq (permute r (rounds 8)) r)))
@result{} (t t nil)
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: permute-by-inverse (row change) ¶

Equivalent to @code{(permute @var{row} (inverse @var{change}))}. Signals a @code{type-error} if either @var{row} or @var{change} is not a @code{row}. @example
@group
(permute-by-inverse !13456287 !45678123) @result{} !28713456 (permute-by-inverse !54312 !2438756) @result{} !54137862 (permute-by-inverse !762345 !4312) @result{} !6271345
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: place-notation-error (parsing format-string &rest args) ¶

Package

roan.

Source

roan.lisp.

Function: place-notation-string (changes &rest keys &key comma elide cross upper-case allow-jump-changes) ¶

===lambda: (changes &key comma elide cross upper-case allow-jump-changes)
Returns a string of the place notation representing the list @var{changes}. The arguments are the same as the like named arguments to @code{write-place-notation}. A leading ’#!’ is never included in the result.

Signals a @code{type-error} if any elements of @var{changes} are not @code{row}s. Signals an error if @var{changes} is empty or contains rows of different stages.
@example
@group
(multiple-value-list
(place-notation-string #8!x1x4,1 :elide nil))
@result{} ("x18x14x18x18" nil)
(multiple-value-list
(place-notation-string #8!x1x4,1 :comma t))
@result{} ("x1x4,8" t)
(multiple-value-list
(place-notation-string #8!x1x4,2 :elide :interior))
@result{} ("x18x4x18x18" nil)
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: placesp (row &rest places) ¶

Returns true if and only if @var{row} is a (non-jump) change, with exactly the specified @var{places} being made, and no others. To match a cross at even stages supply no @var{places}.

Signals a @code{type-error} if @var{row} is not a @code{row} or any of @var{places} are not @code{bell}s. Signals an @code{error} if any of @var{places} are not less than the stage of @var{row}, or are duplicated.
@example
@group
(placesp !21354768 2 7) @result{} t
(placesp !21346587 2 7) @result{} nil
(placesp !21354768 2) @result{} nil
(placesp !2135476 2) @result{} t
(placesp !21436587) @result{} t
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: position-of-bell (bell row) ¶

===merge: bell-at-position

Package

roan.

Source

roan.lisp.

Function: read-place-notation (&optional stream stage eof-error-p eof-value recursive-p) ¶

Reads place notation from a stream, resulting in a list of @code{row}s representing changes. Reads all the consecutive characters that can appear in (extended) place notation, and then tries to parse them as place notation. It accumulates characters that could appear as place notation at any stage, even stages above @var{stage}. The sequence of place notation must be followed by a character that cannot appear in place notation, such as whitespace, or by end of file. There is an exception, in that an unbalanced close parenthesis will also end the read; this allows using this to read place notation in lists and vectors without requiring whitespace following the place notation. The place notation may be extended with the comma unfolding operator, and with jump changes, as in @code{parse-place-notation}. The argument @var{stream} is a character stream open for reading, and defaults to the current value of @code{*standard-input*}; @var{stage} is a @code{stage}, an integer, and defaults to the current value of @code{*default-stage*}; and @var{eof-error-p}, @var{eof-value} and @var{recursive-p} are as for the standard @code{read} function, defaulting to @code{t}, @code{nil} and @code{nil}, respectively. Returns a non-empty list of @code{row}s, all of stage @var{stage}. Signals an error if no place notation constituents are available, if the characters read cannot be parsed
as (extended) place noation at @var{stage}, or if one of the usual errorneous conditions while reading occurs.

Package

roan.

Source

roan.lisp.

Function: read-row (&optional stream eof-error-p eof-value recursive-p) ¶

Constructs and returns a @code{row} from the conventional symbols for bells read from the @var{stream}. The stage of the row read is determined by the bells present, that is by the largest bell for which a symbol is read. The treble can be elided, in which case it is assumed to be leading; a @code{parse-error} is signaled if any other bell is omitted. Bells represented by letters can be either upper or lower case.

Package

roan.

Source

roan.lisp.

Function: record-matches (counter row &optional following-row handstroke-p) ¶

Causes all the single-row patterns of @var{counter} to be matched against @var{row}, and, if a @var{following-row} is supplied and not @code{nil}, also all the double-row patterns to be matched against both rows. If the generalized boolean @var{handstroke-p} is supplied it indicates whether @var{row} is to be considered a handstroke or not, and, unless explicitly set again, either with the @var{handstroke-p} argument to @code{record-matches} by with @code{(setf match-counter-handstroke-p)}, whether or not subsequent rows will be considered handroke or backstroke will alternate. That is, supplying a @var{handtroke-p} argument to @code{record-matches} is equivalent to calling @code{(setf match-counter-handstoke-p)} immediately before it. Signals a @code{type-error} if @var{counter} is not a @code{match-counter}, @var{row} is not a @code{row}, or @var{following-row} is neither a @code{row} nor @code{nil}.

Package

roan.

Source

pattern.lisp.

Function: remove-all-patterns (counter) ¶

Removes all the patterns in the @code{method-counter} @var{counter}, and returns a positive integer, the number of patterns so removed, if any, or @code{nil} if @var{counter} had no patterns. Signals a @code{type-error} if @var{counter} is not a @code{match-counter}.

Package

roan.

Source

pattern.lisp.

Function: remove-pattern (counter label) ¶

Removes any pattern in @code{method-counter} @var{count} with its label @code{equalp} to @var{label}. Returns @code{t} if such a pattern was found and removed, and @code{nil} otherwise. Signals a @code{type-error} if @var{count} is not a @code{method-counter}.

Package

roan.

Source

pattern.lisp.

Function: reset-match-counter (counter) ¶

Resets all the counts associated with all the patterns in @var{counter} to zero. Signals a @code{type-error} if @var{counter} is not a @code{match-counter}.

Package

roan.

Source

pattern.lisp.

Function: reversed-row (row) ¶

Returns a @code{row} of the same stage as @var{row} with its bells in the reverse order. A @code{type-error} is signaled if @var{row} is not a @code{row}. @example
(reversed-row !32148765) @result{} !56784123
@end example

Package

roan.

Source

roan.lisp.

Function: rounds (&optional stage) ¶

Returns a @code{row} representing rounds at the given @var{stage}, which defaults to @code{*default-stage*} Signals a @code{type-error} if @var{stage} is not a @code{stage}, that is an integer between @code{+minimum-stage+} and @code{+maximum-stage+}, inclusive.

Package

roan.

Source

roan.lisp.

Function: roundsp (row) ¶

True if and only if @var{row} is a @code{row} representing rounds at its stage. @example
@group
(roundsp !23456) @result{} t
(roundsp !123546) @result{} nil
(roundsp 123456) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: row (&rest bells) ¶

Constructs and returns a @code{row} containing the @var{bells}, in the order they appear in the argument list. If the treble is not present, it defaults to being the first bell in the row. Duplicate bells or bells other than the treble missing result in an error being signaled.
@example
(row 2 1 3 4 7 6 5) @result{} !13245876
@end example

Package

roan.

Source

roan.lisp.

Function: row-match-error (format &rest args) ¶

Package

roan.

Source

pattern.lisp.

Function: row-match-p (pattern row &optional following-row) ¶

===summary===
Roan provides a simple pattern language for matching rows. This is useful, among other things, for counting rows considered particularly musical or unmusical.

A pattern string describes the bells in a row, with several kinds of wildcards and other constructs matching multiple bells. Bells’ names match themselves, so, for example, "13572468" matches queens on eight. A question mark matches any bell, and an asterisk matches runs of zero or more bells. Thus "*7468", at major, matches all twenty-four 7468s, and "?5?6?7?8" matches all twenty-four major rows that have the 5-6-7-8 in the positions they are in in tittums. Alternatives can be separated by the pipe character, @samp{|}. Thus "13572468|12753468" matches either queens or Whittingtons. Concatentation of characters binds more tightly than alternation, but parentheses can be used to group subexpressions. Thus "*(4|5|6)(4|5|6)78" at major matches all 144 combination rollups. When matched against two major rows "?*12345678*?" matches wraps of rounds, but not either row being rounds.

Two further notations are possible. In each case it does not extend what can be expressed, it merely makes more compact something that can be expressed with the symbols already described. The first is a bell class, which consits of one or more bell names within square brackets, and indicates any one of those bells. Thus an alternative way to match the 144 combination rollups at major is "*[456][456]78".

A more compact notation is also available for describing runs of consecutive bells. Two bell symbols separated by a hyphen represent the run of bells from one to the other. Thus "*5-T" matches all rows ending 567890ET. If such a run description is followed by a solidus, @samp{/}, and a one or two digit integer, it matches all runs of the length of that integer that are subsequences of the given run. Thus "*2-8/4" is equivalent to "*(2345|3456|4567|5678)". If instead of a solidus a percent sign, ’%’, is used it matches subsequences of both the run and its reverse. Thus "1-6%4*" matches all little bell runs off the front of length four selected from the bells 1 through 6, and is equivalent to the pattern "(1234|4321|2345|5432|3456|6543)*". There is some possible ambiguity with this notation, in that the second digit of an integer following a solidus or percent sign could be interpreted as a digit or a bell symbol. In these cases it is always interpreted as a digit, but the other use can be specified by using parentheses or a space.

Spaces, but no other whitespace, can be included in patterns. However no spaces may be included within bell classes or run descriptions. Thus " 123 [456] 7-T/3 * " is equivalent to "123[456]7-T/3*", but both "123[ 4 5 6 ]7-T/3*" and
"123[456]7-T / 3*" are illegal, and will cause an error to be signaled.

In addition to strings, patterns may be represented by parse trees, which are simple list structures made up of keywords and bells (that is, small, non-negative integers). Strings are generally more convenient for reading and writing patterns by humans, but parse trees can be more convenient for programmatically generated patterns. The function @code{pattern-parse} converts the string representation of a pattern to such a tree structure. Sequences of elements are represented by lists starting with @code{:sequence}; alternatives by lists starting with @code{:or}; bell classes by lists of the included bells preceded by @code{:class}; runs by a list of the form @code{(:run @var{start} @var{end} @var{length} @var{bi})}, where @var{start} is the starting @code{bell}, @var{end} the ending @code{bell}, @var{length} the length of the run, and @var{bi} is a generalized boolean saying whether or not the runs are bidirectional; @code{bell}s are represented by themselves; and @samp{?} and @samp{*} by @code{:one} and @code{:any}, respectively. The elements of the @code{:sequence} and @code{:or} lists may also be lists themselves, representating subexpressions. For example, the string "(?[234]*|*4-9%4?)*T" is equivalent to the tree
@example
@group
(:sequence (:or (:sequence :one (:class 1 2 3) :any)
(:sequence :any (:run 3 8 4 t) :one))
:any
11)
@end group
@end example
===endsummary===
Determines whether @var{row}, or pair of consecutive @code{row}s, @var{row} and @var{following-row}, match a pattern. If @var{following-row} is supplied it should be of the same stage as @var{row}. The @var{pattern} may be a string or a tree, and should be constructed to be appropriate for the stage of @var{row}; an error is signaled if it contains explicit matches for bells of higher stage than @var{row}. Returns a generalized boolean indicating whether or not @var{pattern} matches.
@example
@group
(row-match-p "*[456][456]78" !32516478) @result{} t
(row-match-p "*[456][456]78" !12453678) @result{} nil
(row-match-p "*[456][456]78" !9012345678) @result{} t
(row-match-p "?*123456*?" !651234 !562143) @result{} t
(row-match-p "?*123456*?" !651234 !652143) @result{} nil
(row-match-p "?*123456*?" !123456) @result{} nil
(row-match-p ’(:sequence :any 6 7) !65432178) @result{} t
(row-match-p ’(:sequence :any 6 7) !23456781) @result{} nil
@end group
@end example

Signals an error if @var{pattern} cannot be parsed as a pattern, if @var{row} is not a @code{row}, if @var{following-row} is neither a @code{row} nor @code{nil}, if @var{pattern} contains bells above the stage of @var{row}, or if @var{following-row} is a @code{row} of a different stage than @var{row}.

Care should be used when matching against two rows. In the usual use case when searching for things like wraps every row typically will be passed twice to this method, first as @var{row} and then as @var{following-row}. A naive pattern might end up matching twice, and thus double counting. For example, if at major "*12345678*" were used to search for wraps of rounds it would match whenever @var{row} or @var{following-row} were themselves rounds, possibly leading to double counting. Instead a search for wraps of rounds might be better done against something like "?*12345678*?".

Package

roan.

Source

pattern.lisp.

Function: row-string (row &optional upper-case) ¶

Returns a string representing the @code{row} @var{row}. The case of any bells represented by letters is controlled by @var{upper-case}, a generalized
boolean defaulting to the current value of @code{*print-bells-upper-case*}. Signals a @code{type-error} if @var{row} is not a @code{row}.

Package

roan.

Source

roan.lisp.

Function: rowp (object) ¶

Package

roan.

Source

roan.lisp.

Function: stage (row) ¶

The number of @code{bell}s of which the @code{row} @var{row} is a permutation.

Package

roan.

Source

roan.lisp.

Function: stage-from-name (name) ¶

Returns a stage, a small, positive integer, with its name the same as the string designator @var{name}, or, if there is no stage with such a name, @code{nil}. The determination is made case-insensitively.
@example
@group
(stage-from-name "cinques") @result{} 11
(stage-from-name "no-such-stage") @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: stage-name (stage) ¶

Returns a string, the conventional name for this @var{stage}, capitalized, or @code{nil} if @var{stage} is not an integer corresponding to a supported stage. @example
@group
(stage-name 8) @result{} "Major"
(stage-name 22) @result{} "Twenty-two"
(stage-name (1+ +maximum-stage+)) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: tenors-fixed-p (row &optional starting-at) ¶

Returns true if and only if all the bells of @var{row} at positions @var{starting-at} or higher are in their rounds positions. In the degenerate case of @var{starting-at} being equal to or greater than the stage of @var{row} it returns true. Note that it is equivalent to @code{(not (null (alter-stage @var{row} @var{starting-at})))}. If not supplied @var{starting-at} defaults to @code{6}, that is the position of the bell conventionally called the seven, though represented in Roan by the small integer @code{6}. Signals a @code{type-error} if @var{row} is not a @code{row} or @var{starting-at} is not a non-negative integer.
@example
@group
(tenors-fixed-p !13254678) @result{} t
(tenors-fixed-p !13254678 5) @result{} t
(tenors-fixed-p !13254678 4) @result{} nil
(tenors-fixed-p !54321) @result{} t
(tenors-fixed-p !54321 4) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

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 @var{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 @code{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.

Package

roan.

Source

method.lisp.

Function: use-roan (&key package syntax modify) ¶

A convenience function for using the @code{roan} package. Causes @var{package},
which defaults to the current value of @code{*package*}, to inherit all the external symbols of the @code{roan} package, shadowing @code{method}, @code{method-name} and @code{class-name}.

If the generalized boolean @var{syntax} is true, the default, it also enables use of Roan’s @samp{!} and @samp{#!} read macros, by calling @ref{roan-syntax} with a true first argument; the value of @var{modify} is passed as a second argument to @ref{roan-syntax}.

Signals a @code{type-error} if @var{package} is not a package designator. Signals a @code{package-error} if @var{package} is the @code{keyword} package.
@example
@group
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
@end group
@end example

Package

roan.

Source

readtables.lisp.

Function: which-grandsire-lead-head (row) ¶

If @var{row} is a lead head of a plain course of Grandsire at its stage returns a positive integer identifying which lead head it is; returns @code{nil} if @var{row} is not a Grandsire lead head. If @var{row} is the first lead head of a plain course of Grandsire @code{1} is returned, if the second @code{2}, etc. For the purposes of this function rounds is not a Grandsire lead head, nor is any row below minimus. Signals a @code{type-error} if @var{row} is not a @code{row}.
@example
@group
(which-plain-bob-lead-head !1253746) @result{} 1
(which-plain-bob-lead-head !28967453) @result{} 4
(which-plain-bob-lead-head !135264) @result{} nil
(which-plain-bob-lead-head !1243) @result{} 1
(which-plain-bob-lead-head !12345) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: which-plain-bob-lead-head (row) ¶

If @var{row} is a lead head of a plain course of Plain Bob at its stage returns a positive integer identifying which lead head it is; returns @code{nil} if @var{row} is not a Plain Bob lead head. If @var{row} is the first lead head of a plain course of Plain Bob @code{1} is returned, if the second @code{2}, etc. For the purposes of this function rounds is not a Plain Bob lead head, nor is any row below minimus. Signals a @code{type-error} if @var{row} is not a @code{row}.
@example
@group
(which-plain-bob-lead-head !13527486) @result{} 1
(which-plain-bob-lead-head !42638507T9E) @result{} 10
(which-plain-bob-lead-head !129785634) @result{} nil
(which-plain-bob-lead-head !12345) @result{} nil
(which-plain-bob-lead-head !132) @result{} nil
@end group
@end example

Package

roan.

Source

roan.lisp.

Function: write-place-notation (changes &key stream escape comma elide cross upper-case jump-changes) ¶

Writes to @var{stream} characters representing place notation for @var{changes}, a list of @code{row}s.

The list @var{changes} should be a non-empty list of @code{row}s, all of the same stage. The @var{stream} should a character stream open for writing. It defaults to the current value of @code{*standard-output*}. If the generalized boolean @var{escape}, which defaults to the current value of @code{*print-escape*}, is true the place notation will be written using the @samp{#!} read macro to allow the Lisp @code{read} function to read it; in this case the stage will always be explicitly noted between the @samp{#} and the @samp{!}. If the generalized boolean @var{upper-case}, which defaults to the current value of @code{*print-bells-upper-case*}, is true positions notated using letters will be written in upper case, and otherwise in lower case.

The argument @var{cross} controls which character is used to denote a cross change at even stages. It must be a character designator for @code{ #\x}, @code{#\X} or @code{#\-}, and defaults to the current value of @code{*cross-character*}.

The argument @var{jump-changes} should be one of @code{nil}, @code{:jumps} or @code{:full}. It determines how jump changes will be notated. If it is @code{nil} and @var{changes} contains any jump changes an error will be signaled. If it is @code{:jumps} any jump changes will be notated using pairs of places between parentheses. While @code{parse-place-notation} and @code{read-place-notation} can interpret ordinary conjunct motion or even place making notated in parentheses, @code{write-place-notation} will only use parentheses for bells actually moving more than one place. If @var{jump-changes} is @code{:full} jump changes will be notated as a row between square brackets. Again, while ordinary changes notated this way can be parsed or read, @code{write-place-notation} will only use bracket notation for jump changes.

The argument @var{elide} determines whether, and how, to omit leading and/or lying places. If the stage of the changes in @var{changes} is odd, or if @var{elide} is @code{nil}, no such elision takes place. Otherwise @var{elide} should be one of @code{:interior}, @code{:leading}, @code{:lying} or @code{:lead-end}, which last is its default value. For any of these non-nil values leading or lying places will always be elided if there are interior places. They differ only for hunts (that is, changes with both a leading and lying place, and no interior places). If @code{:interior}, no elision takes place if there are no interior places. If @code{:leading}, the ’1’ is elided as implicitly available. If @code{:lying}, the lying place is elided, so that the result is always ’1’. The value @code{:lead-end} specifies the same behavior as @code{:lying} for all the elements of @var{changes} except the last, for which it behaves as @code{:leading}; this is often convenient for notating leads of treble dominated methods at even stages.

If the generalized boolean @var{comma} is true an attempt is made to write @var{changes} using a comma operator separating it into palindromes. In general there can be multiple ways of splitting an arbitrary piece of place notation into palindromes. If this is the case the choice is made to favor first a division that has the palindrome after the comma of length one, and if that is not possible the division that has the shortest palindrome before the comma. Any sequence of changes of length two can be trivially divided into palindromes, but notating them with a comma is unhelpful, so @var{comma} applies only to even length lists of changes of length greater than two. Whether or not a partitioning into palindromes was possible can be determined by examining the second value returned by this function, which will be true only if a comma was written.

Returns two values, @var{changes}, and a generalized Boolean indicating whether or not the result was written with a comma.

Signals an error if @var{changes} is empty, or contains rows of different stages, if @var{stream} is not a character stream open for writing, or if any of the usual IO errors occurs.

Package

roan.

Source

roan.lisp.

Function: write-row (row &key stream escape upper-case) ¶

Writes @var{row}, which should be a @code{row}, to the indicated @var{stream}.
The case of any bells represented by letters is controlled by @var{upper-case}, a generalized boolean defaulting to the current value of @code{*print-bells-upper-case*}. @var{escape}, a generalized Boolean defaulting to the current value of @code{*print-escape*}, determines whether or not to write it in a form that read can understand. Signals a @code{type-error} if @var{row} is not a @code{row}, and the usual errors if @var{stream} is not open for writing, etc.

Package

roan.

Source

roan.lisp.

---