C a m o u f l a g e
by Benedict Roeser

Version 0.2.1  -  2005-11-17
	# => 
A very nice draft.

Camouflage is an attempt to create an easy to learn esoteric programming
language.
It's all about disguises. Each disguise serves for a certain purpose. Just read
the manual.


1. Basic syntax

Camouflage is strictly case sensitive.

Note about New-Line-Characters (cr lf): They have to be used. But you can use
more than needed.

1. 1. Mission title

Each program starts with the 'mission title'.
It consists of the reserved keyword 'Mission' and the name/purpose of your
program in ''.
You can use all ASCII symbols.

Example 'Mission title of a scientific calculator':

Mission 'Scientific Calculator'

1. 2. Pages

A program consists of 'pages'. Each program has got at least one 'page'. 
Between the mission title and the first page and between each page has to be a
blank line.
A page starts with the 'Page introduction'. We have to distinguish between
'commentary pages' and 
'deliverable pages'. A commentary page is ignored by the Camouflage
interpreter/compiler, a deliverable page isn't.
Important: A commentary page has to have a correct syntax! It has to consist of
'disguises' and 'commands' as well as 
deliverable pages.

Example 'Page introduction for a commentary page':

This must not be done under any circumstances:

There are no other ways to introduce commentary pages.
Deliverable pages are introduced by:

1. The reserved keyword 'This'
2. The 'importance keywords' which can either be 'is to'/'has to' or 'might'
3. The reserved keyword 'be done'
2. The optional reserved keyword 'immediately'

By using the importance keyword 'might be' the interpreter/compiler can decide
whether to execute the page or not.
This might be interesting for maintenance tasks.

By omitting the keyword 'immediately' the interpreter/compiler can decide when
to execute the page. This might be interesting
for multi-threaded programs.

Example 'Page introduction for a deliverable page:

This is to be done immediately:

A page ends with 'and return after having done so.' or 'but return after having
done so.'
'return after having done so.' is a reserved keyword. 'but' and 'and' will be
handled later.

Each page needs at least one 'disguise' and one 'command'. (Will be explained
later)
The first disguise is alwasy written with the first letter in uppercase.

Example 'Perfectly correct program consisting of two pages (doing nothing at
all)':

Mission 'Doing nothing at all'

This might be done:
As ghost
paint a towel
and return after having done so.

This has to be done immediately:
As security guard
paint guns
and return after having done so.

Between two pages all disguises are removed.
The value of variables however isn't changed. An exception to this rule is the
system variable 'the result' which will be explained later. It's cleared at 
the end of a page.

Jumping from one page to another with the 'follow command' or the 'obey
command' is not possible.


1. 3. How to comment your code

The only way to comment code are commentary pages.
It might be useful to copy the source code of the corresponding deliverable
page into the commentary page
and add a kind of comment string after each line, that should be commented.
Don't worry about performance issues.
If you use a Camouflage compiler it will just throw away all commentary pages
after syntax checking them.
To understand the following example you may have to read the following
chapters.
Note that the disguises used on commentary pages don't do anything.

Example 'Commenting your code, referring to parts of the Mission "Doing nothing
at all"':

This must not be done under any circumstances:
As security guard
paint comment string as sentence
and paint guns
and collect 'COMMENT #42: guns might be important when handling stuff near
comment #77' in comment string
and return after having done so.


2. Disguises

2. 1. Disguise types

There are five types of disguises.
1. security guard
2. slot machine
3. ghost
4. tax collector
5. playwright

A disguise changes the mode in which commands are interpreted.
Between two disguises must be a command.
Several disguises can be added resulting in more than one active command mode.
See 'Adding disguises'.

In 'security guard mode' each command is plausability checked.
No errors are thrown, but default values are used on error.

In 'slot machine mode' there is a fity-fifty chance that a command is executed.
'slot machine mode' has no effect
if 'security guard mode' is active.

In 'ghost mode' commands are executed without visible traces. No text is
outputted, no graphical interface changes, ...
Nevertheless, side effects are computed. E. g. if you have commands in ghost
mode, that store the current screen resolution
in a variable and change the screen resolution to 1024x768 the resolution will
NOT CHANGE, but the variable will be set.

