NAME

Ringing::PlaceNotation - manipulate place notation


SYNOPSIS

  use Ringing::PlaceNotation;
  $pn = new Ringing::PlaceNotation(6, '&-3-4-25-3-4-5,2');
  print $pn->format(symmetry => 1, cross => 'x', external => 1);


DESCRIPTION

This module provides a class to represent a piece of place notation. It can parse input in a flexible format and provide output in a choice of different formats.

We also provide some separate functions for performing various operations on place notation strings and bell numbers.

EXPORT

None by default.

All the functions documented below are available for export; the tag :funcs will export them all.

There are also some precompiled regular expressions which may be exported, as described below; they can all be exported by using the tag :res.

The tag :all exports both the functions and the regular expressions.


PLACE NOTATION SYNTAX

A single bell is usually represented by one character. The characters representing bells from 1 to 33 are, as used, by the Central Council,

  1234567890ETABCDFGHJKLMNPQRSUVWYZ.

This package additionally supports an extended notation for bells above 33. Any bell may be represented by a decimal number in curly braces, for example {41} or {130}.

Place notation consists of a sequence of changes. A change is a sequence of bells, each representing a place made in the change. The places should be arranged in ascending order; this is not checked but often assumed. A `cross' change in which no places are made may be represented by and of the characters X, x or -. Changes are separated by dots, but dots either side of cross changes are optional. External places may be omitted. White space is permitted anywhere in the place notation and will be ignored. A piece of place notation matching this description is called simple.

Compound place notation is a series of pieces of place notation separated by commas. Each piece may start with an ampersand (&), in which case it represents a symmetrical sequence of changes: for example, the two strings &-2-3-4,5 and -2-3-4-3-2-5 are equivalent.


REGULAR EXPRESSIONS

This module defines the following regular expressions:

$any_bell
This regular expression matches any bell: either one of the characters used by the Central Council to refer to a bell (for bells up to 33) or a decimal number enclosed in braces (such as {41}) for arbitrary bell numbers.

$odd_bell
This regular expression matches any odd bell.

$even_bell
This regular expression matches any even bell.

$simple_pn
This regular expression matches a piece of simple place notation.

$compound_pn
This regular expression matches a piece of compound place notation.


FUNCTIONS

The following functions are defined by this module.

bell_to_string()

  $s = bell_to_string($b);

This function takes a number (at least 1) and returns the string representing that bell; for example 12 becomes 'T'.

string_to_bell()


  $b = string_to_bell($s);

This function takes a string representing one bell and returns the number of that bell. If the string is not recognised, it returns 0.

expand_pn()

  my $s = expand(pn($bells, $pn);

This function takes a piece of compound place notation (see above) and puts it into maximal form - that is, with dots between all changes including cross changes, with external places, and with cross changes represented by X. For example, &-2-3,4 becomes X.2.X.3.X.2.X.4.


THE Ringing::PlaceNotation CLASS

The Ringing::PlaceNotation class represents a piece of place notation. It encapsulates the preceding functions in a single class definition.

METHODS

The class defines the following methods.

Constructor

  $pn = new PlaceNotation($bells, $pn_string);

The constructor takes a number of bells and a string of compound place notation (see above).

maximal()

  $s = $pn->maximal();

This function returns the place notation in maximal format. This is how it is stored internally, so there is no overhead as there is for format().

format()

  $s = $pn->format(%options);

This function returns a string containing the place notation, formatted according to the options given in a hash. The following entries in the hash are recognised:

dots
If true, put dots between all changes (including cross changes).

external
If true, include external places; otherwise, remove them.

cross
This hash entry may be X, x or -; it controls which character is used to represent a cross change. The default is X.

symmetry
If this is true, the place notation is checked for symmetry. If it is symmetrical, the result is a string of compound place notation consisting of two pieces, each symmetrical. If the place notation is not symmetrical, this option has no effect.

For example,

  my $pn = new Ringing::PlaceNotation(6, '3-4-25-3-4-5-4-3-25-4-3-2');
  print $pn->format(symmetry => 1, cross => 'x', external => 1);

will print &36x14x1256x36x14x56,12.


AUTHOR

Martin Bright, <martin@boojum.org.uk>


COPYRIGHT AND LICENCE

Copyright (C) 2004 by Martin Bright. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.