git @ Cat's Eye Technologies ALPACA / 0f8dfda
Convert documentation to Markdown. More to come... --HG-- rename : doc/alpaca.html => README.markdown catseye 12 years ago
3 changed file(s) with 116 addition(s) and 136 deletion(s). Raw diff Collapse all Expand all
+116
-0
README.markdown less more
0 ALPACA
1 ======
2
3 Language
4 --------
5
6 **ALPACA** stands for **a** **l**anguage for **p**rogramming
7 **a**rbitrary **c**ellular **a**utomata.
8
9 Cellular Automata
10 -----------------
11
12 While [RUBE](http://catseye.tc/node/RUBE.html) was being developed it became
13 clear to the author that the "bully" approach to writing a complex cellular
14 automaton would result in a program extremely difficult to understand and even
15 worse to maintain.
16
17 ALPACA was developed in order to have a terse, precise and readable
18 language in which to express the rules for any given cellular automaton.
19 It is in ALPACA, then, that [REDGREEN](http://catseye.tc/node/REDGEEN.html),
20 a successor to RUBE, is written. Being described in ALPACA instead of C,
21 the source code for REDGREEN is easily a hundred times clearer than the
22 knotted mess that is RUBE.
23
24 Other cellular automata that have been successfully described in ALPACA
25 include John Conway's famous Game of Life automaton and the lesser-known
26 WireWorld automaton.
27
28 Implementation
29 --------------
30
31 You can download a copy of the ALPACA v0.90 distribution from this web
32 server. It contains Perl 5 source code, documentation, example ALPACA
33 descriptions, and example automaton forms to use for them.
34
35 The compiler has now been hand-coded in Perl 5 (instead of C
36 automatically generated by CoCo/R, as was in v0.80) and produces a Perl
37 program that accepts an automaton form (a start state) as input, in the
38 form of an ASCII text file, and animates it.
39
40 Documentation
41 -------------
42
43 In brief, a description of a Cellular Automaton (CA) in ALPACA consists
44 of a number of state or class declarations, seperated with semicolons
45 and ending with a period.
46
47 A state declaration defines a state, associates a visual element with it
48 (currently an ASCII character, possibly someday a colour or graphic) and
49 is followed by a list of transition rules seperated by commas.
50
51 A class declaration defines a class of states. Each state can belong to
52 many classes, and are listed in overload order. Classes can have their
53 own rules, and the `is` operator can be used to check for any of the
54 states of a class instead of a single state.
55
56 A transition rule specifies a state to change to and a boolean
57 expression to evaluate to see if that state should be changed to. The
58 expression may make use of whether there are a certain minimum number of
59 neighbours of a state or class, whether neighbours in certain positions
60 hold a certain state or class, and constant true, false, and random
61 boolean terms, manipulated by infix boolean operators.
62
63 (A more rigorous and complete specification is underway.)
64
65 As an example, here is John Conway's Game of Life automaton, expressed
66 in ALPACA (it's short):
67
68 state Dead " "
69 to Alive when 3 Alive and 5 Dead;
70 state Alive "*"
71 to Dead when 4 Alive or 7 Dead.
72
73 Grammar
74 -------
75
76 Whitespace is ignored between tokens, and comments extend from
77 `/*` to `*/` and do not nest.
78
79 AlpacaProgram ::= Entries ".".
80 Entries ::= Entry {";" Entry}.
81 Entry ::= Class | State.
82 Class ::= "class" ClassID {ClassDesignator} [Rules].
83 State ::= "state" StateID [Appearance] {ClassDesignator} [Rules].
84
85 ClassID ::= identifier.
86 StateID ::= identifier.
87 Appearance ::= character.
88
89 ClassDesignator ::= "is" ClassID.
90
91 Rules ::= Rule {"," Rule}.
92 Rule ::= "to" StateDesignator "when" Expression.
93
94 Expression ::= Term {("and" | "or" | "xor") Term}.
95
96 Term ::= AdjacentcyFunc
97 | "(" Expression ")"
98 | "not" Term
99 | BoolPrimitive
100 | RelationalFunc.
101
102 RelationalFunc ::= StateDesignator (StateDesignator | ClassDesignator).
103
104 StateDesignator ::= "n" | "^" | "nw" | "^<"
105 | "s" | "v" | "ne" | "^>"
106 | "w" | "<" | "sw" | "v<"
107 | "e" | ">" | "se" | "v>" | "me" | StateID.
108
109 AdjacentcyFunc ::= ("1" | "2" | "3" | "4" | "5" | "6" | "7" | "8")
110 (StateDesignator | ClassDesignator).
111
112 BoolPrimitive ::= "true" | "false" | "guess".
113
114 character ::= quote printable-non-quote quote.
115 identifier ::= alpha {alpha | digit}.
+0
-90
doc/alpaca.html less more
0 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
1 <!-- encoding: UTF-8 -->
2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
5 <title>Cat's Eye Technologies: ALPACA: A Language for Programming Arbitrary Cellular Automata</title>
6 <!-- begin html doc dynamic markup -->
7 <script type="text/javascript" src="/contrib/jquery-1.6.4.min.js"></script>
8 <script type="text/javascript" src="/scripts/documentation.js"></script>
9 <!-- end html doc dynamic markup -->
10 </head>
11 <body>
12
13 <h1>ALPACA</h1>
14
15 <h2>Language</h2>
16
17 <p><b>ALPACA</b> stands for <b>a</b> <b>l</b>anguage for <b>p</b>rogramming
18 <b>a</b>rbitrary <b>c</b>ellular <b>a</b>utomata.</p>
19
20 <h2>Cellular Automata</h2>
21
22 <p>While <a href="/projects/rube/">RUBE</a> was being developed it
23 became clear to the author that the "bully" approach to writing a
24 complex cellular automaton would result in a program
25 extremely difficult to understand
26 and even worse to maintain.</p>
27
28 <p>ALPACA was developed in order to have a terse, precise and readable
29 language in which to express the rules for any given cellular
30 automaton. It is in ALPACA, then, that <a href="../eg/redgreen/">REDGREEN</a>,
31 a successor to RUBE,
32 is written. Being described in ALPACA instead of C,
33 the source code for REDGREEN is easily a hundred times clearer than
34 the knotted mess that is RUBE.</p>
35
36 <p>Other cellular automata that have been successfully described in
37 ALPACA include John Conway's relatively famous <a href="../eg/life/">Game of Life</a> automaton
38 and the lesser-known <a href="../eg/wireworld/">WireWorld</a> automaton.</p>
39
40 <h2>Implementation</h2>
41
42 <p>You can download a copy of the ALPACA v0.90 distribution
43 from this web server.
44 It contains Perl 5 source code, documentation, example ALPACA descriptions,
45 and example automaton forms to use for them.</p>
46
47 <p>The compiler has now been hand-coded in Perl 5 (instead of C
48 automatically generated by CoCo/R, as was in v0.80) and produces a Perl program
49 that accepts an automaton form (a start state) as input, in the form of an ASCII text file, and
50 animates it.</p>
51
52 <h2>Documentation</h2>
53
54 <p>In brief, a description of a Cellular Automaton (CA) in
55 ALPACA consists of a number of state or class declarations,
56 seperated with semicolons and ending with a period.</p>
57
58 <p>A state declaration defines a state, associates a visual
59 element with it (currently an ASCII character, possibly someday a colour
60 or graphic) and is followed by a list of transition rules
61 seperated by commas.</p>
62
63 <p>A class declaration defines a class of states. Each state
64 can belong to many classes, and are listed in overload order.
65 Classes can have their own rules, and the <code>is</code> operator can
66 be used to check for any of the states of a class instead of
67 a single state.</p>
68
69 <p>A transition rule specifies a state to change to and a
70 boolean expression to evaluate to see if that state should
71 be changed to. The expression may make use of whether there
72 are a certain minimum number of neighbours of a state or class,
73 whether neighbours in certain positions hold a certain state
74 or class, and constant true, false, and random boolean terms,
75 manipulated by infix boolean operators.</p>
76
77 <p>For more detail see the <a href="ebnf.txt">EBNF</a>
78 description of the grammar, and examine the source for the REDGREEN
79 automaton in detail.</p>
80
81 <p>As an example, here is John Conway's <a href="../eg/life/">Game of Life</a> automaton,
82 expressed in ALPACA (it's short):</p>
83
84 <pre>state Dead " "
85 to Alive when 3 Alive and 5 Dead;
86 state Alive "*"
87 to Dead when 4 Alive or 7 Dead.</pre>
88
89 </body></html>
+0
-46
doc/ebnf.txt less more
0 The non-attributed grammar for ALPACA, v0.90 BETA.
1 --------------------------------------------------
2
3 IGNORE CHR(9)..CHR(13), COMMENTS FROM "/*" TO "*/"
4
5 TOKENS
6 character = quote printable-non-quote quote .
7 identifier = alpha {alpha | digit} .
8
9 PRODUCTIONS
10 AlpacaProgram = Entries "." .
11 Entries = Entry {";" Entry} .
12 Entry = Class | State .
13 Class = "class" ClassID {ClassDesignator} [Rules] .
14 State = "state" StateID [Appearance] {ClassDesignator} [Rules] .
15
16 ClassID = identifier .
17 StateID = identifier .
18 Appearance = character .
19
20 ClassDesignator = "is" ClassID .
21
22 Rules = Rule {"," Rule} .
23 Rule = "to" StateDesignator "when" Expression .
24
25 Expression = Term {("and" | "or" | "xor") Term} .
26
27 Term = AdjacentcyFunc
28 | "(" Expression ")"
29 | "not" Term
30 | BoolPrimitive
31 | RelationalFunc .
32
33 RelationalFunc = StateDesignator (StateDesignator | ClassDesignator) .
34
35 StateDesignator = "n" | "^" | "nw" | "^<"
36 | "s" | "v" | "ne" | "^>"
37 | "w" | "<" | "sw" | "v<"
38 | "e" | ">" | "se" | "v>" | "me" | StateID .
39
40 AdjacentcyFunc = ("1" | "2" | "3" | "4" | "5" | "6" | "7" | "8")
41 (StateDesignator | ClassDesignator).
42
43 BoolPrimitive = "true" | "false" | "guess".
44
45