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

7 Calls

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 calls, 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 calls may be compared with equalp.

Examples of calls:

Type: call

An immutable object describing a change ringing call, such as a bob or single.

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

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.

Function: call-apply method &rest calls

Applies zero or more calls to a lead of method. Returns two values, the first a list of rows 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 calls with following place notation to the same lead.

Type: call-application-error

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.


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