1. CommandBox CLI
Automating All Things CFML
Now with Task Runners! Brad Wood
@bdw429s

2. #FreeCFML
● CFML is for templating HTML
● Only usable with a web server
● Must install server
● Only access via HTTP

3. #FreeCFML
● CFML runs anywhere the JVM does
● JSR-223
● Can be used for embedded devices
● Run from the command line
● Outside of a servlet container
● Put it on a Raspberry Pi!

4. #FreeCFML
pi.bradwood.com

5. #FreeCFML
CFML-powered hat
https://github.com/bdw429s/CFML-Pi-Hat

6. CommandBox
● Native OS binary (Mac, Linux, Windows)
● CLI
● REPL
● Command-based
● Lightweight
● Extensible

7. Install CommandBox
www.ortussolutions.com/products/commandbox
● apt-get
● yum
● Homebrew
● Download box[.exe] binary
https://commandbox.ortusbooks.com

8. CFML via the CLI
REPL
(Read Eval Print Loop)

9. Running Native Shell
> !myApp.exe
> !/path/to/myApp
> !dir
> !netstat -pan
> !npm ll
> !ipconfig
> !ping google.com -c 4
> !java -jar myLib.jar

10. Running CFML Functions
> #now
> #hash mypass
> #reverse abc
> #listGetAt www.foo.com 2 . | #ucase | #reverse

11. Running Expressions
> server start name=`cat defaultServer.txt`
> echo "Your CBox version: `ver` & app is '`package show name`'!!"
> package set createdDate='"`#now | #dateformat mm/dd/yyyy`"'

12. Running Mashups
> forgebox show coldbox --json | #structFind versions | #arrayFirst | #structFind version

13. Automation
OS .cfm execution
> execute test.cfm

14. Automation
Unix #! Shell scripts
myScript.sh
#!/usr/bin/env box
<cfoutput>#now()#</cfoutput>

15. Automation
Unix #! Shell scripts
$> chmod +x myScript.sh
$> ./myScript.sh
{ts '2015-02-19 20:31:32'}

16. Custom Commands
● CFConfig
● CFDocs
● DocBox
● Cfscript.me
● ImageToASCII
install commandbox-cfconfig

17. Task Runners
● Does (most) everything a custom command does
● It’s a single CFC
● Portable
● No installation
● Easy to distribute
● Can have more than one target (like Ant)
● Replaces other build tools like Ant, Shell, or Grunt
● Doesn’t require any server to be started

18. Task Runner features
● Very little boilerplate
● Pure CLI execution (of CFML)
● Built in parameter handling
● CLI interactivity with user
● ANSI color formatting
● Access to file globbing/watchers/etc
● Can also run commands or native OS binaries
● Easy output helpers

19. Task Runner Anatomy
Task.cfc
component {
function run() {
print.greenLine( 'Hello, World!' );
}
}

20. Task Runner Anatomy
CommandBox> task run
Hello, World!

21. Task Runner Anatomy
● Default filename is Task.cfc
● Default method (target) is run()
● But you can call them whatever you want!
CommandBox> task run myTask
CommandBox> task run myTask myTarget

22. Task Runner Parameters
Task.cfc
component {
function run( required param1, boolean force=false ) {
if( force )
print.line( 'Param 1 is [#param1#]' );
}
}

23. Task Runner Parameters
● Named or positional
● Task named params start with :
● Flags work, but need : as well
task run task.cfc run value1 value2
task run :param1=value1 :param2=value2
task run myTask --:force

24. Task Runner Class Hierarchy
─┬ commandbox.system.BaseCommand - Base task for all custom commands
└─┬ commandbox.system.BaseTask - base task for all task runners
└── task - Your custom task runner

25. Task Runner Properties
● wirebox - WireBox injector
● CR - carriage return ( char(10) )
● formatterUtil - Formatter Utility
● fileSystemUtil - File System Utility
● shell - CLI Shell class
● print - Print helper
● logBox - LogBox factory
● logger - LogBox logger named after this CFC
● parser - CLI Parser class
● configService - Config Setting Service
● SystemSettings - System Setting helper
● job - Interactive Job
● thisThread - A reference to the current running java.lang.Thread
● asyncManager - WireBox's AsyncManager class

26. Task Runner Methods
// Returns the AsyncManager class
async()
// Convenience method for getting stuff from WireBox
getInstance( name, dsl, initArguments={}, targetObject='' )
// Retuns current exit code
getExitCode()
// Sets exit code to be returned when task completes
setExitCode( required numeric exitCode )
// Returns the current working directory of the shell
getCWD()
// ask the user a question and wait for response
ask( message, string mask='', string defaultResponse='', keepHistory=false, highlight=true, complete=false )
// Wait until the user's next keystroke amd return the char code
waitForKey( message='' )
// Ask the user a question looking for a yes/no response and return a boolean
confirm( required message )

