gsl.gsl 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191
  1. .document: gsl
  2. ..output: html
  3. ..h1: Guppy Specification Language
  4. ..ul
  5. ...li
  6. ....a: Generated document example
  7. .....href=docexample.html
  8. ...li
  9. ....a: Kinds
  10. .....href=#kinds
  11. ...li
  12. ....a: Example
  13. .....href=#example
  14. ...li
  15. ....a: Emacs editing mode
  16. .....href=#emacsmode
  17. ..p: GSL is an evolving specification language, which is a part of the
  18. ...a: Guppy-PE
  19. ....href= index.html
  20. ...t: programming environment. I started experimenting with this
  21. language because I felt the need to have a way to specify
  22. documentation and tests from the same source. GSL can describe aspects
  23. of a system, especially its API, in a way that can be automatically
  24. converted to tests as well as to documents. The documents generated
  25. have a formal structure for describing the formal aspects of the
  26. specification, complemented with descriptive text from the same source
  27. documents. A language that is similar in intent to GSL, is the
  28. ...a: http://adl.opengroup.org
  29. ....href=http://adl.opengroup.org/
  30. ...t: Assertion Definition Language.
  31. ..p: Generating tests automatically is a quite hard problem
  32. generally. The programmer only may know best what should be tested.
  33. At the very least, however, GSL can check that some aspects of the
  34. documentation are in fact correct. If an object is specified to have
  35. an attribute, it can be tested. If the kind (type) of the attribute is
  36. also specified, it can also be tested, as far as the kind of the
  37. attribute is specifed, and as far as it can be done within physical
  38. limits when there are circularities and combinatorial explosions.
  39. ..p: It is possible to use GSL to write documents that have no formal
  40. connection to program semantics. It supplies a syntax that can proivde
  41. a 1-1 correspondence with HTML (and XML), but is often easier to read
  42. and write (IMHO). The syntax is a simple syntax based on dotted
  43. indentation. There is a well defined 1-1 correspondence with a tree
  44. structure.
  45. ..p: This release of Guppy is not primarily concerned with GSL which
  46. is still in a very prototypical state, it awaits probably the first
  47. major refactoring. However, since the documentation of Heapy is
  48. generated by GSL, something deserves to be said about the kind of
  49. documents it has generated.
  50. ..p: I think what wants to be explained at this point is the following.
  51. ..a
  52. ...name=kinds
  53. ...h3: Kinds
  54. ..p: I am generally using the word 'kind' to stand for something that is
  55. not a type or a class but is specified in some other way. This is
  56. because I don't want to say type and class when I am not exactly
  57. referring to a type or class, since it would be confusing if some
  58. people think it means a Python type or class, someone else think it
  59. means something else. The word 'kind' means just a kind, it is not
  60. defined what a kind is, except for what you might think it means in
  61. ordinary language.
  62. ..p: Maybe a 'kind' is quite the same as what is otherwise often
  63. called an 'interface'. Well, I am using the word 'kind' in that case
  64. anyway since it is shorter and easier to read and write.
  65. ..p: In GSL, a 'kind' starts as just a name for something without
  66. any properties at all. You can however add properties to a kind
  67. by specifying something about it. You may for example say
  68. ..pre
  69. \.and: mykind
  70. \..attr:: attributename
  71. ..c: end pre
  72. ..p: This means you have added an aspect to mykind. It now means that it is
  73. a (Python) object having an attribute named attributename. A test can
  74. be generated from this specification. It will check an object claimed
  75. to be of kind mykind, to make sure it really has an attribute named
  76. attributename.
  77. ..p: You can also add properties saying that a kind of objects or
  78. attributes is callable, what kind of parameters it can take, and what
  79. kind of return value it will deliver. The parameters can be specified
  80. to be optional, named, or repeated in varous ways.
  81. ..a
  82. ...name=example
  83. ...h3: Example
  84. ..p: This
  85. ...a: GSL example
  86. ....href=gslexample.html
  87. ...t: contains the source code and the generated test code for the
  88. ....a: generated document
  89. .....href=docexample.html
  90. ...t:example. The generated document intends to illustrate different kinds
  91. of parameter specifications.
  92. ..a
  93. ...h3: Emacs mode
  94. ...name=emacsmode
  95. ..p: There is an Emacs mode that supports editing of GSL files. It is
  96. based on the Python mode. It indents with dots instead of
  97. spaces. The mode file "gsl-mode-0.1.el" is in the distribution top
  98. level directory and is not automatically installed.
  99. ..p: The following is taken from its builtin help texts.
  100. ..pre
  101. GSL mode:
  102. Major mode for editing GSL files.
  103. To submit a problem report, enter `C-c C-b' from a
  104. `gsl-mode' buffer. Do `C-c ?' for detailed documentation.
  105. This mode knows about GSL dotted indentation.
  106. Paragraphs are separated by blank lines only.
  107. COMMANDS
  108. key binding
  109. --- -------
  110. C-c Prefix Command
  111. C-c C-v gsl-mode-version
  112. C-c C-b gsl-submit-bug-report
  113. C-c ? gsl-describe-mode
  114. C-c C-r gsl-shift-region-right
  115. C-c > gsl-shift-region-right
  116. C-c C-l gsl-shift-region-left
  117. C-c < gsl-shift-region-left
  118. KINDS OF LINES
  119. Each physical line in the file is either a `markup line'
  120. (the line starts with a dot character '.') or a `text line'
  121. (the line starts with some other character). Text lines starting
  122. with a dot may be entered by quoting by a backslash ('\')).
  123. INDENTATION
  124. Unlike most programming languages, GSL uses indentation, and only
  125. indentation, to specify block structure. Unlike other programming
  126. languages the indentation is not based on blanks but on another
  127. special character; currently this is fixed to be the '.' character.
  128. The indentation that can be supplied automatically by GSL-mode is
  129. just a guess: only you know the block structure you intend, so only
  130. you can supply correct indentation.
  131. Primarily for entering new code:
  132. TAB indent line appropriately
  133. LFD insert newline, then indent
  134. The TAB and LFD keys will indent the current line to reproduce
  135. the same indentation as the closest preceding markup line.
  136. Primarily for reindenting existing code:
  137. C-c C-l shift region left
  138. C-c C-r shift region right
  139. The indentation of the markup lines in the region is changed by +/- 1
  140. or the argument given. Text lines in the region will not be changed.
  141. OTHER COMMANDS
  142. Use C-c C-v to see the current version of gsl-mode.
  143. Use C-c C-b to submit a bug report or enhancement proposal.
  144. This text is displayed via the C-c ? command.
  145. HOOKS
  146. Entering GSL mode calls with no arguments the value of the variable
  147. `gsl-mode-hook', if that value exists and is not nil; see the `Hooks'
  148. section of the Elisp manual for details.
  149. ..c: end pre