Skip to content

Latest commit

 

History

History
271 lines (193 loc) · 9.11 KB

README.md

File metadata and controls

271 lines (193 loc) · 9.11 KB
icon description
plug-circle-bolt
BoxLang and the Multiverse!

Running BoxLang

{% hint style="warning" %} 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. {% endhint %}

{% hint style="info" %} The script for *nix/Mac is boxlang

The script for Windows is boxlang.bat {% endhint %}

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

{% tabs %} {% tab title="Mac" %}

/Users/username/.boxlang

{% endtab %}

{% tab title="Linux" %}

/home/username/.boxlang

{% endtab %}

{% tab title="Windows" %}

c:/Windows/users/myuser/.boxlang

{% endtab %} {% endtabs %}

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.

{% hint style="danger" %} 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. {% endhint %}

Folder/FIleDescription
/classesWhere all the compiled classes will be stored
/configWhere configuration files are stored for the runtime
/config/boxlang.jsonThe runtime configuration file. Here is where you can configure all the settings, caches, datasources, compiler information, and so much more.
/globalWhere global BoxLang classes and component templates can be stored for the entire runtime
/libYou 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.
/logsAll log files will be stored here
/modulesHere is where the BoxLang modules are installed and will be available for the entire operating system binary.
version.propertiesThe 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.

{% tabs %} {% tab title="Mac/*nix" %}

boxlang

{% endtab %}

{% tab title="Windows" %}

boxlang.bat

{% endtab %}

{% tab title="Jar" %}

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

{% endtab %} {% endtabs %}

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]

{% hint style="success" %} Press Ctrl-C to exit the REPL or type exit or quit {% endhint %}

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.

{% hint style="info" %} 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 {% endhint %}

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.

{% tabs %} {% tab title="Mac / *Unix" %}

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

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

{% endtab %}

{% tab title="Windows" %}

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

{% endtab %}

{% tab title="Jar" %}

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

{% endtab %} {% endtabs %}

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"

{% hint style="warning" %} This assumes script, not templating tags. {% endhint %}

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-all.jar
echo "2+2" | boxlang

or

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

# on Windows
type test.cfs | java -jar boxlang-1.0.0-all.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

At this point, you are done getting running with BoxLang. It's now your turn to write some code and get it running.