OK, at the moment no-one is developing the program apart from myself. But it struck me that if I documented a few things as if people were, then I’d have a lot of stuff ready if ever I get a co-developer or even hand on the project.
The Canal Planner situation has, I think, shown us the danger of a project like this being all in the mind of one individual.
So what I’ll be doing from time to time is documenting how I did particular things, in a sort of “tutorial” way. But before I do that, I thought I’d start with a sort of apology for the number of languages (big and small) used in CanalPlanAC. I thought it might be fun to document them all – but don’t let this put anyone off: you don’t need all of them at any one time.
- C – the Interpreter that underlies CanalPlanAC is written in C. This can remain unchanged for months, until I discover a bug or find the need to add a feature right into the language. What tends to happen is that I write something in the scripting langauge but find it too slow or too cumbersome, so add it as a language feature instead. There is – as yet – no modular extensibility to the C: there are about 35 thousand lines of C in 87 source files that I’ve written,and a chunk more in various pieces of “foreign” code that are linked in.
- CanalPlanAC scripting language. I have no name for this language, which can be invoked interactively by /cgi-bin/canal/ or to execute a file as /cgi-bin/canal file.can. This is a basic like language that deserves another dozen items on the syntax. It was vaguely inspired by Superbasic which could give you a few pointers to some of the syntax. Key things about it are:
- An intermediate typing system where all values are one of a number of types, and get coerced from one to the other when assigned.
- Support for associative arrays (called “lookup” tables) and lists
- Inline operators: this is a mixed blessing – a line like «if a contains “hello” then …» is easy to read, but precedence sometimes goes wrong. (So «print ‘this is me and you’ after ‘me’ contains ‘you’» produces the whole string (because it parses as evalutate «’me’ contains ‘you’» which is 0, then returns the original string after character 0.
- Built-in comprehension of a waterways network with the ability to plan routes aroung it and travel along them.
- Built-in read/write of SQL, JSON and XML
- There are a few small bash scripts, mainly to kick off CanalPlan programs.
- There is the whole automake/autoconf nest of snakes in /source/ but that shouldn’t need touching.
- Many web pages use Javascript (both home written and some appropriately licensed utilities) to do place name lookup, display maps etc.
Next – the data formats that these programs use to store data, communicate with them selves and talk to the user