directive
Patrick Mueller - [email protected]
Summary
directive
is a code parsing system based on the
recognition that most programs tend to be structured as a set
of blocks of the form:
- comment
- definition
- body
For example:
/**
* this is a comment
*/
myFunction(arg1, arg2)
{
for (something) { somethingElse() }
}
In that example, you have a comment, followed by the definition
of the myFunction
procedure, followed by the body of the
procedure.
With directive
, you use a standard format to write your
comments, definitions, and bodies. Definitions are actually
called directives.
Parsing Rules
The parsing rules are line based, so things like multi-line comments and multi-line expressions are not directly handled by the system.
The basic rules for the different parts of a directive are:
-
comment
A comment block begins with a line that contains a / or # character in column one. It continues until a directive.
-
directive
A directive is a single line which begins with an alphabetic character, $ or @.
-
body
A body block begins after a directive, and continues to a comment or directive. Every line of a body (except empty lines) must begin with at least one white-space character.
API
To use directive
, you must first create a DirectiveReader
with the
constructor
DirectiveReader(source, fileName, lineNumber)
source
is the source file containing the directives, fileName
is the name
of the file, and lineNumber
is the line the source starts at (for embedded
directives in other files).
With the resulting DirectiveReader
object, you can invoke the method
directiveReader.process(handler)
handler
is an object containing functions that are called back at various
times during the processing. Methods which must be implemented in this
object include:
-
processDirective(event)
-
fileBegin(event)
-
fileEnd(event)
See the examples for the actual data passed in the events.
In addition, you can provide functions of the form:
handleDirective_[directiveName]
where [directiveName]
is a specific directive that you want to handle.
Rather than invoking the processDirective
method for this directive, the
specified handleDirective_[directiveName]
method will be invoked instead.
Examples
See the test cases for examples. In particular, the files in the test/test-files directory contain sample inputs with the list of events that are generated for that input, so you can see exactly what gets generated.