Nevertheless! Party Metaphorically

    supchik

    0.2.5 • Public • Published

    Supchik

    Build Status

    Supchik like Borschik but with source maps support and one more thing... things.

    Supchik features

    • Borshick JS include notations
    • AST processing under the hood (https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API)
    • Сustomizable AST transformations
    • Source map generation
    • Minimize support
    • Accurate error handling
    • Well documented
    • Heavy tested

    Limitations

    • No CSS processing
    • No HTML processing
    • No freezing
    • No resource inlining
    • Just JS

    Contents

    ## Command line usage

    Install global: npm install supchik -g

    
    // `source.js` to `source.output.js`
    supchik source.js
    
    // `source.js` to `source.output.js` with pretty print
    supchik source.js --pretty-print
    
    // `source.js` to `source.output.js` with source map
    supchik source.js --source-map output.js.map
    
    // `source.js` to ast `source.output.json`
    supchik source.js --output-format ast --output source.output.json
    
    

    Command line options list

    Usage: supchik <file ...> [options]
    
      Options:
    
        -h, --help                 output usage information
        -V, --version              output the version number
        -o, --output               Specify output file.
        --input-format <format>    Specify input format: `code` or `ast`. Default: `code`.
        --output-format <format>   Specify output format: `code` or `ast`. Default: `code`.
        --source-map <file>        Specify source map output file.
        --transforms <transforms>  Specify transform modules. Default: `borschik`.
        --pretty-print             Pretty print output. Default: true.
        --verbose                  Default: false.
    
    ## node.js usage

    Install: npm install supchik

        var supchik = require('supchik');
     
        // Compile `source.js` to `output.js`
        supchik.compile('source.js', 'output.js', {
            inputFormat: supchik.Format.FILE_CODE,
            outputFormat: supchik.Format.FILE_CODE
        });
     
        // Compile from source string to `output.js`
        var source = fs.readFileSync('source.js', { encoding: 'utf-8' });
        supchik.compile(source, 'output.js', {
            outputFormat: supchik.Format.FILE_CODE
        });
     
        // Compile from source string to generated source string
        var generatedSource = supchik.compile(source);
     
        // Compile from source string to generated AST
        var generatedAst = supchik.compile(source, null, {
            outputFormat: supchik.Format.AST
        });
     
        // Compile from AST to generated source string
        var ast = esprima.parse(source);
        generatedSource = supchik.compile(ast, null, {
            inputFormat: supchik.Format.AST
        });
     
        // Compile `source.js` to generated AST file
        supchik.compile('source.js', 'output.ast.json', {
            inputFormat: supchik.Format.FILE_CODE,
            outputFormat: supchik.Format.FILE_AST
        });
     
        // Advanced example
        var output = {};
        supchik.compile(source, output, {
            sourceMap: 'output.js.map',
            prettyPrint: true, // pretty print output
            // additional AST transformation stages
            transforms: [ '/path/to/my/transform/module' ],
            techs: { // specify techs
                js: require('/path/to/my/js/tech'),
                txt: MyTxtTech,
                custom: MyCustomExtensionTech
            },
            file: require('/path/to/my/file') // specify file system engine
        });
     
        output.source; // file source string
        output.ast; // generated AST
        output.sourceMap; // source map string
        output.compiledSource; // compiled source string
     
        // Supported input formats
        supchik.Format.FILE_CODE; // read js file
        supchik.Format.FILE_AST; // read ast json file
        supchik.Format.CODE; // string js source
        supchik.Format.AST; // ast json source
     
        // Supported output formats
        supchik.Format.FILE_CODE; // write js file
        supchik.Format.FILE_AST; // write ast json file
        supchik.Format.CODE; // output as js string
        supchik.Format.AST; // output as ast json
    ## Error handling

    One of the Supchik's goals to accurate handle errors. It uses rich exceptions design to tell you about errors.

     
        try {
            supchik.compile( ... );
        } catch(error) {
            if(error instanceof supchik.ParseError) {
                // Parse source error occured
     
                error.source;      // file
                error.lineNumber;  // at line number
                error.column;      // at column number
                error.description; // error's description
     
            } else if(error instanceof supchik.GenerateError) {
                // Generate source from AST error occured
     
                error.description; // error's description
     
            } else if(error instanceof supchik.ReadError){
                // Read file error occured
     
                error.source; // file
     
            } else if(error instanceof supchik.WriteError) {
                // Write file error occured
     
                error.source; // file
     
            } else {
                // Other error not tracked by Supchik
            }
        }
     
    ## Borshick JS include notations diffirence

    All literal notations always escapes as include type. Except string literal notation that always escapes strings.

     
        var a = {/*borschik:include:a.json*/}; // var a = { a: true };
        var b = {/*borschik:include:b.txt*/};  // var b = 'Text from B';
        var c = 'borschik:include:c.json';     // var c = '{"c":true}';
     

    All JavaScript includes must provide valid JavaScript source and must lends to AST node's body.

     
        /*borschik:include:a.js*/ // ok
     
        /*borschik:include:a.json*/ // failed! makes source js file not valid.
     
        /*borschik:include:a.txt*/ // failed! makes source js file not valid.
     
        for(;;) {
           /*borschik:include:b.js*/ // ok
        }
     
        for(;/*borschik:include:b.js*/;) { // failed! makes source js file not valid.
        }
     
        if(true) {
           /*borschik:include:b.js*/ // ok
        } else  {
           /*borschik:include:b.js*/ // ok
        }
     
        if({/*borschik:include:b.js*/}) { // failed! makes source js file not valid.
        }
     
        function f() {
           /*borschik:include:b.js*/ // ok
        }
     
        function f(/*borschik:include:b.js*/) { // failed! makes source js file not valid.
        }
     
        var c = {/*borschik:include:c.json*/}; // ok
     
        var c = {/*borschik:include:c.js*/}; // failed! makes source js file not valid.
     

    Borshick JS include notations reference

    ## Understanding techs

    Techs role in Supchik to generate Mozilla AST tree from source string. Supchik's techs must export parse method that accepts source string and returns Mozilla AST tree. Basic example:

        function parse(input, options) {
            options = options || {};
     
            return {
                type: 'Program',
                body: [{
                    type: 'Literal',
                    kind: 'string',
                    value: input,
                    loc: {
                        range: [ 0, input.length ],
                        start: { line: 1, column: 0 },
                        end: { line: 1, column: input.length }
                        source: options.source || null
                    }
                }]
            };
        }
     
        module.exports = {
            parse: parse
        };

    node.js usage:

        ...
     
        var MyCustomTech = {
            parse: function(input, options) { ... }
        };
     
        supchik.compile(source, null, {
            techs: {
                js: require('/path/to/my/js/tech'),
                custom: MyCustomTech
            }
        });
     
        ...
    ## Understanding transformations

    Supchik's transformation allow to provide your custom AST transformation stage. Transformation must export transfrom method that accepts Mozilla AST tree and returns transformed Mozilla AST Tree. Basic example:

        var estraverse = require('estraverse');
     
        function transform(ast, options) {
            options = options || {};
     
            options.sourcePath; // path to file as array: [ '/path/to/file/', '..' ]
            options.source;     // file name: ../file.js
            options.file;       // file engine
            options.techs;      // available techs
            options.transforms; // available transforms
     
            // Let's make all vars names forced lowercase
            estraverse.traverse(ast, {
                enter: function(node, parent) {
                    if(node.type === 'Identifier') {
                        node.name = node.name.toLowerCase();
                    }
                }
            });
        }
     
        module.exports = {
            transform: transform
        };

    Command line usage

        supchik source.js --transforms /path/to/my/transform/module,/path/to/my/other/transform/module
    

    node.js usage

        ...
     
        var MyTransformModule = {
            transform: function(ast, options) { ... }
        };
     
        supchik.compile(source, null, {
            transforms: [ '/path/to/my/transform/module', MyTransformModule ]
        });
     
        ...
    ## Tests

    Supchik uses Mocha framework for tests. Run tests: npm test.

    ## Contribution guide

    Just try to keep current code styles.

    ## License
    The MIT License (MIT)
    
    Copyright (c) 2013 Vitaliy Green
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
    

    lodash license

    Copyright 2012-2013 The Dojo Foundation <http://dojofoundation.org/>
    Based on Underscore.js 1.5.2, copyright 2009-2013 Jeremy Ashkenas,
    DocumentCloud and Investigative Reporters & Editors <http://underscorejs.org/>
    
    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:
    
    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    

    commander license

    (The MIT License)
    
    Copyright (c) 2011 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
    
    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    'Software'), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:
    
    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    

    esprima license

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
      * Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
      * Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
    THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    

    estraverse license

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
      * Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
      * Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
    THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    

    escodegen license

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
      * Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
      * Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
    THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    

    mocha license

    (The MIT License)
    
    Copyright (c) 2011-2013 TJ Holowaychuk <tj@vision-media.ca>
    
    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    'Software'), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:
    
    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    

    chai license

    (The MIT License)
    
    Copyright (c) 2011-2013 Jake Luer <jake@alogicalparadox.com>
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
    

    wrench license

    The MIT License
    
    Copyright (c) 2010 Ryan McGrath
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
    

    Install

    npm i supchik

    DownloadsWeekly Downloads

    1

    Version

    0.2.5

    License

    MIT

    Last publish

    Collaborators

    • vitaliygreen