OSDev.org

The H Programming Language
---------------------------------
           19 September 2007 0.02
http://messiahandrw.netfast.org

Execution Environment
---------------------------------
The environment consists of at
least 5000 units of memory
storage and at least 512 units of
stack storage. The environment
begins with the all memory set to
0 and nothing on the stack. The
pointer position begins pointing
to the first unit in memory. A
unit is at least 8 bits in
length. The program begins
executing from the first
instruction and continues until
there are no more instructions to
execute.

H Standard Library
---------------------------------
To be implemented.

---------------------------------
Execution Notes

- Brainf*ck code should execute
   correctly without requiring
   modification.
- If the pointer position is
   moved past beyond the bounds
   of the memory, then the
   pointer is wrapped around to
   the other side of the memory.
- If a value has been decreased
   below 0 or increase above the
   maximum value stored in a
   memory unit, then the value is
   wrapped around.
- If a closing nest is reached
   with no opening nest, then
   the debugger will be alerted
   in debug mode or the command
   will be ignored in release
   mode.
- If a value is pushed on to the
   stack and there is no stack
   space remaining, then the
   value is ignored.
- If a value is popped from the
   stack and the stack is empty,
   then the stack will return
   the value 0.
- If a ( is executed, then the
   program will to the
   instruction after the next
   ). Code between ( and ) is
   not executed unless the
   function is registered and
   executed.
- If a ) is executed outside of
   a loop, then the program will
   exit.
- If a function is associated to
   a value already associated to
   another function, then the new
   value will be associated to
   the new function.
- If a function is called with
   a value that is not associated
   with a function, the debugger
   will pause execution in debug
   mode, or the program will
   go to the next instruction in
   retail mode.
- If unrecognised text is
   executed in debug mode, then
   the debugger will pause the
   code, or the program will go
   to the next instruction in
   retail mode.
- The debugging command ! is
   ignored in retail mode.
- The c command varies between
   implementations and therefore
   should not be used directly.
   The c command should only be
   used for testing and for
   writing implementation-
   specific function wrappers
   inside of libraries.
- The ) and ] are identical, but
   should be used according to
   their context.
- A function may also be ended
   with ].

Commands
---------------------------------
-- Numeric Manipulation --
+  Increase value pointed to
    by the pointer.
-  Decrease value pointed to
    by the pointer.
>  Increment the pointer
    position.
<  Decrement the pointer
    position.
   
-- Program Control --
[  Opening nest. If value
   pointed to by the pointer is
   equal to 0 then jump to
   closing next.
]  Closing nest. Jump back to
   opening nest.

-- Stack --
^  Push value pointed to by the
    pointer on to the stack.
v  Pop value from the stack in
    to the position the pointer
    is pointing to.
   
-- Compatibility --
,  Read byte from keyboard and
    place in to the position the
    pointer is pointing to.
.  Write the ASCII character of
    the value the pointer is
    pointing to on the screen.

-- Functions --
(  Declare the beginning of a
    function.
)  Return from a function.
:  Register the function of the
   last ( executed and   associate
   it with the next number
   popped from the stack.
x  Execute the function
    associated with the next
    number popped from the stack.
z  Unassociate function
    associated with the next
    number popped from the stack.
   
-- Preprocessor --
"  Include the contents of the
    file named between two " over
    the position of the file name
    and the two "'s.
#  Ignore all text from and
    including the # to the end of
    the line.

-- Debugger --
!  Pause execution until the
    debugger allows the program
    to resume execution.
   
-- Compiler/Interpreter --
c  Compiler/interpreter specific
   command.

Change Log
---------------------------------
version 0.02:
- Removed { (do if 0) and } (end
  without loop)
version 0.01:
- Initial design documentation.

+a1?a50!a

21 ^ #

H Programming Language Compiler
http://messiahandrw.netfast.org

Usage: h [options] source

Options:
        -b <bits>       Specify the size of the memory cells in bits.
        -cs             Output to C# source code rather than a binary image.
        -d, --debug     Generate debugging information.
        -h, --help      Show this text.
        -l <language>   Language to compile.
        -m <size>       Number of cells in memory.
        -o <file>       Specify output file.
        -O              Disable optimisation.
        -u, --unsafe    Generate unsafe code. Unsafe code is faster but does
                        not provide memory protection.

Supported languages:
        bf              Brainf*ck (default)
        h0.02           H (0.02)(comming soon)

Supported memory cell sizes:
        8               8-bits
        16              16-bits
        32              32-bits (default)
        64              64-bits