In 'playwright mode' everything is ultra-verbose and the return value of every
command is displayed after the execution of
the command.
'playwright mode' has no effect if 'ghost mode' is active.

In 'tax collector mode' all variable or constant values are substituted by user
input.
If 'security guard mode' is active and impossible values are entered by the
user, default values are taken.
If 'ghost mode' is active the urge for user input will not be shown in any way
(No popup windows with
'Please enter something:', no blinking cursor on the console, ...)
The following example will ask for user input. If no integer or a number
smaller than 0 is given 'security guard mode' will
overwrite the results of 'tax collector mode' with the given 'default value'
12.

Example 'tax collector mode with security guard mode':

Mission 'Doing stuff'

This has to be done immediately:
As security guard
paint dollars
and paint bucket as storage for dollars
and as tax collector
collect 12 dollars in bucket
and return after having done so.

2. 2. Adding disguises

As already shown in the last example, disguises can easily be added. It's
possible to add all five disguises, but you should 
be absolutely sure to know what you are doing.

Disguises are added with the keyword 'and'. It's impossible to add a disguise
which is already added.

Example: 'and as security guard'

2. 3. Substituting disguises

The last disguise which was added(/the only disguise) can be substitued with
the keyword 'but'.
It's impossible to substitute a disguise with another one wich is already
added.
It's impossible to substitute a disguise with itself.

Example: but as ghost

2. 4. Removing disguises

Disguises can't be removed before the end of a page, they just can be
substituted with other disguises.
That means: If you add two disguises, the first one can't be changed to any
other disguise!
All disguises are removed with the end of a page.


3. Variables

3. 1. Basic data types

There are numbers and sentences. numbers are floating point values, sentences
are strings.
Variables are defined with the 'paint command', a variable name and the
reserved keyword 'as'.
A variable name can consist of ASCII-Characters from a to z and A to Z and a
space ' '.
Remember that Camouflage is strictly case sensitive.

Example 'Basic data types':

This has to be done immediately:

As ghost
paint AfunnyVariableWithoutSpaces as number
and paint a funny variable with spaces as sentence
and paint a funny variable WITH spaces as number
and return after having done so.

3. 2. Something similar to a class

There is something similar to a 'class'. Certainly it isn't a real class, but
it's similar.
We will refer to it as 'class'.
Such a class can be used to create something similar to an 'object'. We will
refer to it as 'object'.
An object can have 'properties'. Properties (also called member variables) can
be numbers, sentences or other objects.
Properties can be added and set with the 'collect command'.
The following example creates the class 'books', the property 'author'
and the object 'Peter Pan' which is of the class 'books'.
There are no methods.

Example 'Similarities':

This is to be done immediately:
As security guard
paint books
and paint author as sentence
and collect author in books
and paint Peter Pan as books
and collect 'some guy' in author
and collect author in Peter Pan
and return after having done so.

3. 3. Lists

