REPO groovy syntax

INV's has its own DSL using the Groovy framework.

This is the syntax for implementing an REPO:

/**
    Adds a new debugging message.
    It is available in the whole script scope. Thus, inside any REPO.
    
    Per example:    
        repo {
            ...
            ask {
                debug "Something"
            }
        }

    @optional
    @type Object
    @default None, a value is required
*/
debug("My message")

/**
    Creates a new REPO object to be processed.
    
    @optional
    @type Closure
    @default None, a value is required
*/
repo {

    /**
        Defines the name of the new REPO object.

        name is accessible within hooks and asks statement by inserting ${name}
        Per example: 
            hooks {
                init "echo 'What's me ${name}?'"
            }
    
        @required
        @type String
        @default None, a value is required
    */
    name "MyName"

    /**
        Defines the path WITHIN the repository path to lookup for source files.

        @optional
        @type String
        @default .inv
    */
    path "./my/path/..."

    /**
        Defines the source access point.
        It can be the git http or ssh address, same thing for SVN and the others.

        src is accessible within hooks and ask statement by inserting ${src}
        Per example: 
            hooks {
                init "git clone ${src}"
            }

        @optional
        @type String
        @default None, a value is required
    */
    src "https://...."

    /**
        Defines the hooks commands execution timeout threshold in milliseconds.
        By default, the timeout is 60000.

        timeout is accessible within hooks and ask statement by inserting ${timeout}
        Per example: 
            hooks {
                init "timeout ${timeout} ..."
            }

        @optional
        @type Integer
        @default None, a value is required
    */
    timeout 30000

    /**
        Defines the ask statement for this REPO.
        It allows predefining questions for the end-user upon using this REPO.
        
        It is quite useful when you want the user to choose the source and target branch during hook's init.

        INV Composer uses this statement durant the Configure step.

        @optional
        @type Closure
        @default None, a value is required
    */
    ask {
    
        /**
            Defines a parameter to the REPO.
            Upon resolution by the end-user, each resolved parameter is available inside hooks

            Per example:
                ask {
                    parameter "source", "Source branch", [defaultValue: "master"]
                    parameter "target", "Source branch"
                }
                hooks {
                    init """
git clone -b ${source} ${src}
git checkout -b ${target}
git push ${target}:${target}
"""
                }

            This is a simple implementation of how we could handle source and target branches during hook's init.

            @param parameterName
                Sets the parameter's name.             
                This is the name you would use within hooks.
        
                @required
                @type String
                @default None, the value required

            @param usage
                Sets the usage text.             
        
                @required
                @type String
                @default None, the value required

            @param Map Options of this parameter
    
                @option defaultValue
                    Sets the default value for the parameter.             
            
                    @optional
                    @type String
                    @default None, the value required

               @option required
                    Indicates this parameter MUST have a valid value
                    By default, true.             
            
                    @optional
                    @type Boolean
                    @default None, the value required
    
                @option values
                    Sets static values for this parameter.
                    
                    Per example:
                        ask {
                            parameter "myArrayValues", "This is a static array of values", [
                                values: ["value1", "value2"]
                            ]
                        }
                    In this case, the user would be offered with two values "value1" and "value2.
    
                    @optional
                    @type List<String>
                    @default None, a value is required
    
                @option command
                    Sets a command that provides values.
    
                    Per example: 
                        ask {
                            parameter "source", "Select the source branch", [
                                defaultValue: "master", 
                                command: "git ls-remote ${src}"
                            ]
                        }
                    In this case, INV would execute "git ls-remote ${src}" (see how we reuse ${src}). 
                    NOTE: This command list remote branches for a git repository.
        
                    Multiple lines are not recommended.
            
                    @optional
                    @type String
                    @default None, the value required

                @option filter
                    Sets the filter callback for values.
                    Closure input is a String representation of a single-line of the command output.
                    
                    Returning NON-EMPTY String means the returned value will be shown to the end-user.
                    Returning EMPTY or NULL means the line will NOT be shown to the end-user.
                    
                    Per example: 
                        ask {
                            parameter "source", "Select the source branch", [
                                defaultValue: "master", 
                                values: ["my", "value"], 
                                filter: {
                                    if (it.contains("my")) {
                                        // ...
                                        return it
                                    }
                                }
                            ]
                        } 
                        NOTE: Here, it would output ["value"]. 
                              This is not relevant context-wise.
                              But, it is quite powerful when values is fed from
                              an external file (or data source)
            
                    @optional
                    @type Closure
                    @default None, a value is required
                    @return A String representation of what to show to the end-user
    
                @option filterRegex
                    Sets the Regex filter for values.
                    The regex can have only ONE capture group.
                    
                    Per example: 
                        ask {
                            parameter "source", "Select the source branch", [
                                defaultValue: "master", 
                                command: "git ls-remote ${src}", 
                                filterRegex: /.*refs\/((?:heads|tags).*)/
                            ]
                        }
                    In this case, the regex /.*refs\/((?:heads|tags).*)/ is applied to EACH lines resulting the command 
                    NOTE: This Regex remove leading characters and capture a simplified branch name. 
            
                    @optional
                    @type String (using Regular Expression syntax /../)
                    @default None, a value is required

        */
        parameter "command", "description", "defaultValue", "values", "filter"
        parameter "command", "description", "defaultValue", [values], "filter"
    }

    /**
        Defines a hook statement.
        This statement allows defining String commands for events during the processing of this REPO.

        @required
        @type Closure
        @default None, a value is required
    */
    hooks {
        
        /**
            Defines the init event commands for this REPO.
            It handles single or multiple lines of commands.

            It is raised when path (or ${path), see above) DOES NOT EXIST on the filesystem.
            Before raising this event, path is created.
            Commands are executed within that path.

            Per example:
                hooks {
                    init """
git clone ${src}
"""
                }

            IMPORTANT: If the exitValue is not 0, path folder is DELETED.

            Multiple lines are HIGHLY recommended.

            @required
            @type String
            @default None, a value is required
        */
        init """
"""

        /**
            Defines the update event commands for this REPO.
            It handles single or multiple lines of commands.
    
            It is raised when path (or ${path), see above) EXISTS on the filesystem.
            Commands are executed within that path.

            Multiple lines are HIGHLY recommended.

            Per example:
                hooks {
                    update """
git pull
"""
                }

            @optional
            @type String
            @default None, a value is required
        */
        pull """
"""
        /**
            DEPRECATED. See pull().
        */
        update """
"""

    }
}

For more examples, check here