27. Task Runner Methods
// Intiator for multiselect DSL. (Check "task interactiviy" page in docs)
multiSelect()
// Run another command by name.
runCommand( required command, returnOutput=false )
// Intiator for Command DSL. (Check "running other commands" page in docs)
command( required name )
// Intiator for directory watcher DSL. (Check "Watchers" page in docs)
watch()
// This resolves an absolute or relative path using the rules of the operating system and CLI.
resolvePath( required string path, basePath=shell.pwd() )
// Intiator for globber DSL (check "Using file globs" page in docs)
globber( pattern='' )
// Intiator for PropertyFile DSL (check "property files" page in docs)
propertyFile( propertyFilePath='' )
// Report error in your task. Raises an exception that will not print the stack trace
error( required message, detail='', clearPrintBuffer=false, exitCode=1 )

28. Task Runner Methods
// Returns true if current exit code is not 0.
hasError()
// Open a file or folder externally in the default editor for the user.
openPath( path )
// Open a URL in the user's browser
openURL( theURL, browser='' )
// Set a CommandBox environment variable
setSystemSetting( required string key, string value )
// Retrieve a Java System property or env value by name.
getSystemSetting( required string key, defaultValue )
// Retrieve a Java System property by name.
getSystemProperty( required string key, defaultValue )
// Retrieve an env value by name.
getEnv( required string key, defaultValue )

29. Task Runner Methods
// Call this method periodically in a long-running task to check and see
// if the user has hit Ctrl-C. This method will throw an UserInterruptException
// which you should not catch. It will unroll the stack all the way back to the shell
checkInterrupted( thisThread=variables.thisThread )
// Loads up Java classes into the class loader that loaded the CLI for immediate use.
// (Check "Loading Ad hoc Jars" page in docs)
classLoad( paths )
// Get the current java.lang.Thread object
getCurrentThread()
// Get the current thread name
getThreadName()

30. Task Runner Output
● Use “print” helper
● Chain methods
● Method names are dynamic
print.line( 'I like Spam.' );
print.line();
print.redLine( "..." );
print.blueText( "..." );

31. Task Runner Output
print
.redOnWhiteLine( 'test' )
.boldRedOnBlueText( 'test2' )
.boldBlinkingUnderscoredBlueTextOnRedBackground('test3')
.line()
.line()
.indentedLine( 'processing...' )
.toConsole();

32. Task Runner Output
print.table(
headerNames = [ 'First Name', 'Last Name' ],
data = [
[ 'Brad', 'Wood' ],
[ 'Luis', 'Majano' ],
[ 'Gavin', 'Pickin' ]
]
);

33. Task Runner Output
print.tree( [
'Ortus Solutions' : [
'Products' : [
'Open Source' : {
'ColdBox MVC' : {},
'CommandBox CLI' : {},
'ContentBox CMS' : {}
},
'Commercial' : {
'ForgeBox Pro' : {},
'CommandBox Pro' : {},
'TimeBox BMP' : {}
}
],
'Services' : {
'Consulting' : {
'Ad-Hoc hours' : {},
'Hourly Retainer' : {},
'Custom' : {}
},
'Training' : {},
'Design' : {}
}
]
] );

34. Task Runner Output
└─┬ Ortus Solutions
├─┬ Products
│ ├─┬ Open Source
│ │ ├── CommandBox CLI
│ │ ├── ContentBox CMS
│ │ └── ColdBox MVC
│ └─┬ Commercial
│ ├── ForgeBox Pro
│ ├── TimeBox BMP
│ └── CommandBox Pro
└─┬ Services
├── Training
├── Design
└─┬ Consulting
├── Hourly Retainer
├── Ad-Hoc hours
└── Custom

35. Task Runner Interactivity
var color = ask( 'Enter favorite color: ' );
if( confirm( 'Do you agree? [y/n]' ) ) {
// Do something if yes
}
// ASCII code for key
var char = waitForKey( 'Press any key.' );

36. Task Runner Interactivity
var color = multiselect( 'What is your favorite color? ' )
.options( 'Red,Green,Blue' )
.ask();

37. Task Runner Interactivity
var colorArray = multiselect( 'What is your favorite color? ' )
.options( [
{ display='Red', value='r', selected=true },
{ display='Green', value='g' },
{ display='Blue', value='b' }
] )
.multiple()
.required()
.ask();

38. Task Runner Shell Integration
getCWD() // current working directory
shell.clearScreen()
shell.getTermWidth() // In characters
shell.getTermHeight() // In characters

39. Run Other Commands
command( 'version' )
.run();

