GSL is an evolving specification language, which is a part of the Guppy-PE programming environment. I started experimenting with this language because I felt the need to have a way to specify documentation and tests from the same source. GSL can describe aspects of a system, especially its API, in a way that can be automatically converted to tests as well as to documents. The documents generated have a formal structure for describing the formal aspects of the specification, complemented with descriptive text from the same source documents. A language that is similar in intent to GSL, is the http://adl.opengroup.org Assertion Definition Language.
Generating tests automatically is a quite hard problem generally. The programmer only may know best what should be tested. At the very least, however, GSL can check that some aspects of the documentation are in fact correct. If an object is specified to have an attribute, it can be tested. If the kind (type) of the attribute is also specified, it can also be tested, as far as the kind of the attribute is specifed, and as far as it can be done within physical limits when there are circularities and combinatorial explosions.
It is possible to use GSL to write documents that have no formal connection to program semantics. It supplies a syntax that can proivde a 1-1 correspondence with HTML (and XML), but is often easier to read and write (IMHO). The syntax is a simple syntax based on dotted indentation. There is a well defined 1-1 correspondence with a tree structure.
This release of Guppy is not primarily concerned with GSL which is still in a very prototypical state, it awaits probably the first major refactoring. However, since the documentation of Heapy is generated by GSL, something deserves to be said about the kind of documents it has generated.
I think what wants to be explained at this point is the following.
I am generally using the word 'kind' to stand for something that is not a type or a class but is specified in some other way. This is because I don't want to say type and class when I am not exactly referring to a type or class, since it would be confusing if some people think it means a Python type or class, someone else think it means something else. The word 'kind' means just a kind, it is not defined what a kind is, except for what you might think it means in ordinary language.
Maybe a 'kind' is quite the same as what is otherwise often called an 'interface'. Well, I am using the word 'kind' in that case anyway since it is shorter and easier to read and write.
In GSL, a 'kind' starts as just a name for something without any properties at all. You can however add properties to a kind by specifying something about it. You may for example say
.and: mykind ..attr:: attributename
This means you have added an aspect to mykind. It now means that it is a (Python) object having an attribute named attributename. A test can be generated from this specification. It will check an object claimed to be of kind mykind, to make sure it really has an attribute named attributename.
You can also add properties saying that a kind of objects or attributes is callable, what kind of parameters it can take, and what kind of return value it will deliver. The parameters can be specified to be optional, named, or repeated in varous ways.
This GSL example contains the source code and the generated test code for the generated document example. The generated document intends to illustrate different kinds of parameter specifications.
There is an Emacs mode that supports editing of GSL files. It is based on the Python mode. It indents with dots instead of spaces. The mode file "gsl-mode-0.1.el" is in the distribution top level directory and is not automatically installed.
The following is taken from its builtin help texts.
GSL mode:
Major mode for editing GSL files.
To submit a problem report, enter `C-c C-b' from a
`gsl-mode' buffer. Do `C-c ?' for detailed documentation.
This mode knows about GSL dotted indentation.
Paragraphs are separated by blank lines only.
COMMANDS
key binding
--- -------
C-c Prefix Command
C-c C-v gsl-mode-version
C-c C-b gsl-submit-bug-report
C-c ? gsl-describe-mode
C-c C-r gsl-shift-region-right
C-c > gsl-shift-region-right
C-c C-l gsl-shift-region-left
C-c < gsl-shift-region-left
KINDS OF LINES
Each physical line in the file is either a `markup line'
(the line starts with a dot character '.') or a `text line'
(the line starts with some other character). Text lines starting
with a dot may be entered by quoting by a backslash ('\')).
INDENTATION
Unlike most programming languages, GSL uses indentation, and only
indentation, to specify block structure. Unlike other programming
languages the indentation is not based on blanks but on another
special character; currently this is fixed to be the '.' character.
The indentation that can be supplied automatically by GSL-mode is
just a guess: only you know the block structure you intend, so only
you can supply correct indentation.
Primarily for entering new code:
TAB indent line appropriately
LFD insert newline, then indent
The TAB and LFD keys will indent the current line to reproduce
the same indentation as the closest preceding markup line.
Primarily for reindenting existing code:
C-c C-l shift region left
C-c C-r shift region right
The indentation of the markup lines in the region is changed by +/- 1
or the argument given. Text lines in the region will not be changed.
OTHER COMMANDS
Use C-c C-v to see the current version of gsl-mode.
Use C-c C-b to submit a bug report or enhancement proposal.
This text is displayed via the C-c ? command.
HOOKS
Entering GSL mode calls with no arguments the value of the variable
`gsl-mode-hook', if that value exists and is not nil; see the `Hooks'
section of the Elisp manual for details.