AnonymousFox

//opt/alt/python27/lib64/python2.7/site-packages/guppy/doc/gsl.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"
   "http://www.w3.org/TR/REC-html40/strict.dtd">

<html lang=en>
 <head>
  <meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
  <title></title></head>
 <body>
  <div>
  <h1>
 Guppy Specification Language
</h1>
  <ul>
   <li><a href='docexample.html'> Generated document example</a></li>
   <li><a href='#kinds'> Kinds</a></li>
   <li><a href='#example'> Example</a></li>
   <li><a href='#emacsmode'> Emacs editing mode</a></li></ul>
  <p> GSL is an evolving specification language, which is a part of the<a href='index.html'> Guppy-PE</a>
 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
<a href='http://adl.opengroup.org/'> http://adl.opengroup.org</a>
 Assertion Definition Language.
</p>
  <p>
 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.
</p>
  <p>
 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.
</p>
  <p>
 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.
</p>
  <p>
 I think what wants to be explained at this point is the following.
</p><a name='kinds'>
   <h3>
 Kinds
</h3></a>
  <p>
 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.
</p>
  <p>
 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.
</p>
  <p>
 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
</p>
  <pre>
.and: mykind
..attr:: attributename</pre>
  <p>
 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.
</p>
  <p>
 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.
</p><a name='example'>
   <h3>
 Example
</h3></a>
  <p> This<a href='gslexample.html'> GSL example</a> contains the source code and the generated test code for the <a href='docexample.html'> generated document</a>
example. The generated document intends to illustrate different kinds
of parameter specifications.

</p><a name='emacsmode'>
   <h3> Emacs mode</h3></a>
  <p>
 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 &quot;gsl-mode-0.1.el&quot; is in the distribution top
level directory and is not automatically installed.
</p>
  <p> The following is taken from its builtin help texts.</p>
  <pre>
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 &gt;		gsl-shift-region-right
C-c C-l		gsl-shift-region-left
C-c &lt;		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.</pre>
  <hr>Generated by <a href="http://guppy-pe.sourceforge.net/gsl.html">GSL-HTML 0.1.5</a> on Sat Jul  4 13:25:11 2009</div></body></html>