Ginger Documentation Release 1.0 sfkl / gjh Nov 03, 2017 Contents 1 Contents 3 2 Help Topics 27 3 Common Syntax 53 4 Design Rationales 55 5 The Ginger Toolchain 83 6 Low-Level Implementation 99 7 Release Notes 101 8 Indices and tables 115 Bibliography 117 i ii Ginger Documentation, Release 1.0 This documentation is still very much work in progress The aim of the Ginger Project is to create a modern programming language and its ecosystem of libraries, documen- tation and supporting tools. The Ginger language draws heavily on the multi-language Poplog environment. Contents 1 Ginger Documentation, Release 1.0 2 Contents CHAPTER 1 Contents 1.1 Overview of Ginger Author Stephen Leach Email [email protected] 1.1.1 Background Ginger is our next evolution of the Spice project. Ginger itself is a intended to be a rigorous but friendly programming language and supporting toolset. It includes a syntax-neutral programming language, a virtual machine implemented in C++ that is designed to support the family of Spice language efficiently, and a collection of supporting tools. Spice has many features that are challenging to support efficiently in existing virtual machines: pervasive multiple values, multiple-dispatch, multiple-inheritance, auto-loading and auto-conversion, dynamic virtual machines, implicit forcing and last but not least fully dynamic typing. The virtual machine is a re-engineering of a prototype interpreter that I wrote on holiday while I was experimenting with GCC’s support for FORTH-like threaded interpreters. But the toolset is designed so that writing alternative VM implementations is quite straightforward - and we hope to exploit that to enable embedding Ginger into lots of other systems. 1.1.2 Features of the Ginger Language and Tools Here’s a list of the features we have already implemented for the GVM project. • Pervasive multiple values, including loop expressions. • Dynamic type checking • Full arithmetic, supporting integers, big integers, rationals and doubles. • Immutable objects - strings, lists vectors and maps. • XML like elements built-in (immutable only). 3 Ginger Documentation, Release 1.0 • User-defined records and vectors. • First class functions and lambda expressions with full lexical binding. • Basic CGI integration. • Garbage Collection with weak references, weak maps and file closing. • Syntax Neutral with two available front-end syntaxes so far. • Multiple Implementations of Single Instruction Set 1.1.3 Further, Planned Features The Ginger project has an extensive roadmap that reflects our ambitions for it as a language. Here are some of the key features from the project roadmap that are not yet available. By and large most of these features are designed but require implementation. n.b. If there’s a particular feature of interest to you, let us know. • Regular expressions and supporting syntax. • Pattern Matching used pervasively to implement binding and smart loops. • Enhancements to the Garbage Collector • Dynamically Create New Virtual Machines as first class objects. • Implicit Force • Complex numbers. • Immutable, updateable, and dynamic strings, lists, vectors, elements and maps. • Optional static typing, consistent with the Dollin principle. • Full object-oriented programming model with multiple inheritance and multiple dispatch. • Coroutines as first class objects. • Keyword parameters with default values. • Partial application. • Auto-loading and auto-importing. • Updaters and deconstructors. • Advanced exception handling model with Alternative returns, Rollbacks, Failovers and Panics. • An additional Lisp-based front-end syntax. • Two further important built-in types: bags and priority queues • Full CGI Integration. • Full Unicode integration. 1.1.4 Development Status • Linux and Mac OS X, 64 & 32-bit versions of all 4 engines. • Common-syntax and C-style syntax front ends. • Basic function definitions & 1st class functions. • Conditions and short-circuit operators. 4 Chapter 1. Contents Ginger Documentation, Release 1.0 • Basic for loops. • Dynamic integer and double arithmetic & relational operators. • Primitive values (booleans, absent, Unicode characters). • Strings (8-bit only). • Lists, vectors, elements and maps (weak/hard, identity/equality). • Basic stream-based i/o working and integrated with garbage collector. • Garbage collector, includes weak refs and weak maps. • Basic packages working. • Full lexical binding, higher order functions. 1.2 About Ginger 1.2.1 What is Ginger Ginger is a modern programming system that is built on top of a general purpose virtual machine. It comes with a modern programming language and library so that you can use to write your own applications. But the whole system is designed to be open, so you can extend or replace almost every part of the system. Why did we create Ginger when there are so many programming systems already? Because we love programming and love making neat, effective programs. But other systems have all kind of conveniences that end up being confusing; strange corner cases that are supposed to be convenient but just make things ugly; or reasonable looking compromises that cause lots of problems later on. So we designed Ginger to be a language that gets out of your way and lets you enjoy the experience of writing a program. It took us a long time, more than ten years, to figure out what we thought that meant. Gradually we distilled our design goals into some key rules. One rule, for example, is “the programmer is in charge (not the language designer)”. That affects the design of visibility declarations such as private/public; it requires that a programmer can get access to private variables for, say, debugging or writing unit tests. You may wonder how this can make sense - in which case turn to the chapter on packages. Another key rule is “if one, why not many?”. This rule means that anywhere in the language where there is a restriction to one item, consider making it many items. So in Ginger expressions don’t return just one value, they may return any number from 0, 1, ... and so on. And methods don’t just dispatch on one special ‘this’ argument, they may dispatch on 0, 1, 2 ... of their arguments. In fact a function is just a special kind of method that dispatches on 0 arguments. To understand how we interpreted our design rules you need to know a little about Ginger. 1.2.2 Hello World in Common In this introduction to Ginger, we will write our examples in what we call ‘Common’. Ginger supports more than one programming language syntax. But we designed Common to be a neat modern language that is easy to remember and accident-resistant. But you don’t have to use it. We also designed a Javascript-inspired syntax too, if you prefer. And in future versions of Ginger we will add more - it’s quite easy to add new ones. (Why did we make Ginger so flexible? Because one of the things we wanted to get away from was the idea that there was a single right answer.) So what does Common look like? Here’s a simple ‘hello, world!’ example. It shows quite a few useful features. I have added line numbers for easy reference. 1.2. About Ginger 5 Ginger Documentation, Release 1.0 Line1 # Prints a cheery message to the console. Line2 define hello()=>> Line3 println("Hello, world!") Line4 enddefine On Line 1 we write an end-of-line comment which is introduced with a hash symbol followed by a space. On Line 2 we introduce a function called ‘hello’. Function definitions start with the keyword ‘define’ and are closed with the matching keyword ‘enddefine’. This pairing of opening and closing keywords is used in many places in Common. The function head is separated from the function body by an ‘=>>’. There are several places where this double-headed arrow is used in Common and it always signals that a function is being defined. On Line 3 we define the function body as calling the ‘println’ function on a literal string. The name ‘println’ is a contraction of ‘PRINT then add a LiNe’ and the function is part of the standard library (ginger.std) . Programmers do not usually import the standard library because it is available by default. String literals use double-quotes, just like C/C++/C#, Java, Javascript and so on. Single quotes are reserved for symbol literals, which you will meet later on, but for now you can think of as a different kind of string. On Line 4 we close the function with the ‘enddefine’ keyword. If you are working interactively you can abbreviate any keyword that starts with the prefix ‘end’ to just ‘end’. This includes ‘enddefine’, ‘endfn’, ‘endif’, ‘endfor’. 1.3 appginger, The Ginger XML Interpreter Usage : appginger [options] [files] OPTION SUMMARY -B, -batch run in batch mode -C, -cgi run as CGI script -I, -interactive run interactively -T, -terminate stop on mishap -d, -debug add debug option (see -help=debug) -h, -help print out this help info (see -help=help) -f, -projectfolder add a project folder to the search path -l, -license print out license information and exit -m<n> run using machine #n -v, -version print out version information and exit 1.4 Get Started with Ginger 1.4.1 Download, compile and install Ginger $ git clone [email protected]:Spicery/ginger.git $ cd ginger $ APPGINGER=`pwd` $ ./configure $ sudo make&& make install 6 Chapter 1. Contents Ginger Documentation, Release 1.0 1.4.2 Install RudeCGI library $ cd /tmp $ wget http://rudeserver.com/cgiparser/download/rudecgi-5.0.0.tar.gz $ tar zxf rudecgi-5.0.0.tar.gz $ pushd rudecgi-5.0.0; ./configure; sudo make&& make install; popd 1.4.3 Install optional extras $ sudo apt-get install