‚̧Negligible Psychological Misery

    water-drop

    2.0.1¬†‚Äʬ†Public¬†‚Äʬ†Published

    water-drop Build Status

    ūüíß very easy to use multi-language scaffolding/boilerplate tool for creating code for your existing projects

    Idea

    A growing big project might eventually require contributors to write different boilerplates/code templates to be used as a starting point for new modules. Most often those templates are files to copy-paste followed by few variable renamings to reflect new module's name. water-drop is a scaffolding/boilerplate tool which allows to create new code based on the provided existing templates written by anyone.

    This tool was created keeping in mind the following conditions:

    1. It has to work for multiple languages (Go, JavaScript, Python, etc).
    2. It has to be easy to use. Nobody should go through pages of documentation or reading many lines of code in order to understand how this tool works.
    3. It has to be easy to setup new templates to be used by everyone. (For this project Handlebars was picked as the main templating engine for its simplicity. You can read more on Handlebars templating here)

    Installation

    Global installation (suggested)

    $ npm i -g water-drop
    $ water-drop
    

    Local installation

    $ npm install water-drop
    $ node_modules/.bin/water-drop
    

    Usage

    USAGE
      $ water-drop <command>
    
    where <command> is one of:
      init, list, template, create, uninit
    
    water-drop <command> -i     quick help on <command>
    
    EXAMPLES
      $ water-drop init
    
      $ water-drop create myNewShinyModule -t exampleModule -p path/within/my/project -v
    
      $ water-drop list
    
      $ water-drop template mySecondShinyModule
    
      $ water-drop template moduleToRemove -d
    
      $ water-drop uninit
    

    Template Creation Example

    • Let's imagine our team need to create lots of new modules which have the same comment about MIT license.
    • Let's imagine we need to include a constant file inside our new module.

    Step 1 (Init water-drop in the folder with future templates)

    $ cd /my/amazing/project/
    
    $ water-drop init
    

    Step 2 (Bootstrap new template)

    $ water-drop template licensedCode
    

    Step 3 (Modify auto-generated config)

    modify water-drop-templates/licensedCode/config.json file

    {
        "steps": [
            { "cmd": "mkdir", "path": "{{myProjectPath}}/{{_mPath}}" },
            {
                "cmd": "cpf",
                "what": "licensedFile.js",
                "to": "{{myProjectPath}}/{{_mPath}}/{{lcase _mName}}.js"
            },
            {
                "cmd": "cp",
                "what": "constants.js",
                "to": "{{myProjectPath}}/{{_mPath}}/constants.js"
            }
        ],
     
        "vars": {
            "myProjectPath": "./",
            "author": "Alexey Novak"
        }
    }

    Step 4 (Add template files)

    Create file water-drop-template/licensedCode/__files/licensedFile.js

    // MIT © {{author}}
     
    import * from './constants.js';
     
    function {{ucase _mName}}() {
     
    }
     
    export default {{ucase _mName}};

    Create file water-drop-template/licensedCode/__files/constants.js

    const config = {
        VERSION: '1.0.0',
     
        // place your config files here
    };
     
    export default config;

    Step 5 (Run water-drop to generate new module based on the template)

    Run $ water-drop create NewModule -t licensedCode -p /ui/utils -v

    New folder ui/utils/ should be generated in the same folder as water-drop.json config file.

    With new files ui/utils/constants.js and ui/utils/newModule.js

    Available 3 Config Steps

    mkdir

    { "cmd": "mkdir", "path": "some/folder/structure" }
    Property Description Can Use Templating
    path New folder path. The whole folder tree will be created if does not exist. Path is relative to the folder where water-drop command is executed. Yes

    cp

    {
        "cmd": "cp",
        "what": "fileTemplate.txt",
        "to": "some/folder/structure/file.txt"
    },
    Property Description Can Use Templating
    what Path to the file within water-drop-template/<template_type>/ to be used for a file copy operation. No
    to Path to where file will be copied over. Path is relative to the folder where water-drop command is executed. Yes

    cpf

    {
        "cmd": "cpf",
        "what": "fileTemplate.txt",
        "to": "some/folder/structure/file.txt"
    },
    Property Description Can Use Templating
    what Path to the file within water-drop-template/<template_type>/ to be used for a file copy operation. water-drop will apply templating to the content of the file to make changes on its content. No
    to Path to where file will be copied over. Path is relative to the folder where water-drop command is executed. Yes

    Available (extra) Handlebar Helpers

    Helper Description Example
    ucase Uppercases first character myModule -> MyModule
    lcase Lowercases first character MyModule -> myModule
    ucaseall Uppercases the whole string myModule -> MYMODULE
    lcaseall Lowercases the whole string MyModule -> mymodule
    u_case_all Uppercases the whole string and also adds _ character between each uppercase character MyModule -> MY_MODULE
    l_case_all Lowercases the whole string and also adds _ character between each uppercase character MyModule -> my_module

    Context

    Handlebars uses context object for templating function. Context for each template consist of the following variables:

    • All variables within vars property of the config withijn water-drop.json file
    • All variables within vars property of the template configuration within water-drop.json file
    • _mType - template type used to create new module (passed through CLI)
    • _mName - new module name (passed through CLI)
    • _mPath - path to the new module (passed through CLI)

    Also some specific water-drop tool configuration which most of the times you do not need to modify:

    • _tFolder - location of the folder with template files
    • _tOpenTag - special open tag to be used for cpf command
    • _tCloseTag - special close tag to be used for cpf command

    Limitation

    It is very important to remember that Handlebars keeps {{ and }} reserved for its template logic. Use <%% and %%> respectively in case when a template needs to preserve those tags.

    Example:

    style=<%% weight: 50px, height: 50px %%>
    
    will be converted to
    
    style={{ weight: 50px, height: 50px }}
    

    Also you might face a problem when trying to replace a value within the object. Example:

    // some of my react code
     
    object={this.props.{{lcase _mName}}}
     
    // this would fail since Handlebars would not like those closing }}}

    You will need to re-write it as

    object={this.props.{{lcase _mName}} }
    

    Future Improvements

    1. There are no tests present for this project yet.
    2. Step command which will be able to inject a line of code into another existing file "in a smart way".
    3. Roll-back mechanism for any auto-generated content in case when there is an error during execution.
    4. Ability to pre-parse and detect issues within the config prior steps execution.
    5. More detailed logging to identify an exact problem when there is a failure.

    License

    MIT license; see LICENSE.

    (c) 2017 by Alexey Novak

    Install

    npm i water-drop

    DownloadsWeekly Downloads

    5

    Version

    2.0.1

    License

    MIT

    Last publish

    Collaborators

    • roserocket
    • anvk