If you want users to be able to pass file globbing patterns to your command, set a type of Globber for the argument.

Even though the user types a string, CommandBox will hand you a CFC instance that's preloaded with the matching paths and has some nice methods to help you interact with the matching paths. The Globber object lazy loads the matches, which gives you time to affect the pattern or even the sort if you wish prior to the file system actually being hit.

Globber.count()

Use the count() method to get the total number of paths matched on the file system.

Globber.apply( ... )

The easiest way to apply some processing to each of the file paths found is by passing a closure to the apply() method. The closure will be executed once for each result.

Globber.matches()

To get the raw results back, use the matches() method.

Globber.asQuery()

If you want to get the results back as a query object, use the asQuery() method and then you can loop over them yourself. The query contents match what comes back from directoryList().

Globber.asArray()

If you want to get the results back as an array, use the asArray() method and then you can loop over them yourself.

Globber.withSort( ... )

Affect the order that the results come back by setting a sort. The sort follows the same pattern as the directoryList() function, which means it can be a comma-delimited list of columns to sort on.

Globber.getPattern()

To get the original globbing pattern that the user typed, use the getPattern() method on the Globber CFC.

Create your own Globber

You can create your own File Gobber object from any pattern using the globber() method. You can pass a comma delimited list or an array of globber patterns to the constructor.

You can also add additional glob patterns to an existing Globber object.

Exclude Patterns

Sometimes when using a Globbing pattern, it's desirable to exclude a small number of patterns and it's cumbersome to manually include every pattern you want. You can set more than one excludes pattern to be passed to filter the matches. Excludes follow the same format as include patterns. If a pattern is both excluded and included, the exclude wins.

Excludes, like includes, allow for a comma-delimited list or an array to be passed.

The setExcludePattern() method will override any existing methods, but the addExcludePattern() method will add to the existing list.

Sometimes you have a command that can need an undetermined number of configuration items that all relate to the same thing. CommandBox can accept any number of named or positional parameters, but it can be hard to collect a dynamic and unknown number of parameters. An easy way to handle this is to have the user prefix each grouped parameter name with something: like this.

doWidget widgetProp:foo=blue widgetProp:bar=seven widgetProp:baz=turkey

This will create a single item in the arguments scope of your command called widgetProp which is a struct and contains the keys foo, bar, and baz. You can loop over the widgetProp struct to access the collection in a concise manner. You can have as any of these parameter groups as you want, and a struct will be created for each unique parameter prefix.

You can omit the prefix entirely and just start a collection of parameters with a colon (:) and they will be placed in a struct called args.

doWidget :foo=blue :bar=seven :baz=turkey

And the command might look like this:

function run( args={} ){
    args.each( function( k, v ) {
        print.line( '#k# has a value of #v#.' );
    } );
}

Which, given the parameters shown above, would output this:

foo has a value of blue.
bar has a value of seven.
baz has a value of turkey.

To escape a literal colon (:) in a parameter name, put a backslash in front of it:

server set foo\:bar=baz

which will create a literal key of foo:bar.

Regardless of whether your command is called with named parameters, positional parameters or boolean flags, you'll access them the same way: via the standard CFML arguments scope. The user will be prompted for required parameters if they haven't provided them, and the defaults you configured will also work just like you expect.

If the parameters were escaped when typed into the command line, you will receive the final unescaped version in your command.

Dynamic Parameters

Users can pass named or positional parameters that aren't declared, and they will come through the arguments scope. Named parameters will be accessible as arguments.name, and positional parameters as arguments[ 1 ], arguments.[ 2 ], etc.

This can allow for powerful commands like package set that allows users to set any box.json property they want.

package set foo=bar

File System Paths As Parameters

If your command accepts a file or folder path from the user, you'll want to resolve that path before you use it. To do this, use the resolvePath() method that is available to all commands via the BaseCommand class. (This method wraps the resolvePath() method of the fileSystemUtil object that is injected into all commands.) The method resolvePath() will make the file system path canonical and absolute. This ensures you have a fully qualified path to work with even if a user might passed a folder relative to their current working directory passed something like ../../.

component extends="commandbox.system.BaseCommand" {

    function run( String directory )  {
        // This will make each directory canonical and absolute
        arguments.directory = resolvePath( arguments.directory );
        return arguments.directory;
    }
}

If you run that command and pass a full file path such as C:\sandbox\testSite, you would get that exact same path back as the output.

However, if you changed the interactive shell to the C:\sandbox directory and then ran the command with testsite as the input, the relative path would now still resolve to C:\sandbox\testSite.

If, from the same directory, you passed testsite/foo/bar/../../, you would still get C:\sandbox\testSite as the path.