NEWS

Ginger Development News
=======================

Ginger Version 0.9.2
--------------------

Ubuntu SNAP Packaging
~~~~~~~~~~~~~~~~~~~~~
Canonical have a new 'universal' package format they call Snap. Ginger has been
rewritten to be Snap compliant. This is the fastest and simplest way to
install, update and remove Ginger, at least on Ubuntu. (There are other 
competing formats, such as Flatpak, that would also be possible.)

    % sudo snap install --devmode https://github.com/Spicery/ginger/releases/download/v0.9.2/ginger_0.9.2_amd64.snap

Command-Line Interface
~~~~~~~~~~~~~~~~~~~~~~
The command-line interface has been substantially rewritten to make GNU readline
part of the core functionality. This eliminates the dependency on rlwrap, although
that remains a useful tool for developers e.g. for gvmtest. This simplifies the
delivery and setup and the ginger executable is now a genuine executable and not
a shebang script - the latter unfortunately being more limited in terms of 
scripting.

The ginger executable now takes a 'command' argument that selects the actual
program:

    % ginger <COMMAND> <OPTIONS>

The program is selected by the very simple strategy of prefixing the command 
with "ginger-". Hence, as an example, the following two command-line are identical:

    % ginger admin 
    % ginger-admin

If omitted the command defaults to "cli", and invokes "ginger-cli". This is an abbreviation for "command line interface".

Refactorings
~~~~~~~~~~~~
* The old appginger executable, which has been without any real use for several
  years, has been properly retired. The few places it was used have been 
  properly replace by ginger-script.
* Reduction in the use of old-style C-macros in favour of C++ constants.
* System-functions have been re-organised to make it possible to manage them
  in a modular way. This functionality has not been used as yet.
* The system-functions table has been renamed to something more sensible.


Ginger Version 0.9.1
--------------------

More Analytical Functions
~~~~~~~~~~~~~~~~~~~~~~~~~
We have also implemented analytical functions for:

* power operator (**) 
* ceiling, floor, truncate
* abs
* asin, acos, atan, atan2
* cosh, sinh, tanh
* acosh, asinh, atanh
* gamma
* erf and erfc

Refactorings
~~~~~~~~~~~~

* All uses of Python2 have been replaced by Python3.

Ginger Version 0.9
------------------

Query Operators
~~~~~~~~~~~~~~~

The following query operators have been implemented:

* P & Q
* P // Q
* Q where C
* Q do S
* Q finally S
* Q while S then E

Naked Queries and Conditional Queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the main uses of queries in for-loops, 'naked' queries have also 
been implemented. This allows you to write declarations like these.

::
	i := 99;							### Declares the variable 99.
	j from 80 where j.isprime;			### j is the smallest prime number > 80.

Queries can also be used inside if-statements. These 'if'-queries execute their
then-part if the match succeeded or the else-part if the match failed.



Escapes
~~~~~~~
We have implemented the most important category of exceptions - namely escapes.
These are a form of 'tagged' return statement that need to be handled or they
escalate into more serious exceptions.

Math: Bigintegers, Rationals, Analytical Functions and TransDoubles Implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We have adopted James Anderson's transreal arithmetic as the basis for floating
point arithmetic in Ginger. This adds three transreal numbers +infinity, 
-infinity and nullity and ensures that arithmetic operators are defined
everywhere (including division by zero etc.)

We have implemented arbitrary precision integer arithmetic and
rational arithmetic. 

We have also implemented analytical functions for:

* divmod 
* log
* log2
* log10
* sin
* cos
* tan
* min, minAll 
* max, maxAll
* sqrt
* cbrt
* hypot
* unary +

Constants E and PI have been added. 

Bug Fixes
~~~~~~~~~

* file2gnx enhanced to handle single-expression files properly.

* All components now print the GPL correctly.

* ginger -q: the quiet startup flag is now honoured.

* <if/> now parsed correctly as legitimate expression.


Refactorings
~~~~~~~~~~~~

* We have eliminated all the compilation warnings on OS X. These were
  caused by the upgrade to XCode 4.6.3.

* The use of \*.inc files to define system functions has been entirely
  retired in favour of self-registering definitions.

* The C++ code has finally been moved into its own namespace. This was
  a low priority but implemented to make writing the API cleaner.

* We have consistently renamed "Machine" as "Engine" throughout the 
  code and documentation. The distinction between the virtual machine
  and its engine is unusual but important.

