Roan provides an immutable call
object that describes a change ringing call, such
as a bob or single, that modifies a lead of a method
. A call
usually has a
fragment of place notation representing changes that are added to the the sequence of
changes constituting the lead, typically replacing some existing changes in the lead.
A call
has an offset, which specifies where in the lead the changes are added,
replaced or deleted; this offset can be indexed from the beginning or the end of a lead,
which frequently allows the same call to be used for similar methods with possibly
different lead lengths. It is also possible to index from a postion within the lead rather
than the beginning or end by supplying a fraction; again, this allows using, for example,
half-lead calls with similar methods with different lead lengths.
Typically a call
replaces exactly as many changes as it supplies. However it is
possible to replace none, in which case the call
adds to the lead length; to only
replace changes with a zero length sequence of changes, in which case the call
shortens the lead by deleting changes; or even to add more or fewer changes than it
replaces.
Typically a call only affects the lead of a method to which is is applied. In exceptional
cases, most notably doubles variations, it may also affect the subsequent lead. To support
such use a call
may have a following place notation fragment and a following
replacement length. Such use is always restricted to being positioned at the beginning of
the subsequent lead, and in the main lead the call must replace changes all the way to the
end of the lead. Note that by starting the call at the end of the lead this could be
simply adding changes, or even doing nothing.
A call
is applied to a lead with the function call-apply
. This can take
multiple call
s, all of which are applied to the same lead. They must not, however,
overlap. The call-apply
function returns two values. The first is a list of the
changes of the lead, modified by the call
(s). The second, if not nil
, is
another call
to be applied to the following lead, and is only non-nil when a
call
does apply also to the subsequent lead.
Two call
s may be compared with equalp
.
Examples of call
s:
(call "4")
.
(call "3.123" :offset 2)
.
(call "7" :from-end nil)
.
(call "5" :fraction 1/2)
.
(call "3.123" :following "3")
.
(call nil :from-end nil :replace 2)
.
An immutable object describing a change ringing call, such as a bob or single.
Creates and returns a call
, which modifies the changes of a lead of a
method
. The 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
method
when applying the code
. The place-notation may be nil
,
in which case no changes are added or replace existing ones. The 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 from-end is
false, and from the end, otherwise. This can be further modifed by fraction which is
multiplied by the lead length; the offset is counted forward or backward from that
product. The fraction
, if non-nill, must be a ratio greater than 0
and less
than 1
, whose denominator evenly divides the lead length. The non-negative integer
replace is the number of changes in the lead to be deleted or replaced. It is
typically equal to the length of 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 following or following-replace are supplied the call is
intended to also apply to the subsequent lead. These operate just like
place-notation and replace, but on the subsequent lead, and always at the
begining of that lead. This use also depends upon the caller of call-apply
making
correct use of its second return value.
If replace is not supplied or is nil
it defaults to the number of changes
represented by the place-notation. If offset is not supplied or is nil
,
it defaults to 0
if from-end is false, and otherwise to the value of
replace, which may itself have been defaulted from the value of
place-notation. The default value of from-end is t
. The default value
of fraction is nil
. If following is supplied but
following-replace is not, following-replace defaults to the number of changes
represetned by following. If following-replace is supplied but following
is not, following defaults to nil
.
A parse-error
is signaled if either place-notation or following is
non-nil
but not interpretable as place notation at the stage of method. A
type-error
is signaled if offset is supplied and is neither nil
nor a
non-negative integer; if replace is supplied and is neither nil
nor a
non-negative integer; fraction is supplied and is neither nil
nor a ratio
between 0
and 1
, exclusive; or if following-replace is supplied and is
neither nil
nor a non-negative integer.
Applies zero or more calls to a lead of method. Returns two values, the
first a list of row
s constituting the changes of the modified lead and the second
nil
or a 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 calls may be nil
,
in which case they are ignored, just as if they had not been supplied. If no non-nil
calls are supplied returns a list of the changes constituting a plain lead of
method.
When multiple 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 type-error
if method is not a method
or if any of the
calls are neither a call
nor nil
. Signals a parse-error
if
method does not have its stage or place-notation defined. Signals a
call-application-error
in any of the following circumstances: if the stage of
method is such that the place notation or following place notation of one or more of
the calls is inapplicable; if an attempt is made to apply a fractional lead
call
where the denominator of the fraction does not evenly divide the lead length;
if the call
would be positioned, or replace changes, that lie outside the lead; if
a 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 call
s with following place
notation to the same lead.
Signaled when an anaomalous condition is detected while trying to
apply a call
to a method
. Contains three potentially useful slots
accessible with call-application-error-call
, call-application-error-method
and call-application-error-details
.