A rule parser for MicroWorld
While this code works and is interesting on its own, you also need at least mw-engine and mw-ui. There will be other modules in due course.
You can see MicroWorld in action here - but please don't be mean to my poor little server. If you want to run big maps or complex rule-sets, please run it on your own machines.
Main entry point is (parse-rule string), where string takes a form detailed in grammar, below. If the rule is interpretted correctly the result will be the source code of a Clojure anonymous function; if the rule cannot be interpretted, an error 'I did not understand...' will be shown.
The function (compile-rule string) is like parse-rule, except that it returns a compiled Clojure anonymous function.
The generated function is a function of two arguments
- cell a cell in a world as defined in mw-engine.world, q.v.;
- world the world of which that cell forms part.
It returns a new cell, based on the cell passed.
Actions of the rule will (can only) modify properties of the cell; there are two properties which are special and SHOULD NOT be modified, namely the properties x and y.
Each time the world is transformed, exactly the same set of rules is applied to every cell. The rules are applied to the cell in turn, in the order in which they are written in the rule text, until the conditions of one of them match the cell. The actions of that rule are then used to transform the cell, and the rest of the rules are not applied.
So, for example, if your first rule is
if x is more than -1 then state should be new
then no matter what your other rules are, your world will never change, because all cells have x more than -1.
If you are having problems because one of your rules isn't working, look to see whether there is another rule above it which is 'blocking' it.
- Any line which starts with the hash character (#) is ignored;
- Any line which starts with a semi-colon (;) is ignored.
A rule comprises:
- if conditions then actions
Each rule must be on a single line. There should be nothing else on that line.
In rules, conditions is one of:
- condition
- condition and conditions
- condition or conditions
Note that 'and' takes precedence over or, so
conditionA and conditionB or conditionC and conditionD
is interpreted as
(conditionA and (conditionB or (conditionC and conditionD)))
A condition is one of:
- property is value
- property is not value
- property is in values
- property is not in values
- property is more than numeric-value
- property is less than numeric-value
- number neighbours have property equal to value
- number neighbours have property more than numeric-value
- number neighbours have property less than numeric-value
- more than number neighbours have property equal to value
- fewer than number neighbours have property equal to value
- some neighbours have property equal to value
- more than number neighbours have property more than numeric-value
- fewer than number neighbours have property more than numeric-value
- some neighbours have property more than numeric-value
- more than number neighbours have property less than numeric-value
- fewer than number neighbours have property less than numeric-value
- some neighbours have property less than numeric-value
Note that everywhere above I've used 'neighbours', you can use 'neighbours within distance', where distance is a (small) positive integer.
A cell has eight immediate neighbours - cells which actually touch it (except for cells on the edge of the map, which have fewer). If the cell we're interested in is the cell marked 'X' in the table below, its immediate neighbours are the ones marked '1'. But outside the ones marked '1', it has more distant neighbours - those marked '2' and '3' in the table, and still more outside those.
| 3 | 3 | 3 | 3 | 3 | 3 | 3 |
| 3 | 2 | 2 | 2 | 2 | 2 | 3 |
| 3 | 2 | 1 | 1 | 1 | 2 | 3 |
| 3 | 2 | 1 | X | 1 | 2 | 3 |
| 3 | 2 | 1 | 1 | 1 | 2 | 3 |
| 3 | 2 | 2 | 2 | 2 | 2 | 3 |
| 3 | 3 | 3 | 3 | 3 | 3 | 3 |
If a rule just says 'neighbours', and not 'neighbours within', it means 'neighbours within 1'; so
if some neighbours are scrub then state should be scrub
has exactly the same meaning as
if some neighbours within 1 are scrub then state should be scrub
In these rules, actions is one of:
- action
- action and actions
and action is:
- property should be value
- number chance in number property should be value
In the above, property is the name of any property of a cell. Any alpha-numeric string of characters can form the name of a property. Actions should NOT try to change the reserved properties x and y.
Values in conditions and actions are considered slightly differently. In a condition, a value is one of:
- symbolic-value
- numeric-value
The '...more than...' and '...less than...' conditions imply a numeric-value. Thus "if altitude is more than fertility..." is interpreted as meaning "if the value of the property of the current cell called 'altitude' is greater than the value of the property of the current cell called 'fertility'", whereas the apparently similar condition 'if altitude is fertility...' is interpreted as meaning "if the value of the property of the current cell called 'altitude' is the symbol 'fertility'".
Thus symbolic-value is any sequence of alphanumeric characters, whereas numeric-value is one of:
- number
- property
and number is any sequence of the decimal digits 0...9, the minus character '-' and the period character '.', provided that the minus character can only be in the first position, and the period character can only appear once.
A value in an action is one of
- symbolic-value
- arithmetic-value
- number
where arithmetic-value is:
- property operator numeric-value
and operator is one of the simple arithmetic operators '+', '-', '*' and '/'.
Note that '...neighbours are...' is equivalent to '...neighbours have state equal to...', and 'some neighbours...' is equivalent to 'more than 0 neighbours...'
The existing parser, mw-parser.core, works but is not well written. A much better parser which does not yet completely work, mw-parser.insta, is also included for the adventurous.
I intend to replace mw-parser.core with mw-parser.insta as soon as mw-parser.insta correctly parses all the test rules.
Copyright © 2014 Simon Brooke
Distributed under the terms of the GNU General Public License v2