* Engines now self-register, so adding new engines is much more straightforward.

* CppLite2 now the basis of C++ unit testing.

Experimental / In-Progress Features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* New Dockerfile added for easy experimentation and to ensure a clean build process.

* New vagrant scripts have been included for experimenting with Ginger and
  rapidly getting test deployments working.

* An initial implementation of co-processes (aka first class VMs) have been added
  to the core but not exposed to the application programmer.


Ginger Version 0.8.2
--------------------

Curry'd Function Definitions Supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Both Common syntax and C-style syntax support "Currying", which means writing a definitions as a chain of function applications like this:

::

    # Common.
    define K( x )( y ) =>> x enddefine;

    //  C-style.
    function K( x )( y ) { return x; }

This will be very familiar to people used to functional programming, where it is the normal way of writing multiple arguments. It can be employed to write very compact and elegant code.


Binding/Assigning to Multiple Variables Implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Common and C-style syntax now support binding of multiple variables at the same time. For example:

::

    # Common.
    ( x, y ) := 'ab';

    # C-style
    val ( x, y ) = 'ab';

The same applies to assignment e.g.

::

    var p := _;
    var q := _;
    ( p, q ) ::= ( false, true );

Common and C-Style Syntax get literal percentages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A double may be written with a terminating "%". This has the meaning of multiplying the value by 0.01. 

::

    >>> 50%;
    There is one result.
    1.  0.5


Dummy Variable Syntax Now Supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Both Common and C-style syntax now support anonymous/dummy variables. Any variable whose name begins with an underscore (e.g. _dummy) acts like never-to-be-reused reference to a variable. 

The main purpose of a dummy variable is primarily to silently discard some unwanted values. The name of a dummy variable is insignificant at runtime but only allowed to assist writing self-commenting code and debugging.

The secondary purpose is that, when used for its value, all dummy variables evaluate to absent. 

Example:
::

        >>> ( alpha, _, beta, _, gamma ) := 'uvwxy';
        >>> alpha, beta, gamma;
        There are 3 results.
        1.  'u'
        2.  'w'
        3.  'y'


Simple stream i/o
~~~~~~~~~~~~~~~~~
A basic form of character-stream i/o has been added in the form of two new system functions. They both accept strings for FILENAMEs.

::

    input := newInputStream( FILENAME );
    output := newOutStream( FILENAME );

Input streams can be invoked like functions. Each call returns the next character from the input stream. When the stream is exhausted the special value termin is returned. Input streams are "pushable", meaning that it is possible to dynamically add characters onto the front of the stream.

    * input() returns the next character or termin to signal exhaustion.
    * input.thisCharInputStream() returns the current character/termin of the input stream.
    * input.nextCharInputStream() returns the current item and advances to the next item.
    * input.thisLineInputStream() returns the current line of the input stream, reading up to the next newline character.
    * input.nextLineInputStream() returns the current line of the input stream and advances to the next line.
    * input.pushInputStream( ITEM ) updates the input stream so that ITEM is pushed onto the front. The current item becomes the next item and ITEM becomes the current item. Note that the item may be any value whatsoever, including termin. Returning termin, even when pushed, will have the effect of immediately closing the input stream.
    * input.isClosedInputStream() returns true if the next item would be termin.
    * input.isOpenInputStream() returns true if the next item would be a character. The opposite of isClosedInputStream.
    * input.closeInputStream() immediately closes the input stream.

Output streams can be invoked like functions too. Each call accepts a character or string and sends it to the output. If the output stream is applied to termin then the stream is closed.

    * output( ITEM ) If ITEM is a character or a string it is sent immediately to the output stream. If ITEM is termin then the stream is closed.
    * output.sendOutputStream( ITEM ), same as above.
    * output.isOpenOutputStream() returns true if the output stream is still accepting items.
    * output.isClosedOutputStream() returns true if the output stream is no longer accepting items. The opposite of isOpenOutputStream.
    * output.closeOutputStream() immediately closes the output stream.

Note that both input streams and output streams are tracked by the garbage collector and are automatically closed when they are collected.


showMe, renaming and bug fixes of show function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are two basic ways of formatting Ginger values into a stream: via the print family or the showMe family. The showMe functions try to format the object as if it was a literal expression in the source programming syntax.