A 'list' is a bulk of either numbers or sentences or objects.
A list is created by painting it with the reserved keyword 'as storage for' and
a class/basic data type.
A list can either be filled with certain objects (like 'Peter Pan' in the
following example') or with
freshly created empty ones (like '20 books', '15 sentence', ...).
Empty objects of the class 'books' will be, well, empty.
Empty sentences will be ''. Empty numbers will be zero/0.

Example 'A list':

This is to be done immediately:
As security guard
paint books
and paint StringStack as storage for sentence
and paint numberstack as storage for number
and paint the bookshelve as storage for books
and paint Peter Pan as books
and collect 20 books on the bookshelve
and collect Peter Pan on the bookshelve
and collect 20 number in numberstack
and collect 15 sentence in StringStack
and return after having done so.

Lists can be limited to a certain size using the command 'set', a size
(integer),
the reserved keyword 'as limititation for', the data type of the list, the
reserved keyword 'in' or 'on',
the name of the list. List limitations can be set to other values during
runtime, but can't be removed.
In 'security guard mode' the violation of a limitation is quietly regulated by
just filling the available space.
In 'playwright mode' with active 'security guard mode' the violation of a
limitation is shown as warning.

Example 'limit a list':

This is to be done immediately:
As security guard
paint books
and paint the bookshelve as storage for books
and set 30 as limitation for books on the bookshelve
and collect 35 books on the bookshelve
and set 45 as limitation for books on the bookshelve
and return after having done so.

3. 4. Example 'Showing lists and objects':

This example will return the following sentences:
21 books on the bookshelve, including Peter Pan.
231 pages in Peter Pan.


Mission 'Something which pretends to be similar to an object-oriented program'

This is to be done immediately:

As security guard
paint pages
and paint books as storage for pages
and paint the bookshelve as storage for books
and paint Peter Pan as books
and collect 231 pages in Peter Pan
and collect 20 books on the bookshelve
and collect Peter Pan on the bookshelve
and paint a random sentence as sentence

and as playwright
count all books on the bookshelve
and collect ' books on the bookshelve, including Peter Pan.' in a random
sentence
and count all pages in Peter Pan
and collect ' pages in Peter Pan.' in a random sentence

and as ghost
collect 'Scary stuff!' in a random sentence
and return after having done so.

3.5 Reserved system variables

There are 3 reserved system variables.

1. the result
2. the time
3. the line

The reserved system variable 'the result' contains the return value of the last
command / control structure.

'the time' contains a current timestamp.
'the line' contains the current line number.

Example 'the result':

As security guard
paint dollars
and paint the bucket as storage for dollars
and paint the other bucket as storage for dollars

and as tax collector
collect 5 dollars in the bucket

but as playwright
count all dollars in the bucket
and collect the result in the other bucket
and compare the result with 5
and return after having done so.

The 'collect command' returns its primary parameter.
The 'take command' returns the taken thing.
The 'count all' command returns what it has counted.

ALL other commands will return the number 0/zero.


4. Commands

All commands have to be connected with the reserved keyword 'and'. There are
indeed exceptions to this rule.

4. 1. List of commands and control structures

command   explanation

collect   sets a variable, automatically appends cr/lf (collect 'fo' in/on bar)
compare   comparing (Only works with 'the result': compare the result with 5)
count all counting elements in a list (count all books on bookshelve)
follow    jump to next disguise (optional keywords: 'on success'/'on failure')
obey      jump to last disguise (optional keywords: 'on success'/'on failure')
order     import a class/variable/list definition mission, can't be nested
paint     initializing a variable/a list of variables/a class (paint books)
rephrase  collect w/o crlf, works on sentences only (rephrase bar to 'foobar')
set       setting a limitation (set 40 as limitation for books on bookshelve)
split     dividing a list by removing 'empty objects' or 'certain objects'
steal     removing something painted and freeing its memory
take      a. remove object from a list ('empty objects'/'certain objects')
          b. storing a property in 'the result' (take author of Peter Pan)

Please note that the 'steal command' won't work in 'security guard mode'.

Examples 'follow/obey are similar to goto':
follow the tax collector on success ('on success' is compared to the value of
'the result')
and obey the ghost

For an example of the 'order command' see the chapter about file I/O.

Examples 'collect ... on/in, take ... of/from, split ... by':

This is similar to +, -, /, *, =

collect Peter Pan on the bookshelve
and collect 9 books on the bookshelve
and split the bookshelve by 2           
   - will remove 5 'empty objects'/5 books
and split the bookshelve by Peter Pan 
   - will remove every object from the bookshelve but 'Peter Pan'
and take Peter Pan from bookshelve    
   - will remove 1 'Peter Pan' object
and take 3 books from bookshelve        
   - will remove 3 'empty objects'/(all 3 books beeing not 'Peter Pan')
and take 2 number from numberstack
and take 7 from numberstack
and take all number from numberstack
and take author of Peter Pan
   - will store the object's property 'author' in 'the result'

4. 2. 'and' and 'but'

The reserved keyword 'and' is used when 'but' isn't used. The first command
after Adding or switching a disguise must not
be introduced by 'and'. The first disguise on a page must not be introduced by
'and'. Apart from that almost every
line will have an 'and'. Exceptions are of course the mission title and the
page introduction.

The reserved keyword 'but' is used when comparing something with 'the result'.
It's similar to something called 'else'.

Example 'compare, but, the result':

count all number in numberstack
and compare the result with 3
and take 1 from numberstack on success - will remove the number 1 from
numberstack if there are exactly 3 numbers on stack
but take 1 number from numberstack on failure  - otherwise one 0 is removed
from the stack

4. 3. File I/O

File I/O is realized with the system defined class file which is made out of
the following source code. You needn't copy the source code to your program.
It is perfectly sufficient to use the 'order command' as shown in the second
example.

Example 'file class - should be used with the order command':

Mission 'a file'

This is to be done immediately:
As ghost
paint file
and paint filename as sentence
and collect filename in file
and paint lines as storage for sentence
and paint char as sentence
and set 1 as limitation for sentence in char
and paint characters as storage for char
and collect lines in file
and collect characters in file
and return after having done so.

As you can easily imagine you can open a file for input/output by using the
'collect command' on a filename of a 'file object'.
There are two predefined properties called characters and lines, both beeing
lists. You can access a file by its lines or by its individual characters.
Writing to the file is done by using the 'collect command', the 'couple
command', the 'rephrase command', or the 'steal command' reading from the file
is done e.g by using the 'take command'.
The filesize can be easily determined by using the 'count all command' on the
character list.

The following example puts the size of a file in the variable 'filesize' and
the first line in the variable 'firstline'.

Example 'Working with files':

This is to be done immediately:
As security guard
order a file
and paint document as file
and paint filename as sentence
and paint firstline as sentence
and paint filesize as number
and paint a temporary list as storage for sentence
and collect 'mydoc.txt' in filename
and collect filename in document
and take characters of document
and collect the result in a temporary list
and count all sentence in a temporary list
and collect the result in filesize
and take lines of document
and collect the result in a temporary list
and take 1 sentence of lines
and collect the result in firstline
and return after having done so.

4. 4. Manipulating a mission's title and source code

Besides the system defined class 'a file' there is a system defined class 'mission'.
The current mission is always identified by the variable 'this mission'.

The class 'mission' is defined in the mission 'for great justice'.

Example 'The source code for the predefined system objects':

Mission 'great justice'

This is to be done immediately:
As ghost
paint mission
and paint filename as sentence
and paint the mission title as sentence
and paint pages as number
and collect filename in mission
and collect the mission title in mission
and collect pages in mission
and return after having done so.

Properties of 'this mission':
filename           the name (of the file with the 'order command')
the mission title  the mission title (see above, when painted)
pages              the number of pages (see above)

As you can easily see, it is possible to combine the 'this mission' object with
the file I/O structures for getting the file size of your program!
It's also pretty easy to append the current time to the mission title of your
program, as the following example shows.
The stack of strings serves as concat-glue. The slot machine is needed to use
the 'steal command'. The 'ghost disguise' can't be used because the mission
'great justice', which is ordered by the 'security guard mode' already uses
the 'ghost disguise' and disguises can't be substituted by itself (see the
chapter for substituting disguises for more information). The 'security guard'
mode, on the other hand can't be used, because the 'steal command' won't work
in this mode. Ultra-verbosity and user input is not requested, so only the
'slot machine mode' remains. The fifty-fifty chance is removed by the line
'obey the slot machine on failure'. Everything else should be clear.

Example 'Doing stuff with the mission title':

This is to be done immediately:

As security guard
order great justice
and paint this mission as mission
and paint a stack of strings as storage for sentence
and paint the mission title as sentence
and take the mission title of this mission
and collect the result in a stack of strings
and collect the time in a stack of strings
and collect a stack of strings in the mission title
and collect the mission title in this mission
but as slot machine
steal this mission
but as security guard
obey the slot machine on failure
but paint this mission as mission on success
and return after having done so.
 

5. Examples

Mission 'Hello World!'

This is to be done immediately:

As security guard
paint a random sentence as sentence

and as playwright
collect 'Hello World!' in a random sentence

and as ghost
collect 'random stuff' in a random sentence
and return after having done so.


6. You're done.

Congratulations! You know everything about Camouflage v0.2.1!
Go and hack some funny programs for it.