For version 0.7.0.

The Shapes language reference

Without a reference documentation, the language would not be defined. On the other hand, the structure of a reference documentation may not suit new users of the language, but writing an instructional text will be postponed until the program is ready for public use.

Here you will find descriptions of the various parts of the documentation, along with links taking you there. You will also find a section describing the notation used throughout the documentation.

Index

The following list of links will take you to the various parts of the documentation:

The short Shapes tutorial:
A tutorial that will introduce you to the core concepts of the language, without getting into details. Plenty of examples.
User's guide:
A more extensive user's guide compared to the tutorial.
The Shapes language compiler:
Man page descripting the commad line interface of the compiler.
Interactive mode:
Using the Shapes compiler interactively.
Language documentation
Documentation of the core language.
- Program structure:
  Defines the output of a shapes program, and gives general recommendations on organizing source code.
- Syntax:
  The laguage syntax, including lexer directives.
- ..Shapes:
  Namespace of the Shapes language.
- Index of standard bindings:
  Index of all bindings under the ..Shapes namespace.
- Core types:
  Presentation of the value types defined by the core language.
- Core state types:
  Presentation of the variable types of states defined by the core language.
..Applications:
Namespace of the standard extensions that are not part of the Shapes language.
Algorithms and tolerance settings:
Advanced topics.
Editing Shapes files:
The shapes-mode for editing Shapes files in Emacs.
Installing Shapes:
Instructions on how to install Shapes.

Notation

This chapter just explains how to understand the rest of this reference. This includes showing how fonts and colors are used, introduction of a few elementary concepts, and even definitions of some very basic syntax elements.

Fonts and color

Concept	Example	Remark
Example code	[stroke pth head:someArrow]	No syntax highlighting of code elements.
Binding (a “variable”) or state	..Shapes..Graphics..stroke, ..Shapes..IO..•page
Formal parameter	some_var, •destination
Filename	hello.shape
Replacable dito	filename.shape
Type name	§Path2D
Regular expression	[~]?[0-9]+([.][0-9]*)?	Like flex version 2.5.4, but generalized to UTF-8.
Syntax rule name	call-expr
BNF structure	?

In the BNF notation, entities separated by whitespace matches source code possibly separated by whitespace. However, there is sometimes a need to indicate that whitespace is not allowed. This can be done by simply omitting the whitespace from the BNF notation, but if this is impossible for readability reasons, the special BNF syntax ; will be used, like this: basicf-float;unit. Conversely, mandatory whitespace is denoted _, which will be surrounded by ordinary whitespace for readability.

To denote that a piece of syntax allows expression that evaluate to a certain type, the :: notation is used, like this:

float

Float

It is also possible to indicate expressions that evaluate to a value of a given type, using the notation <SomeType>, like this:

float-pair

→

( <§Float>, <§Float> )

The following character classes will be used later:

LowerCaseLetter	→	[a-z_?]
UpperCaseLetter	→	[A-Z]
Greek	→	[αβγΓδΔεζηΘικλΛμνχΞπΠρσΣτϕωΩ]
Letter	→	LowerCaseLetter \| UpperCaseLetter \| Greek

The range of non-Latin characters that match Letter is expected to be extended in the future.

Nomenclature

Files

Before going into the language itself, let us introduce a few definitions relating to files.

When the compiler is invoked, this shall typically result in a piece of graphics. This is the output file.

Two types of input files can be identified. First, there are application sources, which are generally used to create a corresponding piece of graphics in an output file. (Sometimes, an application source may not be meant to produce an output file by itself, but as part of another application where it is included.) Second, there are extension sources, which shall not produce any graphics by themselves, but only provide functionality that can be used in applications.

There are other types of files as well, but the introduction of these is not needed for the language reference.