https://github.com/pmuellr/directive

code-oriented DSL framework for JavaScript
https://github.com/pmuellr/directive

Last synced: about 2 months ago
JSON representation

code-oriented DSL framework for JavaScript

• Host: GitHub
• URL: https://github.com/pmuellr/directive
• Owner: pmuellr
• Created: 2009-12-18T14:03:09.000Z (about 15 years ago)
• Default Branch: master
• Last Pushed: 2012-08-23T15:23:38.000Z (over 12 years ago)
• Last Synced: 2024-10-31T18:11:48.257Z (3 months ago)
• Language: JavaScript
• Homepage:
• Size: 131 KB
• Stars: 2
• Watchers: 2
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
directive

=================================

Patrick Mueller - [[email protected]](mailto:[email protected])

[![build status](https://secure.travis-ci.org/pmuellr/directive.png)](http://travis-ci.org/pmuellr/directive)

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.