`if .. else if ..` can now be used as a primary expression (i.e., `println(if(1 ...
[aqualang.git] / README.md
blob827a2c077e3b26522bd39d5d16cf94a8241d34a0
1 # Aqua
3 A ~~toy~~ programming language interpreter
5 ## building
7 ~~the jtc interpreter has no dependencies and sits in a single C++ file.~~
8 ~~C++11 capable compilers should compile it without extra options other~~
9 ~~than enabling C++11.~~
11 ~~example: `g++ -o jtc jtc.cpp -std=c++0x -O3`~~
13 Not anymore! Sorry :-( ... To build jtc, you'll need cmake now.<br />
14 Quick setup:
16     mkdir build
17     cd build
18     cmake ..
19     make # be patient!
20     # all set
22 The main executable is `aqua`.<br />
23 The library is 'libaqua.so' (or `aqua.dll` on windows).
25 The entire API (which is still awaiting some rewrital) is in include/aqua.h.<br/>
26 For now, `src/main.cpp`, as well as `src/stdlib*.cpp` need to suffice as API examples ... though I'm working on better examples.
28 ## syntax
30 **keywords:**
32  + **`if`**
34   Does what it says on the tin.<br />
35   Example:
37         if(1 == 2)
38         {
39             println("nuh uh!")
40         }
42  + **`while`**
44     Looping.<br />
45     Example:
47         while(1 < 2)
48         {
49             println("waiting for the impossible. please stand by")
50         }
52  + **``**
54  + **`sizeof`**
56   Gets the size of an object using `<Container>::size()` (i.e, `Array::size`).<br />
57   Example:
59         things = ["foo", "bar", "baz"]
60         println(sizeof(things))
61         //same as `println(things.size())`
63  + **`typeof`**
65   Gets the type of an object using `Value::typeName()`.<br />
66   Example:
68         MyClass = func()
69         {
70             local this = {}
71             ...
72             return this
73         }
75         println(typeof(MyClass))
78 **Builtin functions and Type member functions**
80  **Builtins for strings**
82   todo: still not completely done
84 **Variables defined by the VM, and implicitly set variables**:
86  + **`true`**
88   Evaluates to `1`. Self-explanatory.
90  + **`false`**
92   Evaluates to `0`. Self-explanatory.
94  + **`ARGV`**
96   Contains the arguments passed to a script or `-e`. Only set by the main interpreter;
97   You'll have to define it yourself if you embed aqua.
99  + **`$args`**
101   Contains all arguments passed to a function. Only defined within a function scope.<br />
102   Example:
104         variadic = func()
105         {
106             for(arg: $args)
107             {
108                 println("arg = ", arg)
109             }
110         }
112         func("foo", [1, 2, 3], "hurf", func(){}, "that's all, folks!")
114 ## todo
116 1. ~~Better name? `jtc` is more of a temporary name. Maybe this whole thing grows into something more~~ Update: renamed to `aqua`!
118 2. JIT-/Bytecode-support is pretty much WONTFIX, but it's nice to think about.
120 3. ~~Rewrite of the API. Many parts are as good as it gets (though tend to be arguably awkward -- see `src/ops.cpp`), but there's a slight template-induced codesmell.~~<br />
121 ~~Having a better API might also reduce compile times, and make it easier to optimize.~~
122 Let's reword that: There's need to bring in a lil' order in some of the messier places. There are still a handful of
123 global functions that *might* prove problematic. *Might*.
125 4. Wrap the whole mess in a namespace. Pretty much requires point #1.
127 5. Better runtime library. Not really a priority for now, though. Starting points can be found in `src/{private.h,stdlib*.cpp}`. Update: Currently in progress.