Nightmare Prom Memories

    prorenata

    1.0.53 • Public • Published

    Prorenata

    P.R.N. (As the circumstance arises)

    by Read Write Tools Nov 19, 2016
    Abstract
    The prorenata build tool is used to execute a sequence of commands on a hierarchy of file paths, using parameters that are defined with a declarative approach, rather than a procedural approach.

    Motivation

    The venerable make command is the inspiration for prorenata.

    Building, testing and deploying software requires a sequence a steps which need to be followed each time a file or one of its dependencies changes. In most cases, these steps should be conditioned on file timestamps, where a step should only be redone when the output of its previous execution is older than the corresponding input file's timestamp. In other words, only execute the step on an as needed basis.

    The name of this utility comes from nursing jargon prorenata (p.r.n.) which means "as the circumstance arises".

    Prerequisites and installation

    The prorenata utility uses Node.js. Package installation is done via NPM.

    This utility requires the BLUE-PHRASE parser, which is distributed with each copy of validly licensed Read Write Tools premium tools.

    To install the utility and make it available to your Bash shell, use this command.

    [user@host]# npm install -g prorenata

    Usage

    The software is invoked from the command line with:

    [user@host]# renata [script-file]

    The script file contains commands in this form:

    command {
       parameter value
    }

    Commands

    There are 6 built-in commands:

    1. copy recursively copies all files in to
    2. compare lists files that are in but not in
    3. clean removes files that are older than
    4. recurse runs a template-defined command recursively over all files in
    5. run executes an arbitrary shell command
    6. template defines new commands for use with the parameter of recurse

    Any name that does not match one of these 6 is considered to be a user-defined command, and it may be used as a command in a template.

    Parameters

    The are 15 built-in parameters:

    1. source an absolute or relative path
    2. dest an absolute or relative path
    3. include+ a file pattern to include, if omitted defaults to '*'
    4. exclude+ a file pattern to exclude
    5. extension the filename extension to apply to destination filenames
    6. exec a command name defined in the template section
    7. overwrite: always | older | never‡
    8. mkdir: true‡ | false (create missing directories)
    9. preserve: true | false‡ (preserve timestamps)
    10. trigger an absolute or relative filename
    11. dependent+ an absolute or relative path
    12. sh+ a shell command to execute
    13. if+ a conditional if [hostname ==] | [hostname !=] then ... else ...
    14. progress: verbose | regular‡ | none
    15. onerror: continue | halt‡

    + parameter that may be provided multiple times

    ‡ optional parameter default value

    Any name that does not match one of these 15 is considered to be a user-defined parameter. Both built-in and user-defined parameters may be used as substitution variables in a template.

    The parameters that may be used with each command are:

    copy source* | dest* | include | exclude | extension | overwrite | mkdir | preserve | progress | onerror
    compare source* | dest* | include | exclude | extension | onerror
    clean trigger* | dependent* | progress | onerror
    recurse source* | exec* | include | exclude | extension | overwrite | mkdir | progress | dest | onerror
    run sh | if | progress | onerror

    * required parameter

    A pair of less-than and greater-than characters are used to enclose a named substitution variable. Use substitutions with recurse, copy and compare commands. Place substitution variables in a template, and the current path or filename will be substituted.

    The substitution variables:

    source The absolute path and filename of the current source file
    sourcepath The local path of the current source file
    sourcefile The current source filename only
    dest The absolute path and filename of the current dest file
    destpath The local path of the current dest file
    destfile The current dest filename only

    Examples

    Here is an example using copy to recursively copy files with *.html extension from 'foo' to 'bar'

    copy {
       source  foo
       dest    bar
       include '*.html'
    }

    Here is an example using template and recurse to compile LESS into CSS from 'foo' to 'bar'

    template {
       compile-css lessc <source> <dest>
    }
    recurse {
       source    foo
       dest      bar
       include   '*.less'
       extension '.css'
       exec      compile-css
    }

    Here is an example using template and a user-defined command to count the number of files in 'foo' with an 'html' extension

    template {
       count-by-ext ls -l <path> | grep <ext> | wc -l
    }
    count-by-ext {
       path      foo
       ext       html
    }

    License

    The prorenata command line utility is licensed under the MIT License.

    MIT License

    Copyright © 2020 Read Write Tools.

    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.

    Availability

    Source code github
    Package installation NPM
    Documentation Read Write Hub

    Install

    npm i prorenata

    DownloadsWeekly Downloads

    5

    Version

    1.0.53

    License

    MIT

    Unpacked Size

    45 kB

    Total Files

    7

    Last publish

    Collaborators

    • joehonton