/ About Arana /

                             //  \\
                           / //  \\ \
                            | \__/ |

       Arana is a simple object oriented language that is
       designed for web applications and inspired by PHP,
      Python, Ruby with an implementation that is heavily
                  inspired by Lua and Potion.

    / Implementation /

        Arana is a very small and simple programming language
        that tries to take the coolest elements of PHP, Python
        and Ruby and put it into a new language developed
        especially for web applications.

    / Features? /

        What makes Arana different from other languages:

        o Tiny runtime and a standard library implemented in
          arana itself.

        o Module-level "monkey patching".  Classes can be
          changed at runtime on a per-module scope similar to
          C#'s extension methods.

        o Multiple interpreters.  The core is implemented in a
          way that you can run multiple interpreters next to
          each other.  This makes it easily possible to embedd
          Arana into web server modules and applications.

    / Object Implementation Details /

        Arana makes some assumptions of the architecture to keep
        the code simple.

        ~ Tagged Integers ~

        Among other things Arana uses tagged integers.  The
        assumption is that the system will only use even numbers
        for memory addresses so the odd ones can be used to store

        When a conversion from a C integer into a tagged Arana
        integer happens the value is left shifted by one and 1
        is added to make the number odd.  The reverse operation
	is right shifting by one.

    / Arana Signature Functions /

        Many functions in arana have signature prefixed with
        AR_SIG.  This macro expands to an extended function
        signature that includes state variables.  The exact
        number of variables may vary.  Per definition only
        functions marked with AR_SIG may invoke other AR_SIG
        functions.  This is done by passing AR_ISIG as first
        argument to the called function.

        Many macros depend on being called in an AR_SIG function.

        Strictly speaking all functions invoked from Arana
        bytecode are marked with AR_SIG.

        Example AR_SIG function:

          static AR
          arana_integer_add(AR_SIG, AR self, AR args)
              AR other;
              AR_PARSE(args, "N::add", &other);
              return AR_INTEGER(AR_AS_LONG(self) +

        Some of the macros in this function are taking advantage
        of AR_SIG variables.  To invoke another AR_SIG function
        the AR_ISIG macro can be used:

          arana_call(AR_SIG, AR object, AR args)
              return arana_call_with_self(AR_ISIG, object,
                                          AR_NONE, args);

        AR_ISIG forwards all AR_SIG parameters.

    / Multiple Interpreters and Contexts /

        Arana is designed to support multiple interpreters
        running at the same time in the same process.  This is
        achieved by explicitly passing the active interpreter
        and context to every function invoked.  The ARG_SIG and
        ARG_ISIG macros are used to keep the code clean and

        The interpreters store the loaded modules in a hash map
        and are used to store exception values for the exception
        system.  The flags for the code execution on the other
        hand are stored in the arana contexts.

        When the code is executed Arana creates a new root
        context and module with the context globals pointing to
        the module variables.

        Whenever a method of an object is called the following
        method lookup takes place:

        1.  for heavy objects have a look into the object's dict
            for callable objects.
        2.  continue looking for invokable methods in the type's
            method table.
        3.  If there is still no method the lookup continues in
            the current context and all outer contexts.  This
            allows module-based extension methods.