| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191 |
- .document: gsl
- ..output: html
- ..h1: Guppy Specification Language
- ..ul
- ...li
- ....a: Generated document example
- .....href=docexample.html
- ...li
- ....a: Kinds
- .....href=#kinds
- ...li
- ....a: Example
- .....href=#example
- ...li
- ....a: Emacs editing mode
- .....href=#emacsmode
- ..p: GSL is an evolving specification language, which is a part of the
- ...a: Guppy-PE
- ....href= index.html
- ...t: 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: http://adl.opengroup.org
- ....href=http://adl.opengroup.org/
- ...t: Assertion Definition Language.
- ..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: 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: 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: I think what wants to be explained at this point is the following.
- ..a
- ...name=kinds
- ...h3: Kinds
- ..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: 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: 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
- ..pre
- \.and: mykind
- \..attr:: attributename
- ..c: end 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: 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.
- ..a
- ...name=example
- ...h3: Example
- ..p: This
- ...a: GSL example
- ....href=gslexample.html
- ...t: contains the source code and the generated test code for the
- ....a: generated document
- .....href=docexample.html
- ...t:example. The generated document intends to illustrate different kinds
- of parameter specifications.
- ..a
- ...h3: Emacs mode
- ...name=emacsmode
- ..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 "gsl-mode-0.1.el" is in the distribution top
- level directory and is not automatically installed.
- ..p: The following is taken from its builtin help texts.
- ..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 > 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.
- ..c: end pre
|