README.md

   1 # Aqua
   2
   3 A ~~toy~~ programming language interpreter
   4
   5 ## building
   6
   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.~~
  10
  11 ~~example: `g++ -o jtc jtc.cpp -std=c++0x -O3`~~
  12
  13 Not anymore! Sorry :-( ... To build jtc, you'll need cmake now.<br />
  14 Quick setup:
  15
  16     mkdir build
  17     cd build
  18     cmake ..
  19     make # be patient!
  20     # all set
  21
  22 The main executable is `aqua`.<br />
  23 The library is 'libaqua.so' (or `aqua.dll` on windows).
  24
  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.
  27
  28 ## syntax
  29
  30 **keywords:**
  31
  32  + **`if`**
  33
  34   Does what it says on the tin.<br />
  35   Example:
  36
  37         if(1 == 2)
  38         {
  39             println("nuh uh!")
  40         }
  41
  42  + **`while`**
  43
  44     Looping.<br />
  45     Example:
  46
  47         while(1 < 2)
  48         {
  49             println("waiting for the impossible. please stand by")
  50         }
  51
  52  + **``**
  53
  54  + **`sizeof`**
  55
  56   Gets the size of an object using `<Container>::size()` (i.e, `Array::size`).<br />
  57   Example:
  58
  59         things = ["foo", "bar", "baz"]
  60         println(sizeof(things))
  61         //same as `println(things.size())`
  62
  63  + **`typeof`**
  64
  65   Gets the type of an object using `Value::typeName()`.<br />
  66   Example:
  67
  68         MyClass = func()
  69         {
  70             local this = {}
  71             ...
  72             return this
  73         }
  74
  75         println(typeof(MyClass))
  76
  77
  78 **Builtin functions and Type member functions**
  79
  80  **Builtins for strings**
  81
  82   todo: still not completely done
  83
  84 **Variables defined by the VM, and implicitly set variables**:
  85
  86  + **`true`**
  87
  88   Evaluates to `1`. Self-explanatory.
  89
  90  + **`false`**
  91
  92   Evaluates to `0`. Self-explanatory.
  93
  94  + **`ARGV`**
  95
  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.
  98
  99  + **`$args`**
 100
 101   Contains all arguments passed to a function. Only defined within a function scope.<br />
 102   Example:
 103
 104         variadic = func()
 105         {
 106             for(arg: $args)
 107             {
 108                 println("arg = ", arg)
 109             }
 110         }
 111
 112         func("foo", [1, 2, 3], "hurf", func(){}, "that's all, folks!")
 113
 114 ## todo
 115
 116 1. ~~Better name? `jtc` is more of a temporary name. Maybe this whole thing grows into something more~~ Update: renamed to `aqua`!
 117
 118 2. JIT-/Bytecode-support is pretty much WONTFIX, but it's nice to think about.
 119
 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*.
 124
 125 4. Wrap the whole mess in a namespace. Pretty much requires point #1.
 126
 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.