Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for the CHICKEN 4 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

mole

Outdated egg!
mole

Documentation

The mole homepage is located at http://www196.pair.com/lisovsky/ad/mole.

Mole reads the Scheme source code and parse it to the structural elements using ";====" as chapter separator, ";----" as section start, ";^^^^" as section end (if necessary) and "; " or "(" at the beginning of the "chunk". Chunk may be a function, macro, binding, etc. More documentation on the source code formatted style may be found in mole.txt file.

Parsed data is represented as the SXML tree. A number of useful reports may be generated querying this data. For example, Mole may be used as a tool for automated documentation generation. For such a purpose it works as a filter that reads documented Scheme code from the standard input and produces some kind of hypertext documentation in the HTML format to the standard output.

Use the command "mole -h" for usage instructions.

Test cases

Since version 3.4 Mole has an ability to attach a test suite to every function in documentation which has a test case in a test fixture file specified with --tf=<file> option. If the file name is omitted (an option --tf ), then file xtest-fixture.scm in subdirectory test is used.

Test cases are XTester-compatible they has to be formatted as follows:

 ;@ name (optional)
 ; description (optional)
 (xtest-assert
 ...
 )

Please note the closing ")" in first position (It's used to detect end of test case). If the name of the function tested may be not detected automatically, it has to be specified explicitly using ;@ <some-name> comment before the test case.

Processing of test fixture file may be controlled using ;$ comment as an explicit end of file. The rest of test fixture will be not processed by Mole.

For every function with test suite a clickable [+] is included in table of content.

Mole Source Code Formating Style

The syntax accepted by Mole is described by the following grammar:

 <module>  ::= ( <chapter> | <section> | <chunk> | <comment> )*
  <chapter> ::= ( <section> | <chunk> | <comment>)*
  <section> ::= ( <chunk> | <comment> )*
  <chunk> :== "(" <chunk-type> <name> <description>? <code> ")" 
  <chunk-type> :== function | macro | app
  <name> ::= "(" name STRING ")"
  <description> ::= "(" description STRING ")"
  <code> ::= "(" code STRING ")"
  <comment> ::= "(" comment STRING ")"

Chapter

 
 ;=============================================================
 ; <Chapter name>
 ; Description
 ;  of the
 ; module

Any number of sections or chunks may follow

End of chapter is ";=" in the first position

Section

 ;-----------------------------
 ; <Section name>
 ; Description
 ;  of the
 ; section

End of section is ";=" or ";-" in the first position

NOTE: in chapter and section separators just two first characters are important: ";=" or ";-" respectively.

Unit

 ; Description 
 ;  of the 
 ; chunk
 (chunk-code 
   ...
  ...)

End of chunk is one of: ";=" ";-" ";*" or "; " in the first position.

Chunk descriptions are of optional. Description-less chunks have to be nested in section or chapter. If they are nested in module they are ignored by parser.

Head comment

 <Comment-block> ::= (^;;\S+$)+  ; Semicolons in the first and second pos

Changelog

License

Public Domain