embed.1

.\" Manpage for embed
.\" Contact howe.r.j.89@gmail.com to correct errors or typos.
.TH embed 1 "17 Jun 2018" "0.1.0" "embed man page"
.SH NAME
embed \- embed virtual machine
.SH SYNOPSIS
embed [-hqt] -i in.blk -o out.blk file.fth
.SH DESCRIPTION
A simple and compact Forth Virtual machine, derived from the H2 CPU
(from <https://github.com/howerj/forth-cpu>, which in turn derives from the J1
CPU). The virtual machine includes a built in eForth image which can be used
in lieu of loading one off of disk.

.SH OPTIONS
No options are mandatory.

.TP
.B -i in.blk
Select initial input block, this block will be loaded off of disk and used as
memory for the Virtual machine, maximum block size is 65535 bytes. If no input
block is specified then an internal initial block will be used instead, which
contains a fully working eForth interpreter.

.TP
.B -o out.blk
Select the output block, the virtual machine is capable of saving sections of
its memory to disk and this option allows the user to specify which file the
memory is saved to. If no file is specified then any attempts by the virtual
machine to save memory to disk will fail.

.TP
.B -h
Print a help message and exit indicating failure.

.TP 
.B -q

Turn quite mode on. It is up to the virtual machine image to respect this
option if it is given, this option justs set the bit to indicate a quite mode.

.TP 
.B -t

Turn tracing on, this sets an option turn on tracing in the virtual machine.
This will do anything if the library has been compiled with the NDEBUG macro
defined.

.TP
.B file.fth
This option supplies a file to read from, by default the virtual machine
will read from stdin(3) if a file is not given. Multiple files can be
specified, but if a file is specified input will not be read from stdin(3).

.SH EXAMPLES

.TP
.B ./embed

This will make 'embed' use the built in virtual machine image, saving will
fail, and stdin(3) will be used as input.

.TP
.B ./embed -o out.blk

Set output block to 'out.blk', any changes using the save instruction will
be written to this file.

.TP
.B ./embed  -i in.blk

Set the initial VM image to 'in.blk'

.TP
.B ./embed -i in.blk -o out.blk file.fth

.SH EFORTH

This manual page is not the right medium to describe eForth, the language
implemented in the default image loaded. eForth is a variant of Forth designed
to be portable and small. Forth is a stack based imperative programming with
minimal safety checks and footprint, it uses Reverse Polish Notation to 
organize input and output arguments, allows for Reflection (the language can
inquire about its run time), has incremental compilation, and is extensible.

The default image includes the Forth interpreter, a simple editor, a 
primitive disassembler, and CRC checks.

If you run the default image you should be greeted with a prompt that looks
something like this:

.TP 
.B eFORTH v1984
.B 5290 11094


You can starting typing things in, the eForth interpreter gets its input a line
at a time and will print out 'ok' after a line has been successfully
interpreted.

Some examples:

.TP
.B 2 2 + . 

This performs the simple sum '2+2' and it prints the result, you should see
the line:

.TP
 4 ok

Printed out.

.TP
.B : hello ." Hello, World!" cr ;

.B hello

.TP
.B words

Displays all of the functions (Forth calls functions words) in the Forth
dictionary (the dictionary is a list of all defined words) in the currently
loaded vocabularies. You can use this word to find out 

.TP
.B see words

The word 'see' is the Forth disassembler, it takes the next word, 'words' and
shows you how assembly for it. You can use 'see' to work out how words work
without the source code.

.TP
.B save

Save the current image to disk, this will fail if you do not specify and
output file when you ran the interpreter with the '-o' option.

.SH COMPILATION

Compilation requires a C compiler that supports the C99 standard at minimum,
if you have make installed you can type 'make' to build the interpreter, if
you do not:

.B cc -std=c99 main.c embed.c image.c util.c -o embed

.SH LIBRARY API AND PORTING

The library API itself is described in detail in the header for the library.
The goal of the library, and the virtual machine, is too be as flexible as
possible. It achieves flexibility by allowing the library user to pass in
callbacks to change the behavior of the Input/Output channels (of which there
are three available to the virtual machine), and also by allowing the user to
pass in a callback that can be used to do arbitrary things by pushing and
pulling data to and from the virtual machines stack.

It should be possible to port to most platforms quite easily, including various
microcontrollers (it might even be possible to do so just by providing the
right callbacks depending on your Board Support Package).

The header file describes what each function does, and the repository contains
example programs. The library should be simple to use, and if it is not please
contact the author to complain about it. Do not be afraid to hack around with
the virtual machine to get it to do what you want either, the program is
relatively short and should be easy to understand even if the code is dense.

.SH EXIT STATUS

This command returns zero on success and non zero on failure.

.SH SEE ALSO

For more information, see
.B https://github.com/howerj/embed
which contains the original program source.

.SH BUGS

For any bugs, contact the author. The eForth image is not standards compliant
with ANS Forth or any other Forth standard, however it does look to not
deviate if possible so if you find any simple changes please email me.

.SH AUTHOR
Richard James Howe (howe.r.j.89@gmail.com)

.SH COPYRIGHT
The embed program is licensed under the MIT license, Copyright (c) 2018, 
Richard James Howe. The same applies to the images and source code to generate 
those images.