40. Run Other Commands
command( ... )
.params( ... )
.flags( ... )
.append( ... )
.overwrite( ... )
.inWorkingDirectory( 'C:/' )
.pipe( command( ... ) )
.run( ... );

41. Run Other Commands
command( 'cp' )
.params( '/my/path', '/my/new/path' )
.run();
command( "install" )
.params( 'coldbox' )
.flags( 'force', '!save' )
.run();

42. Run Other Commands
command( 'run' )
.params( 'java -version' )
.run();

43. Running other Tasks
// Call “run” target of “task.cfc”
task().run();
// Call “compile” method on “build.cfc”
task( 'build' )
.target( 'compile' )
.run();
// Call “run” method on “mytask.cfc”, passing in args
task( 'mytask' )
.params( path='/my/path', newPath='/my/new/path' )
.run();

44. Downloading Files
property name="progressableDownloader" inject="ProgressableDownloader";
property name="progressBar" inject="ProgressBar";
...
progressableDownloader.download(
'http://site.com/fileToDownload.zip',
'C:/path/to/fileWeDownloaded.zip',
// This callback fires every 1024K of downloaded bytes
function( status ) {
progressBar.update( argumentCollection = status );
}
);

45. Erroring Out
error( "I don't like your tone of voice" );
error(
message="We could not fufill your order",
detail="The ice cream machine is down (again)",
exitCode=666
);

46. Directory Watchers
watch()
.paths( '**.cfc' )
.inDirectory( getCWD() )
.withDelay( 5000 )
.onChange( ()=>{
print.line( 'Something changed!' );
command( 'testbox run' )
.run();
} )
.start();

47. Access Database
ds = {
class: 'org.gjt.mm.mysql.Driver',
connectionString: 'jdbc:mysql://localhost:3306/bradwood',
username: 'root',
password: 'myPass'
};
var qry = queryExecute(
sql='select * from role',
options={ datasource : ds }
);

48. Create datasource on the fly
dsources = getApplicationSettings().datasources;
dsources[ 'myNewDS' ] = {
class: 'com.microsoft.jdbc.sqlserver.SQLServerDriver',
connectionString: 'jdbc:sqlserver://host:1433;DATABASENAME=dbname',
username:'username',
password:'pwd'
};
application action='update' datasources=dsources;

49. Lifecycle Events
● preTask - Before any target in the task
● postTask - After any target in the task
● aroundTask - Wraps execution of any target in the task
● pre<targetName> - Before a specific target (Ex: preRun)
● post<targetName> - After a specific target (Ex: postRun)
● around<targetName> - Wraps execution of a specific target (Ex:
aroundRun)
● onComplete - Fires regardless of exit status
● onSuccess - Fires when task runs without failing exit code or exception
● onFail - Fires if exit code is failing after the action is done.
● onError - fires only if an unhandled exception is thrown and receives
exception object.
● onCancel - Fires when the task is interrupted with Ctrl-C

50. Lifecycle Events
component {
function preTask() {
// Some setup here
}
function run() {
print.line( 'Target is running' );
}
function onComplete() {
// Some cleanup here
}
function onFail(){
log.error( 'There was an issue!' )
}
}

51. Interactive Jobs
● Creates organized output on page when completing
several job steps
● Allows for debug logging which is hidden on
successful execution, but visible when erroring
● Works well with progress bars
● Allows tracking nested operations
● You’re used to seeing this in the output of “server
start” and “install”

52. Interactive Jobs
job.start( 'This is my job to run' );
job.addLog( 'Still going...' );
job.addLog( "Now we're getting somewhere." );
job.addLog( 'Almost done!' );
job.complete();

53. Interactive Jobs
job.start( 'Starting server' );
job.addLog( 'This is the server name' );
job.addWarnLog( "Hey, don't touch that dial" );
job.start( 'Installing CF Engine first' );
job.addLog( 'This was the version used' );
job.addLog( "Yeah, we're done" );
job.complete();
job.addLog( "Aaand, we're back!." );
job.addErrorLog( "I think we're going to crash" );
job.error( "Didn't see that coming" );

54. Property Files
// Create and load property file object
propertyFile( 'myFile.properties' )
.set( 'my.new.property', 'my value' )
.store();
// Get a property
var value = propertyFile( 'myFile.properties' )
.get( 'existing.property' );
// Create one from scratch
propertyFile()
.set( 'brad', 'wood' )
.store( 'myFile.properties' );

55. Loading *box Modules
loadModule( 'build/modules/myUtils' );
var thingFromModule = getInstance( 'thing@myUtils' );

56. Thank You
● Brad Wood
● brad@bradwood.com
● Codersrevolution.com
● commandbox.ortusbooks.com
● www.ortussolutions.com/products/commandbox