Ideally showMe will generate output that can be fed back into the (current) compiler to re-generate the value. As a consequence, each language should have its own definition of this.

The showMe function has an alias (showln). It is implemented in terms of the
underlying sysPrint function (previously show).

The showMe function has become the default way of printing results.

Configurable Result Printing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is now possible to configure the way results are printed via a new
user settings file::

    ~/.config/ginger/settings.gson

The strings exploit the new, basic formatted print functions.

The format of that file is a limited version of the planned GSON (Ginger Simple Object Notation) format, which is a strict superset of JSON (see http://json.org/).

A default settings.gson file can be generated using::

    ginger-admin --settings


Basic formatted printing via printf, printfln, stringf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The formatted print functions printf, printfln and stringf have been provided. They support the most elementary form of substitution at present: any occurence of '%p' or %s will be substituted by the matching positional parameter.
::

    FORMAT_STRING.stringf( ARG1, ... ARGn ) returns a string with the format parameters substituted.
    FORMAT_STRING.printf( ARG1, ... ARGn ) sends a string to the standard output after substitution.
    FORMAT_STRING.printfln( ARG1, ... ARGn ) sends a string to the standard output after substitution and then sends an additional newline.

Example:
::

    >>> "Call me %p.".stringf( "Steve" );
    There is one result.
    1.  "Call me Steve."

The difference between %p and %s is that %p uses the print format and %s uses the show format.


showMeRuntimeInfo() built-in function (cf phpInfo)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The system function "showMeRuntimeInfo" is designed to conveniently print contextual information about the Ginger running environment, working rather like PHP's phpInfo command. It's a blunt instrument that is occasionally just what is needed. Here's a truncated example of its output.



# >>> showMeRuntimeInfo();
# Application Environment
# -----------------------
# * Startup mode: Shell
# 
# Main
# ----
# * Ginger version: 0.8.2-dev
# * VM Implementation ID: 1
# * Garbage collection tracing: disabled
# * Code generation tracing: disabled
# * Reading standard input: 0
# * Level of print detail: 3
# * Showing welcome banner: disabled
# * Interactive package: ginger.interactive
# * Default syntax: cmn
# 
# .... (deleted) ....


The Erase and Dup family of built-in functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Two families of 'stack manipulation' functions have been added. The dup-family are useful for duplicating all or some of the arguments they are passed. The erase-family are useful for discarding all or some of the arguments they are passed.

::

    dupAll( V1, ..., Vn ) returns ( V1, ... Vn, V1, ... Vn )
    dupFirst( V1, ..., Vn ) returns ( V1, ... Vn, V1 )
    dupAllButFirst( V1, ..., Vn ) returns ( V1, ... Vn, V2, ... Vn )
    dupLast( V1, ..., Vn ) returns ( V1, ... Vn, Vn )
    dupAllButLast( V1, ..., Vn ) returns ( V1, ... Vn, V1, ... Vn-1 )
    dupLeading( V1, ..., Vn, k ) returns ( V1, ..., Vn, V1, ... Vk )
    dupAllButLeading( V1, ..., Vn, k ) returns ( V1, .. Vn, Vk+1 ... Vn )
    dupTrailing( V1, ..., Vn, k ) returns ( V1, ... Vn, Vn-k+1, ... Vn)
    dupAllButTrailing( V1, ... Vn, k ) returns ( V1, ... Vn, V1, ... Vn-k )

    eraseAll( V1, ..., Vn ) returns ()
    eraseFirst( V1, ..., Vn ) returns ( V2, ..., Vn )
    eraseLast( V1, ..., Vn ) returns ( V1, ..., Vn-1 )
    eraseAllButFirst( V1, ..., Vn ) returns ( V1 )
    eraseAllButLast( V1, ..., Vn ) returns ( Vn )
    eraseLeading( V1, ..., Vn, k ) returns ( Vk+1, ... Vn )
    eraseTrailing( V1, ..., Vn, k ) returns ( V1, ..., Vn-k )
    eraseAllButLeading( V1, ..., Vn, k ) returns ( V1, ... Vk )
    eraseAllButTrailing( V1, ..., Vn, k ) returns ( Vn-k+1, ... Vn )

gvmtest: New Virtual Machine Test Tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The gvmtest tool is only intended for testing the implementation of the 
C++ API to first class GVMs. It allows stack inspection, heap inspection,
manual code generation and compilation. 

The available commands are listed below:
::

    <registers/>
    <peek/>
    <stack.clear/>
    <stack.length/>
    <stack/>
    <heap.crawl/>
    <gc/>
    <compile> GNX </compile>
    <code> INSTRUCTION* </code>

It is intended that this work contributes usefully towards the C++ API & integration with a Python module.

All Major Features documented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All the features listed on the overview.rst page are now expanded in their own short articles. 

Under the hood
~~~~~~~~~~~~~~
There are two architectural changes to Ginger in this version. Firstly the C++ Ginger virtual machine API has been significantly advanced, although remains incomplete. This was triggered by the implementation of the gvmtest tool.

Secondly, a general interface for managing C++ objects has been added. This was done in order to implement input and output streams. This means that arbitrary C++ classes can be added and manipulated in Ginger and managed by the garbage collector.

In addition there have been numerous refactorings & bug fixes.
    
    *   Refactoring: Eliminating the use of C's printf and related functions 
        in favour of C++ stream i/o.
    *   Removed some badly out of date documentation (README.rst for example)
    *   Fixed linker issue that was cutting out self-registering built-ins.
    *   Improved error messages in some VM instructions.
    *   Calling local variables generated incorrect code, fixed.
    *   Renamed some VM instructions so they are more obvious what they do.
    *   Added new and more efficient VM call instructions.
    *   Fixed defect in --debug=showcode arising from the data-pool change.
    *   ginger-cli errors in exception catching fixed.
    *   Now possible to exclude unwanted interpreter engines at compile time.


Ginger Version 0.8.1
--------------------

Shell and Help Commands added to Ginger interpreter via new Tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ginger interpreter now specially intercepts certain inputs and treats 
them as commands. These

Unix shell command - any input starting with an exclamation mark is now
handed off to the shell. e.g.

	>>> !pwd
	/Users/steve/projects/Spicery/ginger/design

Help command - any input matching 'help' or 'help <topic-name>' will
now open a web browser on that topic. e.g.

	>>> help instruction_set


User Configurable File-Extension-to-Parser Mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The file2gnx tool is now responsible for managing the mapping from file
extensions through to the parsing tool. This is now fully configurable by
the user via the settings file 'parser-mapping.mnx'. The search for settings
file is `XDG base directory specification`__ compliant.

.. __: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

file2gnx searches the below path for 'parser-mapping.mnx' files. The
first matching entry wins.

    1.  $XDG_CONFIG_HOME/ginger
    2.  if $XDG_CONFIG_HOME does not exist fall back to $HOME/.config/ginger
    3.  For folder FOLDER in the colon-separated path $XDG_CONFIG_PATH 
        search FOLDER/ginger
    4.  If $XDG_CONFIG_PATH is not defined fall back to /etc/ginger


Pass Multiple, Comma-Separated Options with -O Option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A new -O option for passing multiple options as a single option has been
added to ginger-script, ginger-cgi and ginger. This was added
due to the widesperad limitation of only being able to support passing a
single option to #! scripts.

e.g.
    #!/usr/local/bin/ginger-script -O-ggnx,-m1


Ginger Instruction Set Documented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An initial documentation set for the Ginger VM instruction set has been written.
This is automatically generated from the comments contained within the 
instructions.

In later versions this will be integrated fully into the Ginger Documentation
project. For this release the documentation is stored by default at:

	/usr/local/share/ginger/html/instruction_set.html

Version 0.8
-----------

Arithmetic
~~~~~~~~~~
	* 	Adds new datatype Float (double precision) and support
		for floating point arithmetic.
	* 	Integer arithmetic now includes div, rem operators.
	*	Integer arithmetic smoothly overflows into floating point.

Common Syntax
~~~~~~~~~~~~~
	*	New reversible syntax for assignment ::= and =::
	*	Elements can now be closed using the universal closing tag </>.

Short-circuit Conditionals
~~~~~~~~~~~~~~~~~~~~~~~~~~
	*	<and> and <or> short-circuit operators added to the runtime.

Build Process
~~~~~~~~~~~~~
	*	Replaced the old Java code with new compact Python scripts,
		greatly simplifying the build process.
	*	New executable ginger-info replaces the --meta-info flag (now 
		removed) and makes the build process more straightforward. Easy way
		to dump the meta-info about Ginger.
	*	Dependency on Boost eliminated.

Other
~~~~~
	*	Many minor defect fixes.