MacSiRiL

Preliminary Manual

Overview

MacSiRiL is a kind of macro-processor for place notation. Pieces of place notation are named and expressions constructed from these named pieces to define peal-length sequences of notation. The definitions are entered into the system from the keyboard, or read from a text file. Requests cause MacSiRiL to generate the rows defined by the place notation and use them in various ways, such as listing and proving them, drawing blue lines and extracting false course-heads.

A simple example

The following example shows a typical MacSiRiL session. The lines beginning with were typed in by the user; those beginning with : were typed out by MacSiRiL. The user has typed in a set of definitions for Cambridge Surprise Minor and a request to MacSiRiL to print out the rows of its plain course:

  > half = [-36-14-12-36-14-56] ;
  > lead = half & ;
  > plain = lead , [12] ;
  > course = 5 * plain ;
  > list course ;
  : 123456
  : 214365
  : 124635
  : 216453
      --
  : 123546
  : 213456
  : 124365
  : 123456
  : [ 121 rows; 0.5 secs ]
  >

The first line defines the place notation for the first half-lead of the method. Place notations are written in the usual way and enclosed in square brackets. The piece of place notation is named half using the = (equals) symbol. The semicolon at the end of the line marks the end of the definition.

The second line defines the place notation for a whole lead using the & (ampersand) symbol together with the name half which was defined in the first line. Whenever a name is used in another definition, MacSiRiL uses the piece of place notation which it names. The effect of putting & after a piece of notation is to "double it up" by repeating it in reverse order except for the final (half-lead) place, thus defining a symmetrical piece of notation. The = (equals) symbol is used to name the result lead.

The third line adds the notation for lead-head place to that of lead using the , (comma) symbol, to join two pieces of notation end-to-end. The result is named plain, and it represents the notation of a complete lead of the method.

The fourth line defines the place notation for a whole course using the * (star) symbol. This causes the following piece of place notation to be copied a given number of times (5 in this case) and the copies joined end-to-end. The name course now defines a piece of place notation 240 elements long.

The final line is a request to MacSiRiL to use the place notation defined by the name course to generate the corresponding rows and list them. For clarity, only a few rows at the start and end of the course are shown here. When the request has been completed, MacSiRiL prints a message telling you how many rows were generated and how long the request took. The at the start of the next line shows that MacSiRiL is expecting the user to type in more definitions and requests.

Some things you will naturally ask

When you have digested the example, and perhaps tried it out for yourself, there are several questions which will probably spring to mind, such as:

Is there any significance in the names lead, course and so on?
No, a name can be any word you choose. You can use SuperCaliFragilisticExpiAliDocious if you can be bothered to type it. The only restriction is that names can contain only upper-and lower-case letters. These are distinct by the way, so lead and Lead are considered to be two different words. Also, there's nothing special about the words used for requests to MacSiRiL -- you can define a name list yourself and then enter list list with no confusion (at least, not to MacSiRiL).
Is the spacing important?
Practically never. The examples have lots of spaces to make it easy to see symbols like , (comma) which are a bit inconspicuous, but spaces can always be missed out, except in one case. This is when two words (such as list and course in the example) might be confused as a single word without the space. Similarly, you don't need to start definitions and requests on separate lines (though it may be clearer if you do) and they can spread out over more than one line.
Does it matter what order I enter the definitions?
No, provided all the definitions you need are entered before you make a request that uses them. If you type in the second line
```
  lead = half & ;
```
before you've entered the first one which defines half, MacSiRiL will give you a warning message
```
  [ "half" is not defined yet ]
```
to remind you that its definition still needs to be entered. You can enter it at any time before you enter the list request.
How do I define methods on more than six bells?
No problem; MacSiRiL simply assumes that the number of bells you want to use is the largest place in the notation supplied to list. If it can't discover this (e.g. if the notation contains all X's), MacSiRiL will display the error message
```
  [ Notation contains no digits ]
```
followed by the informatory message
```
  [ "list" not performed ]
```
How many bells can I use?
Up to 16. MacSiRiL uses 1234567890etabcd to represent them. You can also use ETABCD for bells 11-16 if you prefer. The smallest number of bells you can use is one, but you probably won't need a computer for this
Can I use a name more than once?
Yes, using &, * and , on names doesn't change their values, so for instance you could define a plain lead of Primrose by entering an extra definition such as
```
  Primrose = lead , [16] ;
```
and this won't affect the previous definition of Cambridge. Similarly, the definitions aren't changed by the list request, and you can use them in further requests and definitions.
What if I define the same name twice?
There's no confusion; if you enter a second definition for a name, it just replaces the original one. This allows you to correct a definition if you got it wrong first time. You can also remove any definition using the request clear followed by the name you want to remove. Typing
```
  clear ;
```
(i.e.without a name after it) removes all the definitions and allows you start again with a clean slate.
What if I forget what names I've defined?
No problem. You can type
```
  show ;
```
which tells MacSiRiL to display all the current definitions. You can display a single definition by adding a name after the request, e.g.
```
  show lead ;
```
Will MacSiRiL disappear into a black hole if I write something like
```
  a = a ; list a ;
```
Not at all. It checks definitions for circularity as you type them. You probably won't enter anything so obviously stupid by accident, but you might enter a set of definitions which is indirectly circular. For example, entering
```
  a = b ; b = c ; c = a ;
```
will cause MacSiRiL to display the error message
```
  [ Definition of "c" is circular ]
```
and save only the first two definitions. Strictly speaking, all the definitions above are circular, but the last one which "closed the circle" will always be the one that gets rejected
Isn't it a bit longwinded to define names which only get used once?
Yes it is, and no you don't have to. In the example, the final request was
```
  list course ;
```
where course was defined to be 5 * plain. You can get exactly the same effect with
```
list 5 * plain ;
```
and you needn't define course at all. Similarly, in the definition of plain, you can replace lead by its value (half &) and also replace half by its value, so you needn't define lead or plain at all. You can just as well enter:
```
  plain = [-36-14-12-36-14-56] & , [12] ; list 5 * plain ;
```
In the previous example, why didn't we replace plain by its definition as well, and just enter
```
  list 5 * [-36-14-12-36-14-56] & , [12] ;
```
Because it gives the wrong result! When a definition contains more than one operation (i.e. &, * or ,), MacSiRiL does them in a standard order: all the &'s first, then the *'s and finally the ,'s, so the definition of plain was acceptable.
We can change the order by putting brackets round the operations we want be done first. Entering
```
  list 5 * ( [-36-14-12-36-14-56] & , [12] ) ;
```
gives the required result because the * outside the brackets will be done after the & and the ,inside them. Inside the brackets, the & is done before the , as it was in the definition of plain.

At this point I got fed up with pretending to be Steve Coleman and writing manuals in the style of a Teletubbies book (again! again!). But I did write a more concise (complete, but less helpful) summary of the features, so now go on and read that (also includes download information) if you're still interested.