Nodular Pudding Multiverse
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    olipublic

    oli.js Build Status Dependency Status NPM version

    Oli language parser and compiler for node and the browser

    Language version0.1
    Stagebeta

    About

    Multi-purpose high level Oli language parser and compiler for node.js and the browser, which implements the latest language specification

    Oli.js provides a general parsing infraestructure to be integrated and consumed from other applications that uses the Oli syntax for specific purposes, like parsing own DSL

    Aditionally it provides a rich featured high and intermediate level programmatic API and a rich command-line interface

    Note: it's still a beta implementation! A full compiler re-designing process is pending

    Features

    • Powerful parser based on parsing grammar expressions
    • Smart compiler with smart type inference
    • Detailed parsing errors
    • Runs on node.js and the browser
    • High and intermediate level featured API
    • Featured command-line interface
    • Heavily tested with high coverage
    • No third party dependencies
    • Official language specification implementation
    • Good performance (run grunt bench)

    Installation

    Node.js

    $ npm install oli
    

    For CLI usage only, it's recommented you install it as global package

    $ npm install -g oli
    

    Browser

    $ bower install oli
    

    Or load the script remotely (just for testing or development)

    <script src="//rawgithub.com/oli-lang/oli-js/master/oli.js"></script>

    Then you can create script tags with text/oli MIME type

    <script type="text/oli" src="path/to/file.oli"></script>

    It will automatically fetch and parse the oli sources and make it available from oli.scripts. To disable the automatic parsing, just add data-ignore attribute in the script tag

    Environments

    • Node.js >= 0.8.0
    • Chrome
    • Firefox
    • Safari >= 5
    • Opera >= 11.6
    • IE >= 9

    Milestones

    • Parser
      • Top-down parsing (based on PEG strategy)
      • AST
      • Configurable parsing options
      • Errors
      • Unicode expressions
      • [*] Indentation based parsing
    • Compiler
      • AST walker
      • Memory register
      • Intermediate code transpiler
      • Code generator
      • [*] Errors
      • [_] Interpreter
      • [_] Optimiser
      • [_] Event-driven
    • Interfaces
      • API
      • CLI
      • REPL
    • Serializer
      • [_] JSON to Oli
      • [_] Concret Syntax Tree to Oli
    • Engines
      • Node.js
      • Browsers
      • [?] Rhino

    Upcoming features

    There are important features in Oli language spec 0.2. You can see the future features discussion here

    A summary about most important features that will be implemented

    • Interpolated code expressions (oli/#3)
    • Generic helper functions (random, string format, date format...)
    • Helpers functions extension via API
    • Block scope references (oli/#18)
    • Indentation-based parsing (oli/#5)
    • Date as first-class primitive type (oli/#2)

    Command-line interface

    Usage: oli [options] path/to/file.oli
    
    Options:
    
      -h, --help           output usage information
      -V, --version        output the version number
      -p, --parse          parse and return the result as JSON
      -t, --tokens         parse and return a collection of the tokens as JSON
      -o, --output <file>  write output into a file instead of stdout
      -a, --ast            return the parsed AST serialized as JSON
      -i, --in-line        parse in-line argument as string
      -d, --indent <size>  JSON output indent size. Default to 2
      -s, --stdin          Read source from stdin
      -r, --repl           use the interactive read-eval-print loop interface
    
    Examples:
    
      $ oli file.oli > file.result.json
      $ oli file.oli -o file.result.json
      $ oli --ast file.oli
      $ oli --tokens file.oli
      $ oli --in-line "hello: oli!" > result.json
      $ oli -s < file.oli
    
    

    REPL

    Run $ oli without arguments to play with the REPL interface

    $ oli
    Oli experimental REPL interface
    Type "examples" to see code examples
    oli> - oli, rules, yes
    

    Programmatic API

    Example

    Require the module

    var oli = require('oli')
    

    Simple parsing

    var code = 'message: - hello, oli!'
    try {
      var result = oli.parse(code)
    } catch (e) {
      console.error('Error while parsing:', e.message)
      console.error(e.errorLines)
    }
    console.log(result) // => { message: [ "hello", "oli!" ] } }

    Binding a custom context to the compiler

    var code = 'directory: *env.HOME'
    var result = oli.parse(code, {
      locals: {
        env: process.env
      }
    })

    parse(code, options)

    Alias: transpile Return: mixed

    Parse and process the given code performing an end-to-end compilation and return the final result, that will be usually an object with the equivalent scheme tree equivalent representation of the Oli source code

    ast(code, options)

    Alias: parseAST Return: object

    This is the most low-level API method. It returns an object that represent the parsed abstract-syntax tree

    Note: AST node types or tree data structures can change between minor versions, as the parser is still beta. Please be aware with that in order to prevent possible inconsistencies if your implementation is coupled to the parsed AST

    parseMeta(code, options)

    Alias: meta Return: mixed

    Parse a given code and return an intermediate resultant object tree structure which includes meta data such as block operators, block expressions, references and attributes prefixed with $$

    compile(ast)

    Alias: run Return: mixed

    Process the given AST and return the compilation result.

    tokens(code, options)

    Alias: parseTokens Return: array

    Returns a one-level objects collection with the existent tokens in the given code

    load(path, callback)

    Context: browser

    Performs an asynchronous XHR request and pass to the callback the response body as plain text. It will throw an Error exception if cannot perform the request

    oli.load('path/to/file.oli', function (text) {
      console.log(oli.parse(text))
    })

    oli.Compiler(ast, options)

    The compiler perform a side-by-side code transformation and generation given an AST tree. It creates a new memory context and uses the tranformer and generator in order to proceed with the compilation

    Once you create an instance of the object, you need to call the compile() method in order to perform the compilation

    oli.Compiler.transformer(ast, memoryContext)

    This method performs an AST traversal walk transforming each node and returning an intermediate-level simplified object tree

    oli.Compiler.generator(obj, memoryContext)

    Takes the intermediate object from the trasnformation process and performs the final code generator. It takes the responsabilities of the interpreter, data mutation and final code generation

    oli.Compiler.nodes

    An object with the AST node type transformer functions

    Options

     meta

    Type: boolean Default: false

    Return an intermediate level object with metadata properties. This is useful when you need to process an intermediate object that includes tokens, operators, expressions and more, instead of process a cutted resultant object

    loc

    Type: boolean Default: false

    locals

    Type: object Default: null

    Set of local variables context to be passed to the compilation sandbox

    Errors

    oli.js provides detailed errors. Usually it will be throwed as exception

    Types

    • SyntaxError
    • CompileError
    • TypeError
    • ReferenceError

    Members

    Each error object instance will have the following members

    • message
    • fullMessage
    • line
    • column
    • offset
    • expect (SyntaxError only)
    • found (SyntaxError only)

    Contributing

    Wanna help? Cool! It will be really apreciated :)

    You must add new test cases for any new feature or refactor you do, always following the same design/code patterns that already exist

    Tests specs are completely written in LiveScript language. Take a look to the language documentation if you are new with it. You should follow the LiveScript language conventions defined in the coding style guide

    Development

    Only node.js and Grunt are required for development

    Clone/fork this repository

    $ git clone https://github.com/oli-lang/oli-js.git && cd oli-js
    

    Install package dependencies

    $ npm install
    

    Run tests

    $ npm test
    

    Run benchmarks

    grunt bench
    

    Coding zen mode

    $ grunt dev [--force]
    

    Cyclomatic complexibility report

    $ grunt plato
    

    Browser sources bundle

    $ grunt build
    

    Release a new version

    $ grunt release
    

    License

    Copyright (c) Tomas Aparicio

    Released under the MIT license

    Bitdeli Badge

    install

    npm i oli

    Downloadsweekly downloads

    5

    version

    0.1.0

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar