Running BoxLang

BoxLang and the Multiverse!

Please check out our installation page to make sure you install the right runtime you want to deploy on. We are assuming you have it installed and boxlang and boxlang-miniserver are in your machine's path.

The script for *nix/Mac is boxlang

The script for Windows is boxlang.bat

BoxLang Home

By default, once you execute a boxlang binary it will look for a BOXLANG_HOME environment variable so it can be used as the home for the OS runtime. If you don't provide one, then by default, it will use the currently logged-in user's home folder + .boxlang

Mac

/Users/username/.boxlang

Linux

/home/username/.boxlang

Windows

c:/Windows/users/myuser/.boxlang

This is important because inside of the home folder, you can have several folders and files by convention that will be used for the runtime execution.

Please note that each runtime can have a different location for the BoxLang home. So make sure you read each of the runtime's docs to see where each goes.

Folder/FIle	Description
/classes	Where all the compiled classes will be stored
/config	Where configuration files are stored for the runtime
/config/boxlang.json	The runtime configuration file. Here is where you can configure all the settings, caches, datasources, compiler information, and so much more.
/global	Where global BoxLang classes and component templates can be stored for the entire runtime
/lib	You can place any *.jar files here, and they will be loaded into the runtime at startup. This is a great place to put third-party jars that will be available at runtime.
/logs	All log files will be stored here
/modules	Here is where the BoxLang modules are installed and will be available for the entire operating system binary.
version.properties	The version information of the installed runtime.

Start the REPL

The first thing you can do is start up the BoxLang REPL, make sure the insaller has added your installation directory to the PATH system variable.

Mac/*nix

boxlang

Windows

boxlang.bat

Jar

java -jar path/to/boxlang-1.0.0.jar

You can run one-off expressions from the REPL like so:

Enter an expression, then hit enter.
Press Ctrl-C to exit.

BoxLang> 2+2
4

BoxLang> dateFormat( now(), "full" )
Wednesday, March 13, 2024

BoxLang> "brad".ucase().reverse()
DARB

BoxLang> a=3
3

BoxLang> b=5
5

BoxLang> a*b
15

BoxLang> ["luis","gavin","jorge"].map( name->name.ucFirst() )
[Luis, Gavin, Jorge]

Press Ctrl-C to exit the REPL or type exit or quit

Please note that the REPL remembers state, so you can use the variables you declare and build a mini-program with it.

Executing a File

You can also use the boxlang binary to execute BoxLang or even CFML code. You can pass a second argument to the binary and it can be a relative (to the current directory you are on) or an absolute path to a file that you wish to execute.

Allowed files are:

• *.bx - A BoxLang class with a main( args=[] ) method

• *.bxs - A BoxLang script file

• *.bxm - A Boxlang markup template file

If you are using the bx-compat-cfml module for CFML Support:

• *.cfs - A CFML script file

• *.cfm - A CFML markup template file

Modify the same command you run above to execute the REPL but add a file path to the end. It can be absolute or relative to the current working directory.

Mac / *Unix

boxlang task.bx
boxlang myscript.bxs
boxlang mytemplate.bxm

boxlang /full/path/to/test.bxs
boxlang /full/path/to/Task.bx

Windows

boxlang.bat task.bx
boxlang.bat myscript.bxs
boxlang.bat mytemplate.bxm

Jar

java -jar boxlang-1.0.0.jar task.bx
java -jar boxlang-1.0.0.jar /full/path/to/test.bxs

Producing Output

As you navigate all the built-in functions and capabilities of BoxLang, let's learn how to produce output to the system console.

• printLn() - Print with a line break

• print() - Print with no line break

• writeOutput() - Writes to the output buffer (Each runtime decides what it's buffer is. The CLI is the system output, the Web is the HTML response buffer, etc)

println( "Time is #now()#" )

I get the output:

╰─ boxlang test.bxs
Time is {ts '2024-05-22 22:09:56'}

Hooray! You have executed your first script using BoxLang. Now let's build a class with a main( args=[] ) convention. This is simliar to Java or Groovy.

class{

        function main( args=[] ){

                println( "Task called with " & arguments.toString() )

        }

}

You can now call it with zero or more arguments!

╰─ boxlang Task.bx
Task called with {ARGS=[]}

╰─ boxlang Task.bx boxlang rocks
Task called with {ARGS=[boxlang, rocks]}

One Off Code Execution

So, to give a quiet example of the --bx-code flag here’s running some one-off code.

boxlang --bx-code "2+2"

This assumes script, not templating tags.

Piping code

You can also pipe statements into the BoxLang binary for execution as well. This assumes script, not tags.

echo "2+2" | java -jar boxlang-1.0.0.jar
echo "2+2" | boxlang

or

# on *nix
cat test.cfs | java -jar boxlang-1.0.0.jar
cat test.cfs | boxlang

# on Windows
type test.cfs | java -jar boxlang-1.0.0.jar
type test.cfs | boxlang.bat

Command Line Arguments

If you interact with the boxlang binary then you will be executing the BoxRunner class in BoxLang. You can use several options and positional arguments to our runtime. Let's explore them.

Options

• --bx-code "code here"—This is used to pass ad-hoc code to execute. Provide code in the next argument, quoted.

• --bx-config - Pass a path to a JSON file for BoxLang configuration. See Runtime Configuration for more information.

• --bx-debug - Enable debug mode (more debug logs!)

• --bx-home - Pass a path to a custom runtime home directory for storing modules, configuration, and more. See Runtime Home Directory for more information.

• --bx-printAST - Prints out BoxLang AST in JSON format for code provided via the -c flag (for debugging)

• --bx-transpile - Prints out transpiled Java source that would be compiled to create the bytecode for the passed template path. (for debugging)

• --version - Output the current runtime's version information

Positionals

• script_path | class_path - The template, class, or script to execute

  • If it's a class, it must have a main( args ) method.

• module:{name} - The executable module to execute. This will execute a Modules' ModuleConfig.main( args ) method.

• {actionCommand: compile,featureAudit, cftranspile} - If you send any of those action commands, we will execute those CLI tools

Using 3rd Party Jars

You can load custom third-party JARs at runtime by adding all your *.jar to the BOXLANG_HOME/lib folder. This will be loaded at runtime and available to use and integrate.

Environment Variables

The boxlang binary will also scan for several environment variables as overrides to the execution process.

Env Variable	Purpose
BOXLANG_CONFIG = PATH	Override the boxlang.json
BOXLANG_DEBUG = BOOLEAN	Enable or disable debug mode
BOXLANG_HOME = DIRECTORY	Override the HOME directory
BOXLANG_PRINTAST = BOOLEAN	Print the AST
BOXLANG_TRANSPILE = BOOLEAN	Tranpile the code

In addition to core runtime OS-level settings, you can also use the environment or Java properties to adjust granular configuration setting. For more see the Runtime Configuration section.