1 of 100

BoxLang v1.x

Introduction

Welcome to BoxLang: A Modern Dynamic JVM Language

BoxLang is a modern dynamic JVM language that can be deployed on multiple runtimes: operating system (Windows/Mac/*nix/Embedded), web server, lambda, iOS, android, web assembly, and more. BoxLang combines many features from different programming languages, including Java, CFML, Python, Ruby, Go, and PHP, to provide developers with a modern, functional and expressive syntax.

BoxLang has been designed to be a highly adaptable and dynamic language to take advantage of all the modern features of the JVM and was designed with several goals in mind:

Be a rapid application development (RAD) scripting language and middleware.
Unstagnate the dynamic language ecosystem in Java.
Be dynamic, modular, lightweight, and fast.
Be 100% interoperable with Java.
Be modern, functional, and fluent (Think mixing CFML, Node, Kotlin, Java, and Clojure)
Extend via Modules
Be able to support multiple runtime environments:
1. Native OS Binaries (CLI Tooling, compilers, etc.)
2. Serverless Computing (AWS Lambda, Azure Functions, etc)
3. Servlet Containers - CommandBox/Tomcat/Jetty/JBoss/Undertow
4. Docker Containers
5. Android/iOS Devices
6. Web assembly
7. Etc
Compile down to Java ByteCode
Framework Capabilities (Scheduling, applications, events, async computing, tasks, queues, modules)
Drop-in Replacement for Adobe ColdFusion and Lucee CFML

BoxLang can also be used as a drop-in replacement for Adobe ColdFusion or Lucee CFML Engines by leveraging our bx-compat-cfmlmodule. NO CODE CHANGES, FASTER, MODERN AND SAVE MONEY.

Launch Video

License

BoxLang Subscriptions

Business Support with SLAs
Enhanced builds
Custom patches and builds
Dedicated Engineer
Premium Modules
Much More...

Support Open Source

Discussions & Help

Reporting a Bug

Jira Issue Tracking

Resources

Ortus Solutions, Corp

Release History

All the major information about BoxLang Releases

Versioning Schema

And constructed with the following guidelines:

Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bump the minor (and resets the patch)
Bug fixes and misc changes bump the patch

LTS - Support Policy

For all BoxLang releases, updates are provided for 12 months, and security fixes are provided for 2 years after the next major release.

Releases

In this section, you will find the release notes and links for each version's documentation once we reach a stable release. For now, you can see all the different beta releases on the left hand navigation under Release History.

1.0.0-RC.3

April 3, 2025

We are so excited to release RC.3 for BoxLang. We have squashed almost 100 tickets for this release. Making it the most performant and solid release to date. We do not have any more release candidates scheduled, so this might be the last before our final release on May 1st. So please, please test your applications and report any issues.

Below, you can find some of the significant accomplishments of this release and the full release notes.

Performance

We have tested the runtime against all our major libraries, ColdBox, TestBox, and ContentBox, and included our major ColdBox modules. BoxLang now officially runs all of our test suites faster than Adobe 2021, 2023, and 2025, with a give-or-take with the Lucee CFML engine.

BXORM

install-bx-module bx-orm

Virtual Threads

We have finalized our core executors in BoxLang and fully integrated Java Virtual threads so you can use them in your applications. The core executors in BoxLang now are:

"executors": {
	// Use this for IO bound tasks, does not support scheduling
	// This is also the default executor for parallel operations
	// This is also the default when requestion an executor service via executorGet()
	"io-tasks": {
		"type": "virtual"
	},
	// Use this for CPU bound tasks, supports scheduling
	"cpu-tasks": {
		"type": "scheduled",
		"threads": 10
	},
	// Used for all scheduled tasks in the runtime
	"scheduled-tasks": {
		"type": "scheduled",
		"threads": 10
	}
},

As you can see, we have 3 executors pre-defined for the runtime:

io-tasks- A virtual thread executor for high I/O intensive tasks
cpu-tasks- A scheduled executor with 10 base threads for your CPU-intensive tasks
scheduled-tasks- A dedicated executor with 10 base threads for scheduling

This now allows us to create Java-based virtual threads using BoxLang constructs threadNew()BIF or the threadcomponent:

threadNew( 
  runnable: () => {},
  virtual: true
)

bx:thread name="virtualTest" virtual=true{
  // A virtual thread.
}

The default for parallel executions in map(), filter(), each()have also been updated to leverage virtual threads by default. You can use the virtual = falseso they can execute in the cpu-tasksexecutor if needed. Enjoy the power of virtual threads.

Schedulers

We now can do schedulers in pure BoxLang. This allows us to integrate it into every corner of the runtime. All the docs for scheduling are coming. Here is a sneak peek of a pure BoxLang scheduler:

class {

	// Properties
	property name="scheduler";
	property name="runtime";
	property name="logger";
	property name="asyncService";
	property name="cacheService";
	property name="interceptorService";

	/**
	 * The configure method is called by the BoxLang runtime
	 * to allow the scheduler to configure itself.
	 *
	 * This is where you define your tasks and setup global configuration.
	 */
	function configure(){
		// Setup Scheduler Properties
		scheduler.setSchedulerName( "My-Scheduler" )
		scheduler.setTimezone( "UTC" )

		// Define a lambda task
		scheduler.task( "My test Task" )
			.call( () -> {
				println( "I am a lambda task: #now()#" );
			} )
			.every( 2, "second" );
	}

	/**
	 * --------------------------------------------------------------------------
	 * Life - Cycle Callbacks
	 * --------------------------------------------------------------------------
	 */

	/**
	 * Called after the scheduler has registered all schedules
	 */
	void function onStartup(){
		println( "I have started!" & scheduler.getSchedulerName() );
	}

	/**
	 * Called before the scheduler is going to be shutdown
	 */
	void function onShutdown(){
		println( "I have shutdown!" & scheduler.getSchedulerName() );
	}

	/**
	 * Called whenever ANY task fails
	 *
	 * @task      The task that got executed
	 * @exception The exception object
	 */
	function onAnyTaskError( task, exception ){
		println( "Any task [#task.getName()#]  blew up " & exception.getMessage() );
	}

	/**
	 * Called whenever ANY task succeeds
	 *
	 * @task   The task that got executed
	 * @result The result (if any) that the task produced as an Optional
	 */
	function onAnyTaskSuccess( task, result ){
		println( "on any task success [#task.getName()#]"  );
		println( "results for task are: " & result.orElse( "No result" ) );
	}

	/**
	 * Called before ANY task runs
	 *
	 * @task The task about to be executed
	 */
	function beforeAnyTask( task ){
		println( "before any task [#task.getName()#]"  );
	}

	/**
	 * Called after ANY task runs
	 *
	 * @task   The task that got executed
	 * @result The result (if any) that the task produced as an Optional
	 */
	function afterAnyTask( task, result ){
		println( "after any task completed [#task.getName()#]"  );
		println( "results for task are: " & result.orElse( "No result" ) );
	}

}

CLI Scheduler

You can now run schedulers from the CLI in any operating system using our new boxlang schedulecommand. Just tell it which scheduler to spin up and forget about CRON.

boxlang schedule MyScheduler.bx

This will spawn our scheduled tasks, run your scheduler, and wait until you manually block it; if not, it runs forever.

Runtime Schedulers & Configuration

You can also now declare schedulers in your boxlang.jsonthat once the runtime starts, it will startup your schedulers.

"scheduler": {
    // The default scheduler for all scheduled tasks
    // Each scheduler can have a different executor if needed
    "executor": "scheduled-tasks",
    // The cache to leverage for server fixation or distribution
    "cacheName": "default",
    // An array of BoxLang Schedulers to register upon startup
    // Must be an absolute path to the scheduler file
    // You can use the ${user-dir} or ${boxlang-home} variables or any other environment variable
    // Example: "schedulers": [ "/path/to/Scheduler.bx" ]
    "schedulers": [],
    // You can also define tasks manually here
    // Every task is an object defined by a unique name
    // The task object is a struct with the following properties:
    // - `crontime:string` - The cron time to run the task (optional), defaults to empty string
    // - `eventhandler:path` - The absolute path to the task event handler(optional), defaults to empty string
    // - `exclude:any` - Comma-separated list of dates or date range (d1 to d2) on which to not execute the scheduled task
    // - `file:name` - Name of the log file to store output of the task (optional), defaults to `scheduler`
    // - `group:string` - The group name of the task (optional), defaults to empty string
    "tasks": {}
},

You can now also choose the default executor and cache to use for server fixations. The schedulersis an array of absolute paths to your scheduler bx classes to load.

Application.bx Schedulers

You can also define schedulers for your particular applications using the Application.bxfile and the this.schedulerssetting.

class{

    ...
    
    this.schedulers = [ "path.to.Scheduler" ]

}

As you can see, the value is an array of instantiation paths. At application startup, the schedulers will be created, registered, and started for you.

Scheduler BIFs

You also now have a collection of new BIFs to interact with your schedulers and even submit schedulers programmatically.

SchedulerStart( path, [force=false] ) - Create, register and start a new scheduler class.
SchedulerShutdown( name, [force=false], [timeout=0] ) - Shutdown a scheduler
SchedulerRestart( name, [force=false], [timeout=0] ) - Restart a scheduler
SchedulerStats( [name] ) - Get a strut of stats of one or all registered schedulers
SchedulerList() - Get an array of names of all schedulers
SchedulerGet( name ) - Get a scheduler instance by name
SchedulerGetAll() - Get all the registered schedulers

Release Notes

Improvements

Bugs

1.0.0-RC.1

February 18, 2025

🚀 BoxLang Release Candidate 1 is Here! 🚀

After nearly a year of relentless iteration, rigorous testing, blood, sweat, lots of praying, tears, and over 1,000 resolved tickets, we proudly announce the first Release Candidate (RC1) of BoxLang! With 27 beta versions behind us, we are now on the final stretch toward the official 1.0 release.

This milestone ensures that most of our libraries are fully compatible and certified for BoxLang, making it production-ready. RC1 delivers significant bug fixes, performance optimizations, and stability enhancements, enabling teams to deploy and fine-tune their applications in real-world environments confidently. We strongly encourage the community to start running production workloads now—your feedback will be instrumental in refining BoxLang ahead of the final release.

Licenses Available TODAY!

Production Tips

Release Notes

New Features

Improvement

Bugs

Beta Stage

This is the collection of Betas we released since our first version.

1.0.0-Beta27

January 31, 2025

This release brings enhanced XML handling, new CLI app support, improved error handling, and expanded interoperability with Java and CFML runtimes. We've also added new HTTP event hooks, improved caching strategies, and a streamlined class resolution process to make your applications more performant, even in debug modes.

🌟 Highlights:

✅ Enhanced XML Support – Improved cloning, merging, and namespace handling in XML operations. ✅ Unified Template & Script Grammars – BoxLang now seamlessly integrates both styles, bringing performance updates to the parser. ✅ Improved Java Interop – Automatic coercion of BoxLang arrays to native Java arrays and varargs support ✅ Better Error Handling – More robust dump rendering and exception management. ✅ New CLI Features – Built-in functions like cliRead(), cliGetArgs(), and cliExit() for pure CLI apps. ✅ Improved HTTP Handling – Proxy support, authentication, and new request/response events.

✅ Trusted Cache – Trusted cache is in the house, to get high performance in production

✅ Class location caches – More performance updates for class resolutions for BoxLang classes

With over 40 improvements, new features, and fixes, this release makes BoxLang even more powerful and stable! 🔥

Improvements

New Features

Bugs

1.0.0-Beta26

January 14, 2025

BoxLang Beta 26 Has Landed!

We’re thrilled to announce the release of BoxLang 1.0.0 Beta 26, a monumental update that takes performance and functionality to the next level. This beta officially certifies the ColdBox HMVC Framework to run on BoxLang, marking a significant milestone in compatibility. Not only can you now run all ColdBox applications seamlessly on BoxLang, but with the latest ColdBox snapshot, you can also build your entire applications in BoxLang, unlocking the full potential of this dynamic and expressive language for modern application development.

This release also introduces blazing-fast Query of Queries (QoQ) support, delivering speeds up to 70 times faster than Adobe or Lucee in specific scenarios, along with exciting new features like list parameter support in JDBC queries and custom QoQ functions. Over 70 bugs have been resolved, and significant improvements have been made, such as enhanced debugging capabilities, refined Box Script syntax, and robust session and metadata handling. With Beta 26, BoxLang continues to push the boundaries, empowering developers to build robust, efficient, and fully modern JVM-based applications.

Welcome to what could be our last beta before the final release of our initial 1.0.0 version of BoxLang and its multi-runtimes.

New Features

Improvements

Bugs

Task

Stories

1.0.0-Beta24

December 2, 2024

Introducing BoxLang 1.0.0 Beta 24!

We’re excited to announce the release of Beta 24, packed with powerful new features, essential bug fixes, and impactful improvements that enhance performance and security. This release brings more robust logging capabilities, enhanced configuration flexibility, and new query-handling methods to streamline your development experience. We’ve also squashed several parsing bugs, ensuring smoother code execution.

Whether you’re optimizing your runtime with custom logging encoders or leveraging the new queryColumnList for seamless data manipulation, Beta 24 is designed to empower developers with a more secure, customizable, and efficient development environment.

🐞 Bug Fixes

• BL-797: Parsing issue fixed when using a < symbol before a tag. No more parsing hiccups!

• BL-798: = sign after an if tag? No problem now! Fixed to handle this scenario smoothly.

• BL-799: Parentheses confusion resolved! Opening parentheses (afterword operators will no longer be mistaken for function calls.

• BL-800: Environmental safety improved: BOXLANG_DEBUG will now be parsed only if non-null to prevent unexpected behavior.

✨ New Features

Improved Logging

BoxLang's logging features have been completely revamped in preparation for its stable release. You also have fine-grain control over them, and module developers will be able to register and leverage custom loggers and appenders.

Please note that the logsDirectory setting has been moved from the root of the boxlang.json to the new logging section.

Check out the new configuration:

JSON Anyone?

• BL-792: Introducing CFConfig support and named loggers for more precise control over your logging setup!

• BL-793: Added the ability to configure logging items, giving you more flexibility in managing your logs.

• BL-803: Choose your logging format! You can now select text and JSON logging encoders for better runtime output customization.

📈 Improvements

• BL-782: Refined the LoggingService to encapsulate all logging characteristics, streamlining log management.

• BL-783: Strengthened security by disabling absolute path logging and prohibiting custom log extensions. Your logs are safer now!

• BL-785: Upgraded logging to follow ISO8601 date/time format and threading standards for more standardized logs.

• BL-786: Replaced FileAppender with RollingFileAppender to better handle large log files through automatic rotation.

• BL-795: Introduced queryColumnList BIF and a columnList() member method for easier Query column management.

• BL-804: Enhanced support for customTagPaths in Application.cfc/bx, expanding customization capabilities.

1.0.0-Beta22

The BoxLang 1.0.0-Beta22 release includes several improvements, bug fixes, new features, and stories. Key improvements include enhanced redirection for the Miniserver, better transactional event broadcasting, and added convenience methods like getRequestContext() and getApplicationContext(). Bug fixes address issues such as JSON deserialization, whitespace management, and various errors related to data types and loops. New features include support for multiple statements inside queries and a new datasourceRegister() BIF for easier SaaS integrations.

Release Notes

New Features

Improvement

Bug

1.0.0-Beta21

October 25th, 2024

This release brings another round of powerful tools and refinements to the BoxLang community, making development more dynamic and robust than ever. We’ve added new capabilities for debugging and tracing, expanded context-sensitive controls for thread management, and introduced new methods for fluent attachment handling.

For deeper flexibility, our improvements enhance configurability, streamline session control, and add deeper levels of JSON serialization management. Plus, we’ve squashed a wide range of bugs, enhancing stability across database connections, date handling, and runtime compatibility with CFML.

New Feature

Improvement

Bug

1.0.0-Beta20

October 25th, 2024

🚀 Introducing BoxLang 1.0.0 Beta 20! 🚀

New Feature

Improvements

Bugs

1.0.0-Beta19

October 18th, 2024

Welcome to the latest release of BoxLang, where innovation takes center stage with groundbreaking enhancements and features designed to elevate your development experience. With the introduction of the ASMBoxPiler, we're pioneering a direct pathway to converting BoxLang code into highly optimized Java bytecode, offering an unprecedented boost in performance and efficiency. By eliminating traditional bottlenecks, we're empowering developers to achieve seamless integration with Java environments, transforming the way applications are built and executed. Prepare to explore the full potential of your projects with this transformative update!

New Features

With the implementation of the ASMBoxPiler, developers can now compile BoxLang source code directly into Java bytecode, streamlining the process and improving performance by over 4 times. This feature eliminates the intermediate steps previously required for code execution, resulting in faster compilation times and seamless integration with Java environments.

The JavaBoxPiler will remain in BoxLang as it's an integral debugging piece. It might be moved later to it's own module, but having the capability to transpile BoxLang/CFML code to Java will remain.

The direct bytecode generation allows for enhanced optimization and leverages the full potential of Java's JVM, leading to more efficient and scalable applications. By default, right now this is an experimental feature and it will need to be turned ON in order to use it via our boxlang.json configuration, via the compiler : "asm"

You can now use * imports for BoxLang classes, which allows you to bring in all the classes found in the imported package into the class namespace so you can create them by just using their name. In practice, the use of star-imports is a trade-off between convenience and potential issues such as namespace collisions. While they can make code more concise, especially when many classes from a package are needed, they may also import unintended classes, leading to ambiguities. Therefore, it's generally recommended to use specific imports when only a few classes are required and reserve star-imports for when numerous classes from the same package are genuinely required.

The @ notation in BoxLang’s import system allows for more efficient and precise class referencing. By explicitly addressing classes from a specific module, performance is improved because it avoids the need for BoxLang to search through all available modules, reducing ambiguity in cases where classes with the same name exist in different modules. The module’s root serves as the base for addressing the class.

Here’s a breakdown of how it works:

By using this method, developers can avoid potential issues like performance degradation due to unnecessary module scanning and the possibility of naming conflicts. It provides a clear and concise way to manage dependencies and class imports in BoxLang.

Just like with BoxLang classes, you can also do the same for all Java libraries modules are packaged with. This allows you to import and create Java classes from specific modules by addressing them using the @ notation.

The following were support tickets for all of these functionalities

If you want to capture AST JSON for debugging purposes you will need to activate the new AST experimental flag:

We continue to make great strides with easy websocket support for BoxLang. Now we have added our very own STOMP implementation which makes our websockets behave like AMQP Messaging Brokers like RabbitMQ.

Improvements

Bug

Getting Started

Migrating from Adobe ColdFusion

Migrating From Lucee CFML

BoxLang Language

Data Navigators

Lambdas -> Pure Functions

1.0.0-Beta9

August 9, 2024

BoxLang Betas are released weekly. This is our ninth marker and we are incredibly excited as we are coming close to our stable release. We have some great news in this release!

New Features

PDFs have landed for BoxLang. The full implementation for creating PDF documents is now complete and available via our bx-pdf module. This module contributes the following Components to the language:

document - the wrapping component for creating PDF documents
- The following attributes are available to the document component
  - format - The format of the document to generate. This attribute is unused and will be removed in a future release as only PDF generation is supported. Any other format requested will throw an error.
  - encryption - The encryption level to use for the document. Default is none. Possible values are 128-bit, 40-bit, none
  - localUrl - If true, the document will be generated with local URLs. Default is false
  - variable - The name of the variable to store the generated PDF binary
  - backgroundVisible - If true, the background will be visible. Default is true
  - bookmark - If true, bookmarks will be generated. Default is true
  - htmlBookmark - If true, it is possible to convert outlines to a list of named anchors (<a name="anchor_id">label</a>) or a headings structure ( <h1>... <h6> ). Transforming of HTML hyperlinks to PDF hyperlinks (if not explicitly disabled Hyperlink jumps within the same document are supported as well
  - orientation - The orientation of the document. Default is portrait. Possible values are portrait, landscape
  - scale - The percentage to scale the document. Must be less than 100
  - marginBottom - The bottom margin of the document
  - marginLeft - The left margin of the document
  - marginRight - The right margin of the document
  - marginTop - The top margin of the document
  - pageWidth - The width of the page in inches
  - pageHeight - The height of the page in inches
  - fontEmbed - If true, fonts will be embedded in the document. Default is true
  - fontDirectory - The directory where fonts are located
  - openpassword - The password to open protected documents
  - ownerPassword - The password to access restricted permissions
  - pageType - The type of page to generate. Default is A4.
  - pdfa - If true, the document will be generated as a PDF/A document. Default is false
  - filename - The filename to write the PDF to. If not provided and a variable argument is not provided, the PDF will be written to the browser ( Web-context only )
  - overwrite - If true, the file will be overwritten if it exists. Default is false
  - saveAsName - The name to save the PDF as in the browser
  - src - A full URL or path relative to the web root of the source
  - srcfile - The absolute path to a source file
  - mimeType - The mime type of the source. Default is text/html. Possible values are text/html, text/plain, application/xml, image/jpeg, image/png, image/bmp, image/gif
  - unit - The unit of measurement to use. Default is inches. Possible values are in, cm
- The following attributes are not currently implemented and will throw an error if used
  - permissions - Granular permissability is not yet supported
  - permissionspassword - Granular permissability is not yet supported
  - userPassword - Granular permissability is not yet supported
  - authPassword - Granular permissability is not yet supported
  - authUser - Granular permissability is not yet supported
  - userAgent - HTTP user agent identifier
  - proxyHost - IP address or server name for proxy host
  - proxyPassword - password for the proxy host
  - proxyPort - port of the proxy host
  - proxyUser - user name for the proxy host
  - tagged - yes|no ACF OpenOffice integration not supported
  - formfields - yes|no Form field attributes are not implemented in standard module
  - formsType - FDF|PDF|HTML|XML Form field attributes are not implemented in standard module
documentitem - specifies header, footer, and pagebreaks within a document body or documentsection
- The following attributes are available to the documentitem component
  - type A string which dictates the type of item. Accepted values are pagebreak|header|footer
  - evalAtPrint This attribute is deprecated as all content is evaluated when the body of the tag is processed
documentsection - Divides a PDF document into sections. Used in conjunction with a documentitem component, each section can have unique headers, footers, and page numbers. A page break will always precede a section
- The following attributes are available to the documentsection component
  - marginBottom - The bottom margin of the section in the unit specified in the document component.
  - marginLeft - The left margin of the section in the unit specified in the document component.
  - marginRight - The right margin of the section in the unit specified in the document component.
  - marginTop - The top margin of the section in the unit specified in the document component.
  - mimeType - The mime type of the content. If the content is a file, the mime type is determined by the file extension. If the content is a URL, the mime type is determined by the HTTP response.
  - name - The name of the section. This is used as a bookmark for the section.
  - srcfile - The absolute path of the file to include in the section.
  - src - The URL or path relative to the web root of the content to include in the section.
- The following attributes are not currently implemented and will throw an error if used
  - userAgent - The HTTP user agent identifier to use when fetching the content from a URL.
  - authPassword - The authentication password to use when fetching the content from a URL.
  - authUser - The authentication user name to use when fetching the content from a URL.

Examples

Simple example using tag-based syntax to generate a physical file:

Example using script syntax to create a variable containing the binary contents of the PDF, which is then written to a file

This is a really step forward for BoxLang in providing the ability to serialize and deserialize any BoxLang type and any BoxLang class to binary recursively n-levels deep. We have introduced two BIFS to accomplish this:

objectSerialize( object, [filepath] ) : binary
objectDeserialize( input ) : object

You can pass ANY object to the serialize function and it will recursively try to serialize the object to binary data. You can then store that in a database, cluster, cache, or a file using the filepath argument. To deserialize you can use the objectDeserialize() function and you can pass in the direct binary or a file path location for the binary.

The only requirement is that the object be a BoxLang type or any Java type that implements serializable.

Also note that for CFML compatibility, the compat module will expose them as objectLoad() and objectSave().

You can now exit the BoxLang REPL by typing quit or exit.

This was related to BL-110 but specifically to BoxLang classes. This allows us now to be able to take the state of any BoxLang class and be able to serialize it to binary. You can then deserialize the binary and inflate it back to a BoxLang object graph again.

The boxlang.json get's a new top level configuration key: experimental which will be a feature flags approach to turn on/off experimental features in BoxLang.

We have consolidated our CLI tooling to all funnel through the boxlang binary script or boxlang.bat for windows. You can now execute our CLI tools via action commands which is based on the following keys:

compile - Executes the BoxLang compiler tool
cftranspile - Executes the CF to BoxLang transpile tool
featureAudit - Executes the feature audit tool

Improvements

The BoxLang Cache BIFs have been renamed to be standardized to the following:

cache( [provider:default] )
cacheFilter()
cacheNames()
cacheProviders()
cacheService()

This introduces BigDecimal usage all over BoxLang for two main use cases:

Being able to store and process very large numbers that wouldn't fit inside a Long or a Double like 111111111111111111111111111 + 222222222222222222222222222
Being able to retain precision for decimals-- even small ones. For ex: (0.1 + 0.2).toString() outputs 0.30000000000000004 in Lucee 5 and ACF 2023. But in Lucee 6 and BoxLang, it correctly returns .3 without any special work

Not ALL numbers are a BigDecimal-- just the ones that need to be:

integer literals in your source code less than 11 chars will be a java Integer
integer literals in your source code less than 20 chars will be a java Long
All other integer literals in your source will be a java BigDecimal
All decimal literals in your source will be a java BigDecimal

Furthermore, we have added a new NumberCaster which we should be using as our primary caster that returns an instance implementing the Number interface in Java

any recognizable classes like int, long, double, big decimal, etc are just returned directly
Any strings which contain integers (no decimal or sci notation) follow the same rules above (integer for small ones, long for bigger ones, big decimal for really big ones)
Any strings with a decimal or sci notation will be made a BigDecimal

Basically, we return the "Smallest" data type we can without losing any precision. (An Integer is about 24 Bytes and a BigDecimal is about 64 Bytes so it seemed worth optimizing a bit)

The web runtimes now have file uploading capabiltiies finalized.

Bugs

1.0.0-Beta2

June 21, 2024

BoxLang Betas are released weekly. This is our second beta marker. Here are the release notes.

Bug

New Features

This will collaborate several new BIFs and components:

ArgonHash: Returns a secure input hash of the given string using the Argon2 hashing algorithm. ( Alias: GenerateArgon2Hash )
ArgonVerify: Performs a Argon2 verification on the given string against the hashed value. ( Alias: Argon2CheckHash )
BCryptHash: Returns a secure input hash of the given string using the BCrypt hashing algorithm.( Alias: GenerateBCryptHash )
BCryptVerify: Performs a BCrypt verification on the given string against the hashed value. ( Alias: BCryptCheckHash )
SCryptHash: Returns a secure input hash of the given string using the SCrypt hashing algorithm.( Alias: GenerateSCryptHash )
SCryptVerify: Performs a SCrypt verification on the given string against the hashed value. ( Alias: SCryptCheckHash )
GeneratePBKDFKey: Generates a PDFK key from the given password and salt.

You can now listen to when the engine flushes the output buffer and intercepts it. This will allow you to collaborate content to the buffer before it's sent to the output destination. The data received is:

context - The execution context
output - The string output to send to the buffer. This can be text or HTML

This is one of our biggest tickets for this release to continue to close the Java interop cycle in BoxLang. This will allow BoxLang lambdas/closures/udfs to be coerced to Java Functional Interfaces at runtime. This means that ANY Java library that offers functional interfaces (lambdas) can be used natively in BoxLang. This means that using streams, completable futures, and Java lambdas are now native to BoxLang.

This can also be used to tap into high concurrency constructs in Java. You can combine the usage of BoxLang pure functions (lambdas) or context-aware closures.

All BoxLang arrays have native stream support, and you get native parallel support as well.

Our truthy/false evaluations for arrays, structs, queries, Java lists, and collections are complete.

This is inspired by Java Optionals for BoxLang. We have introduced a new class called Attempt(), which allows you to create fluent and functional code to work with values or delay attempts at code execution. Then, you can interact with the result of your attempt using our functional methods.

Another important aspect of attempts is that they evaluate that the seeded value is not null but also truthy. This means you can use it to evaluate that the value is truthy or false, not only null. You can also pass in a closure/lambda to be the value and once you request to evaluate the result, it will do it asynchronously and delayed.

Here are the current functions available to you in this beta. There are more coming to make it more fluent.

get():any - Get the value or throw an exception if null or falsey
empty():Attempt - Produce a new empty attempt
of( value ):Attempt - Produce a new attempt with the passed value
ofFunction( context, function/closure/lambda ):Attempt - Produce a new attempt with a closure or lambda.
isEmpty():boolean - Is the value falsey or null
isPresent():boolean - Is the value present
ifPresent( consumer ):Attempt - Call the consumer lambda/closure if the value is present
ifPresentOrElse( consumer, action ):Attempt - Call the consumer lambda/closure if present or the action lambda/closure if not.
ifEmpty( consumer ):Attempt - Call the consumer if the value is not present
or( supplier ):Attempt - If the value is present it returns itself, if not, it calls the supplier closure/lambda to produce a new attempt.
orElse( other ):any- Get the value if present, or otherwise return the other value passed
orElseGet( supplier ):any - Get the value if present, otherwise call the supplier closure/lambda to produce the value you want to return.
map( mapper ): Attempt - Maps the value of the attempt if it exists, else returns the same attempt with no value.
filter( predicate ) - If the value is present it will call your predicate closure/lambda so you can run tests on the value. If the return is true it will return the same attempt, else an empty attempt.
orThrow():any - Returns the value if it exists or throws an exception
orThrow( message ):any - Returns the value if it exists or throws an exception with your custom message
orThrow( exception ):any - Returns the value if it exists or throws your custom exception
stream():Stream - If the value exists returns a stream with the value else an empty stream
toString():String - Gives you a string representation of the value
isValid():Boolean - If the value is present it will try to validate it with the registered validation schemas, if any.
toBeValid( closure or lambda ):Attempt - This allows you to register a lambda/closure to validate the data if any. When calling isValid() it will call this function if registered.
toBeBetween( min, max ):Attempt - This allows you to register a min and max numerical values to test the value. It must be in range to be valid.
toMatchRegex( regex ):Attempt - This allows you to register a regular expression to match against the value.

This was something we always wanted to do. This allows module and BoxLang developers to contribute member methods to ANY BoxLang class. So now, you can serialize any Class to JSON natively using our BoxLang Class to JSON native serialization. Let's build a Person class:

As you can see, we have introduced a few annotations for JSON serialization based on our experience with the ColdBox mementifier project. You can tag properties to be excluded from serialization using the jsonExclude annotation. You can exclude a list of properties from the class annotation as well. Now, let's get some JSON data out using the toJSON() member function, which delegates it to the jsonSerialize() bif.

This will allow framework developers to collaborate with first-class methods in any BoxLang class.

This is an internal convenience method for creating BoxLang arrays from strings.

BoxLang is an event-driven language. It announces tons of events during the software life cycle. You can now listen to any global event via the new BoxRegisterInterceptor() bif. This will allow you to register classes, lambdas, or closures.

However, BoxLang also offers interceptors at the request level via the internal application listener. This means that you can listen to a specific request life-cycle by using the boxRegisterRequestInterceptor() bif.

More work towards compatibility is completed.

This has been a heached in current CFML engines. We now detect what you send in to the writeOutput() or echo() commands and we will convert them to string if they are complex objects or classes.

Native Encrypt, Decrypt and GenerateSecretKey()

We now support all encryption and decryption algorithms natively in BoxLang without ANY third-party library. Secure by default and with 3 BIFS created for this. Supported algorithms:

AES
ARCFOUR
Blowfish
ChaCha20
DES
DESede
HmacMD5
HmacSHA1
HmacSHA224
HmacSHA256
HmacSHA384
HmacSHA512
HmacSHA3-224
HmacSHA3-256
HmacSHA3-384
HmacSHA3-512

1.0.0-Beta6

July 19, 2024

BoxLang Betas are released weekly. This is our fifth beta marker. Here are the release notes.

New Features

We are excited to bring the completion of nested transactions into BoxLang, something we have wanted in an open-source engine for years.

transaction{
  queryExecute( "INSERT INTO developers ( id, name, role ) VALUES ( 22, 'Brad Wood', 'Developer' )", {} );
    
    transaction{
      queryExecute( "INSERT INTO developers ( id, name, role ) VALUES ( 33, 'Jon Clausen', 'Developer' )", {} );
	 transactionRollback();
    }
    
}

Here, the INSERT in the child transaction is rolled back, but the parent transaction's INSERT statement persists.

General behavior:

A rollback on the parent transaction will roll back the child transaction.
A rollback on the child will NOT roll back the parent.
Child transaction savepoints use a prefix so they don't collide with the parent transaction.
Logging has been added, so you can easily see the transaction lifecycle as a transaction is created, savepoints are created, transactions rollback, etc.
You can't change any transaction properties on a nested transaction. i.e., once the parent transaction begins, you can't begin a child transaction and change the isolation level.

Transaction events will come in the next beta.

This BIF is now complete so you can easily reverse query data.

Adobe CFML Engines do this today via their “magic” connector. Lucee has never supported it. The expanded path should work like so now:

if it doesn’t start with a / (and isn’t absolute), then make it relative to the base path
look for a BoxLang mapping (not including “/” )
Check if it’s an absolute path already, like C:/foo/bar
Then announce an ON_MISSING_MAPPING interception point
if no interceptor provided a value, then resolve via the root / mapping

The servlet runtime will have a listener for ON_MISSING_MAPPING that attempts to use servetContext.getRealPath() to try and resolve the path. This will allow any aliases in the resource manager to kick in.

If the servlet has an alias called /foo and you expand the path /foo/existingFile.txt, it will see it, but if you expand the path /foo/notExistingFile.txt then it will not “see” the mapping. We can solve that by taking off segments to see if any part of the path is found, but there is a performance hit to that, and I’m not sure if it’s necessary or not.

We have introduced static access to headless BIFS in BoxLang so you can use them as method references anywhere a BIF can be received, EVEN in Java classes that implement similar BIFS.

// Syntax
::BIF

// Examples
::UCase
::hash

This expression represents a first-class BoxLang function that can be invoked directly.

(::reverse)( "darb" ); // brad

You can also store the BIF static access into variables.

foo = ::ucase
foo( "test" ) // TEST

You can also leverage it as a high-order function combination from methods or classes that expect function references.

["brad","luis","jon"].map( ::ucase ); // [ "BRAD","LUIS","JON" ]

[1.2, 2.3, 3.4].map( ::ceiling );    // [2,3,4]

["brad","luis","jon"].map( ::hash ); // ["884354eb56db3323cbce63a5e177ecac", "502ff82f7f1f8218dd41201fe4353687", "006cb570acdab0e0bfc8e3dcb7bb4edf" ]

In order to explain this new functionality in BoxLang, here is a Java snippet:

List.of("apple", "banana", "cherry").stream().forEach(String::toUpperCase);

This syntax is a shortcut for writing out the following Java lambda:

List.of("apple", "banana", "cherry").stream().forEach(str -> str.toUpperCase());

(Other JVM languages like Clojure have similar syntax) The String::toUpperCase binds to the instance method toUpperCase, but in a way that it will be called on each string instance in the stream. So for each iteration, it will call the toUpperCase method on that instance. Nothing like this ever existed in CFML engines. However, in BoxLang, it does now. BoxLang allows you to do the following:

BoxLang-type member methods
Class member methods
Java member methods
Any object member/field

Since member methods in BoxLang aren’t necessarily bound to a class and we’re a dynamic language, we have simplified the syntax to this:

.methodName

This is a function expression that accepts a single argument and calls the method name specified on the incoming instance, returning the result of the member call. it is a shortcut for

i -> i.methodName()

So our Java example becomes like this in BoxLang

["apple", "banana", "cherry"].stream().forEach( .toUpperCase );

When not using (), check if there is a field of that name that is not a function, and if so, return that field value. So, the following example would fetch the name key in the struct.

nameGetter = .name
data = { name : "brad", hair : "red" }
nameGetter( data ) // brad

If the syntax .foo() is used or there is no field of that name, then it will be assumed we’re invoking a method. It can be directly invoked:

(.reverse)( "darb" ); // brad

It can be placed into a variable and invoked later:

foo = .ucase;
foo( "test" );  // TEST

And it can be passed to higher-order functions. (This is the main use case)

["brad","luis","jon"].map( .toUpperCase ); // ["BRAD","LUIS","JON"]

[1.2, 2.3, 3.4].map( .ceiling ); // [2,3,4]

[
  { myFunc : ()->"eric" },
  { myFunc : ()->"gavin" }
].map( .myFunc ) // [ "eric", "gavin" ]

Additionally, we have added support for multiple-arguments as well:

.methodName( arg1, arg2 )

Example:

["brad","luis","jon"].map( .left(1) ); // [ "b", "l", "j" ]

The arguments will not be evaluated until the function is invoked, and the argument expressions will be re-evaluated for every invocation.

pendingOrders.each( .submit( generateNextOrderNumber() ) ) // Fresh order number for each submission

The argument evaluation will have lexical binding to the declaring context.

local.suffix = " Sr."
["brad","luis","jon"].map( .concat( suffix ) ); // [ "brad Sr.", "luis Sr.", "jon Sr." "]

children.each( .setParent( this ) )

Bound member methods can also use named params (unless they are Java methods, of course)

foo = .left( count=2 );
foo( "test" ); // "te"

This brings a whole new dimension of dynamic goodness for not only BoxLang functions but also for Java functions. Welcome to a new era!

This is one of our very first steps in supporting range types. You know have the capability to generate arrays with a specific boxed range using arrayRange( from, to ). You can use a from and to numeric index, and it will build the array with that many elements with the range as its value. However, you can also use range notation: {from}..{to}

// an array from 1 to 100
a = arrayRange( "1..100" )
a = arrayRange( 1, 100 )

// a negative indexed array
a = arrayRange( "-10..10" )
a = arrayRange( -10, 10 )

We have now finalized a threadTerminate( name ) BIF.

We have now finalized a threadJoin( [name], timeout ) BIF. We have expanded this BIF and if you don't pass a thread name or a list of names, it will join all active threads.

This is now finalized.

Futures

value : If passed, the value to set on the BoxFuture object as completed, or it can be a lambda/closure that will provide the value, and it will be executed asynchronously, or it can be a native Java CompletableFuture
executor : If passed, it will use this executor to execute the future. Otherwise, it defaults to the fork/join pool in Java.

// incomplete future
f = futureNew()

// completed future with a value
f = futureNew( myValue )

// a future that executes an asynchronous lambda/closure and the value will be the result
f = futureNew( () -> orderService.calculate() )

// A future with an executable and a virtual thread executor
f = futureNew(
    () -> processTasks(),
    executorNew( "virtual", "virtual" )
)

runAsync( callback, [executor ] )

You can pass a closure or lambda to runAsync() to execute it asynchronously. The seconds parameter is an executor which runs the threads. It runs in the fork/join pool by default, but you can also pass your own executors. The return is a BoxFuture, which you can then do asynchronous pipelines.

calculation = runAsync( () -> calculateNumber() )
    .then( result -> result * 2 )
    .then( result -> result + 5 )
    .onError( exception -> { manage exception } )
    .get()
    

// Use a custom executor
runAsync( () -> "Hello", executorNew( "single", "single" ) )
    .then( ::println )
    .join()
    
// Process an incoming order
runAsync( () => orderService.getOrder() )
    .then( order => enrichOrder( order ) )
    .then( order => performPayment( order ) )
    .thenAsync( 
        order => dispatchOrder( order ), 
        executorNew( "cpuIntensive", "fixed", 150 )
     )
    .then( order => sendConfirmation( order ) );
 
// Combine Futures
var bmi = runAsync( () => weightService.getWeight( rc.person ) )
    .thenCombine(
	runAsync( 
	    () => heightService.getHeight( rc.person ) ),
            ( weight, height ) => {
            var heightInMeters = arguments.height/100;
            return arguments.weight / (heightInMeters * heightInMeters );
            })
        .get();

You now have the full capability to register, create, and manage custom executors in BoxLang. The AsyncService manages all executors in BoxLang.

Here are the new functions dealing with executors:

executorGet( name ): Get a registered executor
executorHas( name ): Checks if an executor has been registered or not
executorList() : Lists all registered executors
executorNew( name, type, [maxThreads:20] ): Creates and registers an executor by type and max threads if applicable.
executorShutdown( name ): Shuts down an executor
executorStatus( [name] ): Get a struct of executor metadata and stats by name or all.

The available executor types are:

cached - Creates a cached thread pool executor.
fixed - Creates a fixed thread pool executor.
fork_join - Creates a fork-join pool executor.
scheduled - Creates a scheduled thread pool executor.
single - Creates a single thread executor.
virtual - Creates a virtual thread executor.
work_stealing - Creates a work-stealing thread pool executor.

You can now register your executors globally in BoxLang in the boxlang.json

// Global Executors for the runtime
// These are managed by the AsyncService and registered upon startup
// The name of the executor is the key and the value is a struct of executor settings
// Types are: cached, fixed, fork_join, scheduled, single, virtual, work_stealing
// The `threads` property is the number of threads to use in the executor. The default is 20
// Some executors do not take in a `threads` property
"executors": {
	"boxlang-tasks": {
		"type": "scheduled",
		"threads": 20
	},
	"cacheservice-tasks": {
		"type": "scheduled",
		"threads": 20
	}
},

DBInfo now returns primary and foreign key columns when you need them.

Metaprogramming on queries is now available with much more information like caching, execution status, records, etc.

Improvements

One of the odd things about CFML is the following:

myArr.append( "foo" ) // returns myArr
arrayAppend( myArr ) // returns true??

In BoxLang, the following BIFS returns the instance it was called with instead of a boolean. However, if you are in compat mode in a CFML file, you will get the old behavior.

arrayAppend()
arrayClear()
arrayDeleteAt()
arrayInsertAt()
arrayResize()
arraySet()
arraySwap()
StructClear()
StructKeyTranslate()
StructInsert()
structAppend()
QuerySetRow()
QueryDeleteRow()
QuerySort()
ArrayPrepend()

The following BIFs return something other than the original data structure, but they have a good reason for doing so, so they remain as is:

queryAddColumn() -- returns index of the column removed
queryAddRow() -- returns the row number added

The following BIF returns the query in Adobe, which we’ll match. Lucee returns the array of removed data, but we’re ignoring that since we agree with Adobe’s behavior.

QueryDeleteColumn()

Bugs

Differences From CFML

A quick guide on key differences and issues when migrating from CFML

Please note that our CFML Compatibility is still in progress. Please keep this page bookmarked as we progress to our stable release.

You can install the compatibility module using box install bx-compat-cfml or if you have a server.json you can add the following:

    "scripts":{
        "onServerInitialInstall":"install bx-compat-cfml"
    }

Even if you forget the server, when you start it up, it’ll get the compatibility module automatically.

File Types

BoxLang can parse and run all of the traditional CFML file types

.cfc - Components
.cfs - Scripts
.cfm - Templates

Components are Classes

CFML Components (CFCs) are called classes in BoxLang, like any other language. You can also use the class declaration for them. You can continue to write components if you like, but if you use our .bx extensions, they are now classes.

class{

    property name=¨firstName¨

}

Tags are Components

Since BoxLang is not a tag-based language but a dynamic language offering a templating language. There are no concepts of tags but of BoxLang components that can be accessed via our templating language or script. In CFML the templating language uses a <cf prefix, in BoxLang we use a <bx: prefix.

<bx:if expression>

<bx:else>

</bx:if>

Default assignment scope

In CFML, the default assignment scope is always variables, but in BL it can differ based on the context. For Functions, it will be local. The BoxLang runtime will toggle this behavior based on the type of the compiled source code. So for .cfm or .cfc source files, the default assignment scope in functions will remain variables but for code compiled from .bx, .bxs or .bxm files, the default assignment scope in functions will be local.

CastAs operator

BoxLang has a new castAs binary operator that you can use instead of the javaCast() bif.

expression castAs type

No transpilation changes are needed since this is a BL-only feature.

Multiple catch types

BoxLang supports

catch( foo.com | brad | com.luis.majano e ) {}

No transpilation changes are needed since this is a BL-only feature.

Annotations

BoxLang will allow for proper annotations before UDF declarations, properties, and classes. The annotation's value can be a string, struct literal, or array literal. You can also use multi-spaced or indentation.

@foo
@bar( value )
@output( true )
function myFunc() {
}

No transpilation changes are needed since this is a BL-only feature.

Documentation Comments (Javadoc style)

BL will support documentation comments like CF, but will NOT allow them to actually influence the function’s behavior. When transpiling CFML to BL, any annotations set in a doc comment modifying the function or any arguments need to be moved to proper annotations in BL.

So the CFML

/**
* My function hint
*
* @output false
* @brad wood
* @name Luis
*
* @myService my hint here for the arg
* @myService.inject
*/
function foo( required any myService ) {}

would turn into this BoxLang

/**
* My function hint
*
* @myService my hint here for the arg
*/
@output( false)
@brad( wood ) // Strings can use quotes or no quotes
@name( “Luis” )
@myService.inject
function foo( required any myService ) {}

Function output defaults to false

The output of functions will be false in BL. The BoxLang runtime will toggle this behavior based on the type of the compiled source code. So for .cfm or .cfc source files, default value of the output annotation on classes and functions will remain true but for code compiled from .bx, .bxs or .bxm files, the default value of the output annotation on classes and functions will be false.

Note, if your Application.cfc and onRequestStart() method do not specify

@output( true )

you will get a blank page with no output!

Accessors True

Accessors in BoxLang are automatically true for all classes by default. This is false for CFML. You can also disable as normal if needed.

@displayName( “user” )
class{

    Property name=“fullName”;
    
}

// Accessors are on by default
user = new User()
user.setFullName( “Luis” )
println( user.getFullName() )

Invoke Implicit Accessors True

We also default invoking of implicit accessors by default to true . You can also disable this at the class level or at the runtime level in the configuration. This is a syntactic sugar to make a delegated call to the accessor/mutator by making it look like if they are property access.

@displayName( “user” )
class{

    Property name=“fullName”;
    
}

// Accessors and invoke implicit are on by default
user = new User()
user.fullName = “Luis Majano”
println( user.fullName )

Import keyword

CFML has the import tag, but there doesn’t seem to be any special script version of it, ours looks like this:

import taglib="/relative/path/customTags" prefix="tags";

import package.Class as alias

Import Aliases

You can also import classes from any resolver and attach an alias to remove any ambiguity.

import java:org.apache.User as jUser;
import models.User;

var oUser = new jUser()
var testUser = new User()

Object Resolvers

Any import or new can be prefixed with an object resolvers prefix. A resolver adheres to our resolver interface to provide access into any type of object or filesystem. By default we ship with two resolvers:

java : Java classes
bx : BoxLang classes

This allows you to import or easily create classes from any source.

// Default resolver is bx : boxlang
import models.User;
// Same as
import bx:models.User;

// Java resolver
import java:java.util.ConcurrentHashMap;

// Custom Resolver
import cborm:entity

This will allow us to modularly provide object resolvers for any type of integrations. You will also be able to use the resolvers for extends and implements

class implements="java:java.util.List" {

}

class extends="java:ortus.boxlang.runtime.types.Struct"{

}

Auto-casting argument and return value types

In CF an argument or return value of Numeric will allow a String through untouched so long as that string can be cast to a number. In BoxLang, we are actively casting the value to a “real” number. In theory, this is seamless, but could affect if you are checking the underlying Java type or passing to a Java method. There is no transpilation that can undo this, unless we add some setting or runtime configuration to disable the “feature”.

GetCurrentTemplatePath() and relative includes

Both Adobe and Lucee do not agree with each other and are inconsistent even within themselves regarding

The return value of the getCurrentTemplatePath() BIF
The lookup of relative templates being included
The lookup of relative CFC paths for object instantiation

Here is some documentation on their differences:

Given a method that's originally part of a CFC
- getCurrentTemplatePath() returns the original CFC (Adobe and Lucee agree here)
- new RelativeCFC() find CFCs in the same folder as the original CFC (Adobe and Lucee agree here)
- include "relativePath.cfm"; find CFCs in the same folder as the original CFC (Adobe and Lucee agree here)
Given a UDF defined in a file in a different directory that's injected into another CFC
- getCurrentTemplatePath()
  - returns the original birthplace of the UDF source in Lucee
  - returns the new CFC the UDF was injected into in Adobe
- Relative CFC path resolution
  - finds the CFC relative to the original birthplace of the UDF source in Lucee
  - finds the CFC relative to the NEW CFC's path in Adobe
- Relative cfinclude path resolution
  - finds the CFC relative to the original birthplace of the UDF source in Lucee
  - finds the CFC relative to the original birthplace of the UDF source in Adobe
Given a UDF defined in a file in a different directory that's passed into a UDF in another CFC for invocation
- getCurrentTemplatePath()
  - returns the new CFC the UDF was injected into in Lucee
  - returns the new CFC the UDF was injected into in Adobe
- Relative CFC path resolution
  - finds the CFC relative to the original birthplace of the UDF source in Lucee
  - finds the CFC relative to the NEW CFC's path in Adobe
- Relative cfinclude path resolution
  - finds the CFC relative to the original birthplace of the UDF source in Lucee
  - finds the CFC relative to the original birthplace of the UDF source in Adobe

In BoxLang, this is being simplified and made consistent across the board. In ALL cases the “current template path” and relative lookup directory will tie to the original source path on disk of the file that contains the currently executing code. So, whether it’s an include, a UDF, an injected UDF from another location, or a closure defined elsewhere - whatever original source file for the code in question is what determines the “current template path” and relative lookups.

BIF Renaming

Some bifs have been renamed in BoxLang.

CFML

BoxLang

serializeJSON

jsonSerialize

deserializeJSON

jsonDeserialize

chr

char

asc

ascii

getComponentMetadata

getClassMetadata

CreateObject Types

The component type for create object becomes class in BoxLang

createObject( ”class”, path )

JDBC Queries

Parameter SQL Types

Both Adobe ColdFusion and Lucee Server utilize a cfsqltype key on query parameters to denote the type of the value being used in a prepared statement or query:

queryExecute(
  "select quantity, item from cupboard where item_id = :itemID"
  { itemID : { value : arguments.itemID, cfsqltype : "cf_sql_numeric" } }
);

In BoxLang, you'll need to replace cfsqltype with just sqltype. In addition, we'd prefer to see all usage of the cf_sql_/CF_SQL prefixes stripped:

queryExecute(
  "select quantity, item from cupboard where item_id = :itemID"
  { itemID : { value : arguments.itemID, sqltype : "numeric" } }
);

Here's a full breakdown of the various syntaxes:

sqltype:"numeric" - The preferred syntax.
cfsqltype:"cf_sql_numeric" - will throw an error in BoxLang core. In CFML syntax files, is transpiled to sqltype:"cf_sql_numeric".
sqltype:"cf_sql_numeric" - is silently treated as sqltype:"numeric".

BlockFactor Query Option

The blockfactor query option in Adobe CF and Lucee Server is used to set a custom batch size when selecting large numbers of rows:

queryExecute( "Select * FROM myBigTable", {}, { blockfactor : 100 } );

In BoxLang, this is renamed to fetchSize:

queryExecute( "Select * FROM myBigTable", {}, { fetchSize : 100 } );

You can use the blockfactor nomenclature by installing the bx-compat-cfml module.

Date and Time Handling

Date Modification and Addition Operations

In BoxLang dates operation and comparison precision is to the millisecond level, compared to the legacy behavior of precision to the second. With the CFML compat module, date comparison functions will revert to using second-level precision.

In addition rounding behavior of date addition may be different than other CFML engines, but in a good way. The following code, when executed in non-BoxLang engines:

epochDate = parseDateTime( "1970-01-01T00:00:00.000Z" );
updatedDate = dateAdd( "s", 500/1000, epochDate );
result = dateTimeFormat( updatedDate, "yyyy-MM-dd'T'HH:mm:ss.SSSX", "UTC" );

will produce an incorrect rounding to the minute ( e.g. 1970-01-01T00:01:00.000Z ). In BoxLang, the addition of ½ second produces a correctly rounded result to the second of 1970-01-01T00:00:01.000Z

Quick Syntax Guide

Quickly learn what the BoxLang language offers.

This guide provides a quick overview of BoxLang syntax styles, intricacies, operators, and features. It aims to assist developers from other languages in their BoxLang development journey. BoxLang has been heavily inspired by many different languages, including Java, CFML, Groovy, Kotlin, Ruby, PHP, and more.

Dynamic & Loose Typing

BoxLang variables are dynamic and type-inferred. We try our best to infer which type you are trying to set for variables at compile-time, but they can completely change at runtime. You use the var keyword to specify a variable within functions or declare them inline if you are in a bxs or bxm script file.

File Types:

bx - A BoxLang class
bxs - A BoxLang scripting file
bxm - A BoxLang templating markup file

// Infered as 'String'
name = "boxlang"

// Inferred as Integer
age = 1
// But I can redeclare it to a string if I need to
age = "one"

// Inferred as Boolean
isActive = false

// Inferred as Date
today = now()

// Use the `var` keyword to define function-local only variables
function test(){
  var name = "hello"
}

You can also add types to arguments within functions or omit them, and it will default to any, which means, well, anything:

function add( required numeric a, required numeric b, boolean print = false ){

}

As you can see, not only can we make arguments required or not, but we can also add default values to arguments. BoxLang does not allow method overrides since basically, every method can take an infinite number of arguments, defined or even NOT defined.

We can also do type promotions and auto-casting from types that can be castable to other types. So, if we call our function like this:

// we auto cast 1 to numeric, "true" to boolean
add( "1", 345, "true" )

This is handy as we really really try to match your incoming data to functional arguments.

`Any` by default

If they are not specifically typed, all arguments and variable declarations are of any type. This means they will be inferred at runtime and can change from one type to another.

// Variables declared in a script are of any type and inferred
name = "luis"

function hello( name ){
    // argument name can be anything
}

High Precision Mathematics

By default, BoxLang will use high-precision mathematics by evaluating your numbers and determining the right type for them. If the numbers are whole and short enough, they will be stored in an Integer or Long. If they contain decimals, they will be a BigDecimal and if you do math on them, the result will be the most precise of the two inputs. You don't have to be knowing or addressing the numerical types, we will do that for you.

You can store a larger number like:

123123123123123123123123123

in a Double, but behind the scenes, not all of that is stored. All Java tracks is

1.2312312312312312 E 26

which means some digits of the original number are gone. So, if you run the math equation

11111111111111111111 + 22222222222222222222

you get:

Windows calculator: 33333333333333333333
BoxLang: 33333333333333333333

You may not be too worried about the use case of very large numbers, but the floating point math has bitten every single developer who’s been around long enough and can wreak havoc on the simplest of math calculations.

Level of Precision

Furthermore, Java’s BigDecimal class allows you to choose the level of precision you want to use. Java 21 defaults to “unlimited” precision, but we’ve dialed that back to the IEEE 754-2019 decimal128 format, which has 34 digits of precision and uses a rounding mode of HALF_EVEN. You can change the amount of precision BoxLang uses for BigDecimal operations at any time like so:

import ortus.boxlang.runtime.types.util.MathUtil;
MathUtil.setPrecision( 100 );

Only When Needed

BoxLang has a smart parser that will always store a number in the smallest package possible, opting to promote the type only when necessary.

n = 1;  // smaller than 10 digits stores in an Integer
n = 11111111111111; // Smaller than 20 digits stores in a Long
n = 111111111111111111111111111; // Anything larger stores in a BigDecimal
n = 12.34;  // All floating point values, store in a BigDecimal

The “bigger” types are contagious. So if you add together an Integer and a Long, we store the result in a Long. If you add a Long and a BigDecimal together, we store the result in a BigDecimal. The idea is always to keep things small and fast until we can’t any longer.

Numeric Literal Separators

Numeric placeholders allow you to place underscore characters (_) inside of a numeric literal for readability. Take a number like this

n = 1000000000

That’s 1 billion. Or was it 1 million? Or maybe it was 100 million… pauses to re-count. With numeric placeholders, your code can look like this:

n = 1_000_000_000

Ahh, so it was 1 billion! There are no rules on where you can place the underscores, so long as they are INSIDE the number and not leading or trailing. You can also place numeric separators in decimals:

n = 3.141_592_653_59

and in the exponent of scientific notation

1e2_345

These underscores are thrown away at compile time. They are not represented in the bytecode and will not appear anywhere in your running app. They are purely for readability in your source code.

Case Insensitive Functionality

Most things in BoxLang can be done with no case sensitivity by default. You can enable case sensitivity in many functions and components, but we try to be insensitive as much as possible :). Here are a few observations where access is case-insensitive by nature:

variable access in any scope
function calls, even to Java classes
function arguments, even on Java classes
class creation, even on Java classes

name = "luis"
// Name can be outputted in any case
println( "Hi, my name is #NamE#" )

// Even maps or arrays
myMap = { name : "luis", age : 12 }
println( "My name is #mymap.NAME# and my age is #mymap.age#" )

Internally we leverage a Key class that provides us with case insensitivity. Each map has a Key as the, well, key.

BIFs = Built-In Functions

// Runs the println() bif and the now() bif
println( "Hola from #now()#" )

To get a sense of all the BIFs registered in your runtime, do a

writedump( getFunctionList() ) or println( getFunctionList() )

Member Functions

Member functions are special functions attached to all data types in BoxLang, whether they are structs, arrays, strings, numbers, dates, Java objects, classes, etc. We provide tons of member functions, but developers can also contribute their own via BoxLang modules. All member functions map back to built-in functions (BIFs).

myArray = [1,2,3,4]
println( myArray.count() )

fruitArray = [
    {'fruit'='apple', 'rating'=4},
    {'fruit'='banana', 'rating'=1},
    {'fruit'='orange', 'rating'=5},
    {'fruit'='mango', 'rating'=2},
    {'fruit'='kiwi', 'rating'=3}
]
favoriteFruites = fruitArray.filter( item -> item.rating >= 3 )

BoxLang Components

bx:http url=apiURL result="result" {
  bx:httpparam type="header" name="Accept" value="application/json";
}

bx:timer variable="myTimer"{
  .. this code to time...
}

As you can see, they all start with the prefix of bx:and the name of the registered component. Each component can have attributes and nested components as well. The cool thing about components, is that they translate incredibly well for templating so that you can create rich templating tags as well.

<bx:query name="getUser" datasource="myDatasource">
    SELECT id, firstName, lastName, email
    FROM users
    WHERE email = <bx:queryparam value="#form.email#" cfsqltype="cf_sql_varchar">
</bx:query>

We ship several components as core:

Abort - Abort the request
Application - Update/Configure the running virtual application
Associate - Associate variable data with a child or parent component
Cache - Caches content
Directory - Directory-based calls
DBInfo - Get database metadata and information
Dump- A cool UI/console dumper of data, simple or complex
Execute- Execute OS binaries
Exit- Exit from nested executions of components
File - File-based calls
Flush- Force flush the output buffer in BoxLang either to Web or Console or whatever runtime you are on.
HTTP - HTTP Calls
Include- Include another template file into another template. Inception.
Invoke- Invoke dynamic methods on dynamic objects with dynamic arguments
Lock- Easy code locking and segmentation
Log- Write to our log files
Loop- Looping constructs for native or Java types
Module- Call custom templates in an isolated fashion
Object- Create BoxLang, Java, Custom objects
Output- Wrap code/HTML to produce output to the buffers
Param- Parameterize variables with default values if not defined
Query - Execute quick queries
SaveContent- Execute content and save it's output into a variable using template stylings
Setting- Set global BoxLang setting directives
Silent- Wrap code so it doesn't produce any output or whitespace
Sleep- Sleeps the thread for the requested amount of time
StoredProc - Execute stored procedures
Transaction - Start JDBC Transaction demarcations
Timer - Time code between it
Thread - Create threaded code
Throw- Throw an exception
Trace- Trace debugging messages to the console or debugging facilities
XML- Build or work with XML content
Zip- Allows you to compress/uncompress and manipulate zip/gzip files

Expression Interpolation

BoxLang can interpret ANYTHING within # as an expression. This can be used for output, assignments, and much more.

"#now()# is a bif, and this #12 % 2# is a math expression, and more!"

Multi-Line Strings

In Java, you can declare a multi-line string easily (JKD15+) by using the triple (""") quote marks.

public String getText(){
   return """
   My text block
      with nice identation

      -- Luis Majano""";
}

It is by far the most convenient way to declare a multiline string as you dont have to deal with line separators or indentation spaces. In BoxLang, you only need 1 quote ("), we will take care of the rest!

function getText(){
   return "
   My text block
      with nice identation

      -- Luis Majano";
}

Multi-Variable Assignments

BoxLang supports the concept of multi-variable declaration and assignments by just cascading variables using the = operator.

name = threadname = taskName = "I am Spartacus!"

This will create the 3 variables in the variables scope with the value "I am Spartacus!"

Switch Statements

The BoxLang switch statements can work on any literal but also on any expression

switch( expression ) {
    case value : case value2 :{
        break;
    }

    default : nothing
}

Catch `any` exception

BoxLang allows you to catch any exception using our any operator

try{
    .. funky code here
} catch( any e ){

    // We just caught every single exception known to man!

}

Multi-Catch Exceptions

In BoxLang you can catch multiple exceptions by using the pipe | operator. They can be both BoxLang exceptions or Java exception types:

catch( foo.com | brad | com.luis.majano e ) {}

No Semicolons, almost

Semicolons are almost always optional except in some situations:

property definitions in classes
Component calls with no body
Component child calls

Components in BoxLang have contributed functionality that is not core language and can be used in a statement syntax. Examples are mail, http, ftp, etc.

// Properties
class{

    property name="hello";
    property lastName;

}

// Components

// No body, requires ;
bx:flush;

// With inline body ; not needed
bx:flush{}

// With Body using {}, so no ; needed
bx:savecontent variables="test"{
    echo( "hello" )
}

// With child calls ; needed
bx:http url=apiURL result="result" {
    bx:httpparam type="header" name="Accept" value="application/json";
    bx:httpparam type="header" name="x-test" value="test";
}

Scopes

BoxLang offers many different persistence and variable scopes depending on where and what you are. All scopes in BoxLang are backed by the Map interface, which in BoxLang land are called Structures. They are case-insensitive by default; you can pass them around as much as you like.

Scripts (`bxm, bxs`)

Scripts can be written in full script (bxs) or using our templating language (bxm).

variables - Where all variables are stored
Unscoped variables go to the variables scope in a script

Classes

BoxLang supports all Object-oriented constructs know in several languages. We expand on the areas of metaprogramming and dynamic typing.

variables - The private scope of the class
this - The public scope of the class and also represents the instance
static - The same as Java, a static scope bound to the blueprint of the class
Unscoped variables go to the variables scope in a class

Functions/Lambdas/Closures

BoxLang supports 3 types of Functions.

local - A local scope available only to the function
arguments - The incoming arguments
variables - Access to the script or class private scope
this - Access to the class public scope
Unscoped variables go to the local scope in a function by default

Persistence Scopes

BoxLang and some of it's runtimes also offer out of the box scopes for persistence.

session - stored in server RAM or external storage tracked by a unique visitor
client - stored in cookies, databases, or external storages (simple values only)
application - stored in server RAM or external storage tracked by the running BoxLang application
cookie - stored in a visitor's browser (Web Only)
server - stored in server RAM for ANY application for that BoxLang instance
request - stored in RAM for a specific request ONLY
cgi - read-only scope provided by the servlet container and BoxLang (Web Only)
form - Variables submitted via HTTP posts (Web Only)
URL - Variables incoming via HTTP GET operations or the incoming URL (Web Only)

Scope Hunting

When you access a variable without specific scope access, BoxLang will try to find the variable for you in its nearest scope. This is done internally via a context object, which can be decorated at runtime depending on WHERE the code is being executed (CLI, web, lambda, android, etc) Example:

function( name ){

    // add to data, which has no scope and no arguments exist
    // so it looks for it in the variables scope
    data.append( name )

    // Looks in arguments first
    return name;
}

Full Null Support

null is a real thing! It's nothing but real! We support the null keyword, assignments, and usage just like Java. It follows the same rules.

CastAs Operator

BoxLang has a natural casting operator that is fluent and readable: castAs {expression}. It can be an expression since the right-hand side can be dynamic. Unquoted identifers will be considered a string literal. Any other expression will be evaluated at runtime.

myJavaClass( value castAs long )

return {
    age : value castAs int,
    tags : value castAs String[],
    isActive : "#value#" castAs Boolean
    spam : value castas "#DynamicType#"
}

Human Operators

Symbol Operator

Human Operator

Hint

==

eq

!=, <>

neq

>

gt

>=

gte

<

lt

<=

lte

contains, ct

Returns true if the left operand contains the right one. 'hello' contains 'lo'

does not contain, nct

Negated Contains

!

not

&&

and

||

or

XOR

Exclusive OR

EQV

Equivalence

IMP

Implication

%

mod

Modulus

InstanceOf Operator

Like other languages, we also offer an instanceOf operator alongside a nice BIF: isInstanceOf(). You can also use negation using our lovely not operator.

isInstanceOf( obj, "Map" )

if( obj instanceOf "String" )
if( obj instanceOf "MyUser" )
if( obj not instanceOf "Integer" )

Data Types

All Java types can be used alongside the core BoxLang types:

any
array
UnmodifiableArray
binary
boolean
class
closure
date
double
guid
function
float
integer
lambda
numeric
number
query
UnmodifiableQuery
string
struct
UnmodifiableStruct
uuid

Arrays are Human

Arrays in BoxLang start at 1, not 0. End of story!

Array/Struct Literal Initializers

Arrays and Structs in BoxLang can be created using literal constructs. Please note that values within the literal declarations can also be expressions.

// empty array
array = []
// array with data
array = [ 1, 23, 234 ]

// empty struct
myMap = {}

// struct with data
myMap = { age:1, test: now() }

// ordered struct with data
myMap = [ age:1, test: now(), anotherKey: "name" ]
myMap.each( ::println )

// Nesting
myArray = [
    {
        name: "BoxLang",
        type: "JVM Dynamic Language",
        version: "1.0.0",
        tags: ["dynamic", "JVM", "scripting", "modern"],
    },
    {
        name: "ColdBox",
        type: "MVC Framework",
        version: "7.0.0",
        tags: ["framework", "MVC", "CFML", "enterprise"],
    },
    {
        name: "TestBox",
        type: "BDD Testing Framework",
        version: "6.1.0",
        tags: ["testing", "BDD", "TDD", "automation"],
    },
];

println( myArray );

Tip: Also remember you can nest arrays into structs and structs into arrays

Trailing Commas

BoxLang supports trailing commas when defining array and struct literals. If you miss a dangling comma, we won't shout at you!

myArray = [
    "BoxLang",
    "ColdBox",
    "TestBox",
    "CommandBox",
]
println( myArray )

myStruct = {
    name: "BoxLang",
    type: "JVM Dynamic Language",
    version: "1.0.0",
}
println( myStruct )

Unmodifiable Objects

BoxLang supports the concept of unmodifiable objects: arrays, structures or queries. These are objects that cannot be modified once they are created. You can also use two BIFs for working with these types:

toUnmodifiable( array or structure or query) - Make an array or structure unmodifiable
toModifiable( array or structure or query ) - Make an array or structure modifiable

These are also available on the types as member methods

myArray = [ 1, 2, 3, 4, 5].toUnmodifiable()
myData = { id: 1, when: now() }.toUnmodifiable()

Truthy/Falsey

BoxLang Truthy and Falsey are concepts used in programming to determine the "truth" of a value in a Boolean context. In many programming languages, values other than true and false can be evaluated for their truthiness. Understanding truthy and falsey values is crucial for writing effective and accurate code when evaluating conditions or performing logical operations.

Truthy values

positive numbers (or strings which can be parsed as numbers)
boolean true
string “true”
string “yes”
array with at least one item
query with at least one row
struct with at least one key

Falsey values:

A null value
The number 0 or string “0”
boolean false
string “false”
string “no”
empty arrays
empty queries
empty structs

Imports & Class Locators

BoxLang offers the ability to import both BoxLang and Java classes natively into scripts or classes.

// Import java classes
import java:java.io.IOException
import java:java.nio.file.FileSystems
import java:java.nio.file.Path

// Import BoxLang classes
import models.User
import models.cborm.MyService

Works just like Java. However, you will notice a nice java: prefix. This is called an class locator prefix. BoxLang supports these out of the box:

java: - Java classes to import or instantiate
bx: - BoxLang classes to import or instantiate (Default, not required)

You can also remove the java: prefix and BoxLang will try to locate the class for you. Careful, as it will scan all locations.

Import Aliases

You can also alias imports to provide less ambiguity when dealing with classes with the same name:

// Import java classes
import java:java.nio.file.Path as jPath
import models.utils.Path

myJavaPath = new jPath()
myBxPath = new Path()

All the object resolvers prefixes can be used anywhere a class or path is expected:

Creating classes and instances: createObject(), new
Using imports
Extending classes
Implementing interfaces

class implements="java:java.util.List" {

}

class extends="java:ortus.boxlang.runtime.types.Struct"{

}

Null Coalescing aka Elvis Operator

BoxLang supports the null coalescing operator ?: to allow you to evaluate if values are empty or null. This is not a shortened ternary as other languages.

( expression ) ?: 'value or expression'

This tests the left-hand side of the ?: and if its null then it will evaluate the right expression or value. This can be used on if statements, assignments, loops, etc.

BoxLang supports safety navigation on ANY object that can be dereferenced: structs, maps, classes, etc. This basically allows you to test if the value exists or not and continue dereferencing or return null

age = form.userdata?.age;

fullName = userClass?.getFullName()

Imagine how tedious this code is

if( order ){

    if( order.hasCustomer() ){
        if( order.getCustomer().hasAddress() ){
            println( order.getCustomer().getAddress() )
        }
    }

}

Now let's transform this code:

println( order?.getCustomer()?.getAddress() )

Assert

BoxLang offers an assert operators that will evaluate an expression and if the expression is falsey it will throw an assert exceptions.

// Asserts that the name is truthy
assert name

// Assert an expression
assert myService.hasData()
assert name.length() > 3

// Assert a lambda/closure result.
assert ()-> { do something }
assert ()=> { do something }

Functional

BoxLang functions are first-class citizens. That means you can pass them around, execute them, dynamically define them, inject them, remove them, and so much more.

It has three major functional types:

UDF—User-Defined Function—Can be created on any scripting template or within Classes. They carry no context with them except where they exist.
Closures are named or anonymous functions that carry their surrounding scope and context with them. It uses the fat arrow => syntax.
Lambdas are pure functions that can be named or anonymous and carry NO enclosing scope. They are meant to be pure functions and produce no side effects. Data in, Data out. It uses the skinny arrow -> Syntax.

hola.bxs

// This is a script that can define functions

// A scripting UDF
function sayHello(){
    return "Hola!"
}

// Execute the UDF
println( sayHello() )

MyClass.bx

// Some class UDFs
class{

    function init(){
        return this
    }

    function sayHello(){
        return "Hola!"
    }

}

test.bxs

// This script uses the defined class above
myClass = new MyClass()

// Let's create an alias for the function
// Functions are first-class citizens in BoxLang
// They can be added, removed, mixed at runtime
myClass.hola = myClass.sayHello

// Let's remove the sayHello function
myClass.sayHello = null
// Or use a global BIF call to remove it
structDelete( myClass, "sayHello" )

println( myClass.hola() )

Let's write up another script that leverages closures and lambdas.

test.bxs

// Named closure
myClosure = item => item++;
myClosure( 1 )

// Anonymous Closure
[1,2,3].filter( item => item > 2 )

// Named Lambda
myLambda = item -> item++;
myLambda( 1 )

// Anonymous Lambda
[1,2,3].filter( item -> item > 2 )

`Public` by default

All functions and classes are public by default, so there is no need to add the public identifier if you don't want to. This creates a very nice and low-verbosity approach to function declaration:

function hello(){}
// Same as:
public function hello(){}

// private
private function getData(){}

// protected
protected function bindData(){}

Non-required arguments by default

All arguments are NOT required by default and will be defaulted to null if not passed. You can use the required identifier to mark them as required.

function save( required user, boolean transactional = false, Logger logger ){

}

Default Arguments

You can create defaults for arguments, which can be literal or actual expressions:

function save( transactional = true, data = {}, scope = "#expression#" ){
}

function hello( name = variables.defaultName ){
    println( "Hola #arguments.name#" )
}

Argument Collections

Similar to var arguments in Java, BoxLang allows the arguments scope to be completely be variable. meaning you can declare the arguments, but you can pass as many as you like and they will all be added into the arguments scope.

Another feature is that you can bind and apply these arguments at function execution time from any map or structure via the argumentCollection special argument. This allows you to collect arguments and dispatch the function call, and BoxLang will match the argument names for you. This can be great for dynamic argument collection, form collection, JSON packets, etc.

function save( name, age, isActive, logIt=false ){
    .. Do your thing here!!
}

// Call the save using a map/struct
myMap = { name: "test", age: 40, isActive: true }
// Use the special argumentCollection designator
save( argumentCollection : myMap )

This is a great time saver.

Auto-casting Arguments & Return Values

In BoxLang, we actively cast the incoming argument value to the specified declared argument.

function setAge( numeric age )

BoxLang will try to auto cast the incoming argument to the numeric type in this instance.

It will also auto cast the outgoing return value for you. So if your function specifies that the return value is a boolean, but you return a string, it will auto cast it to boolean for you.

function Boolean isAlive(){
    return "yes"
}

BoxLang Classes

BoxLang classes are enhanced in many capabilities compared to Java, but they are similar to Groovy and CFML.

Automatic package definition
Automatic Hash Code and Equals methods
Automatic constructor created for you based on the defined properties
No need to add a name to the class definition, we use the filename
Implements by default IClassRunnable, IReferenceable, IType, Serializable
Automatic getters and setters for any property definition
Automatic implicit property accessors and mutators
Allows for pseudo constructor blocks for initializations and more (Space between last property and first function)
Output is false by default for pseudo-constructors and functions
Automatic metadata registration into the $bx BoxMeta programming object
Allows for single inheritance
Allows for interfaces
Allows for static blocks, functions, and properties
Allows for final properties (coming soon)
Allows for lazy properties (coming soon)
Allows for property observers (coming soon)
Allows for scope observers (coming soon)
Functions in a class can have different visibilities: private, public, protected, remote

Properties, not Fields

BoxLang classes can define properties as data members; they are not called fields and are always private meaning they will be stored in the variables scope. You can define them in short or long format. Please note that properties do require a semi-colon, as they can be very ambiguous.

All properties are stored in the variables scope.

Short Form

The short form allows for property [type=any] name [default=expression];

class{

    // No type means `any`, no default means null
    property firstName;
    // A numeric age with a default value of 1
    property numeric age default=1;
    // A struct data with a default struct literal
    property struct data default={ name:"this", age : 3, whatever : now() };

}

Long Form

The long form allows for name-value pairs. We distinguish some value pairs from those we don't, and those we don't will be added as metadata to the property.

class{

    property name="firstName" type="string" default="boxlang";
    property name="age" type="numeric";

    property name="data"
        type="struct"
        default={ name:"this", age : 3, whatever : now() };

}

default - The property's default value
name - The property's name
getter - Boolean indicator to generate or not the getter for the property. Default is true
required - If the property requires a value or not.
setter - Boolean indicator to generate or not the setter for the property. Default is true
type - The default type of the property defaults to any

BoxLang also advertises Class creations, so modules can collaborate with extra metadata and properties or inspect the properties and act on them.

Our dependency injection framework does this.

Automatic Constructor

Constructors in classes for BoxLang are not overloads but a single init() method. However, by default we create one for you. It can also take in named parameters or an argumentCollection to initialize all properties.

User.bx

class{

	property name;
	property email;
	property isActive;

}

// Create a new user with no data
user = new User()

// Create one with named params
user = new User( name: "BoxLang", email: "info@boxlang.io", isActive: true )

// Create one with an arg collection
myArgs = { name: "BoxLang", email: "info@boxlang.io", isActive: true }
user = new User( argumentCollection: myArgs )

If you create your own init() then it's your job to initialize your class :)

Annotations

BoxLang annotations can be added to properties, functions, and classes. Using the following pattern:

@annonationName
// or...
@annonationName( value, value, value )

The value is a literal expression (string, boolean null, number, array, or struct) or an identifer. Since runtime variables aren't allowed here, identifiers will be treated as quoted strings. If no value is supplied, then omit the parentheses.

Tip: Remember that string literals you can use quotes, single quotes or none.

@singleton
class{

    @inject
    property name="wirebox";
    
    
    @returnFormat( json )
    function getData(){
        return data
    }
    
    @cache( true )
    @returnFormat( "xml" )
    function getXMLData(){
    
    }

}

You can add as many as you like to the target locations without creating annotation classes or boilerplate.

Metadata: $bx

All of these annotations and metadata can be retrieved at runtime by using the getMetadata() or getClassMetadata() bifs. You can also look at the .$bx property in every boxlang object. Which contains not only the metadata about each object, but ways to do meta-programming with it. Like adding/modifying/removing properties/functions/annotations.

Extra metadata can be added to functions, properties, classes, or annotations.

@singleton
@transientCache( false )
@myMetadata( hello, "another value" )
class{

}

myClass = new MyClass()
writeOutput( myClass.$bx.meta ) or println( myClass.$bx.meta )

The $bx object is the BoxLang meta-object. It contains all the necessary metadata information about an object, it's Java class representations and useful methods for meta-programming. From it's Java Class, to functions, properties, data, etc. It can be used on ANY BoxLang Type. Here are the properties in the $bx object available to you. It also contains many methods that exist in the BoxMeta object.

meta - A struct of metadata about the class
$class - The Java Class that represents your class

Getter and Setters

By default, automatic getters and setters for properties are enabled. You can disable them all for the class or one by one. All the setters return an instance of this. You can also override them as you see fit.

class{

    property name="firstName" type="string" default="boxlang";
    property name="age" type="numeric"

    // Override the getter
    function getAge(){
        // log it
        return variables.age
    }

    // Override the setter
    function setFirstName( firstName ){
        // Log here
        variables.firstname = arguments.firstName;
        return this;
    }

}

myClass = new MyClass().setFirstname( "luis" );

Implicit Accessors

Implicit accessor/mutator invocations are on by default in BoxLang. You can disable them by adding the invokeImplicitAccessor annotation to false. Implicit accessors allows you to invoke getters and mutators as if you are working properties on a class. It's just syntactical sugar to make your code look a lot less verbose when calling getters and setters.

class{
    property name="firstName" type="string" default="boxlang";
    property name="age" type="numeric"
}

// Invoke Using implicit invokers
myClass = new MyClass();
myClass.age = 23
printLn( myClass.age )

// Disable invokers
@invokeImplicitAccessor( false )
class{
    property name="firstName" type="string" default="boxlang";
    property name="age" type="numeric"
}

Running BoxLang

BoxLang and the Multiverse!

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

/Users/username/.boxlang

/home/username/.boxlang

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

/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.

boxlang

boxlang.bat

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.

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

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

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

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

# 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-debug - Enable debug mode (more debug logs!)
--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

Modules

The Officially supported BoxLang modules

Every runtime can use modules, and the installation process can differ. So, make sure you review each of the sections on Running BoxLang and adapt your installation process accordingly.

For web runtimes running on CommandBox, our servlet server, then use the box CommandBox CLI for installation and server.json for tracking dependencies. For our operating system runtime, use our install-bx-module binary.

Operating System Modules

Operating System

# Install os-wide modules
install-bx-module bx-compat-cfml

# Install os-wide modules with a specific version
install-bx-module bx-compat-cfml@1.0.0

# Install multiple modules
install-bx-module bx-compat-cfml bx-esapi bx-orm

Local CLI Application Modules

BoxLang also supports the concept of local loading. Meaning, if you have a boxlang_modules folder in the root of where you run your CLI applications, then BoxLang will load those modules first and then fall back to the user's home directory for the operating system.

myAppDirectory

# Install locally
install-bx-module bx-compat-cfml --local

# Install locally
install-bx-module bx-compat-cfml@1.0.0 --local

# Install multiple modules locally
install-bx-module bx-compat-cfml bx-esapi bx-orm --local

CommandBox Runtimes

The CommandBox CLI installs BoxLang modules into web runtimes.

Eventually, CommandBox will be the de-facto standard of installation once it's migrated to BoxLang.

CommandBox

box install bx-compat-cfml bx-esapi

Configuration

You can customize the boxlang module directory by changing the runtime.modulesDirectory setting in your config/boxlang.json file:

boxlang.json

{

    // A collection of BoxLang module directories, they must be absolute paths
    "modulesDirectory": [
      "${boxlang-home}/modules"
    ],

}

Core Modules

Here is the collection of modules built and supported by the BoxLang team that are completely open-source.

bx-ai

Category: ai

Welcome to the BoxLang AI Module. This module is a BoxLang module that provides AI capabilities to your BoxLang applications.

install-bx-module bx-ai

bx-compat-cfml

Category: cfml

This module allows your BoxLang engine to run as an Adobe CFML engine or a Lucee CFML engine. Please note that we will not offer every single feature of the Adobe engines in this single module. It can be spread out through a collection of modules.

install-bx-module bx-compat-cfml

bx-csrf

Category: security

install-bx-module bx-csrf

bx-password-encrypt

Category: security

This module provides password encryption and hashing functionality to Boxlang. Includes bcrypt, argon, and Scrypt.

install-bx-module bx-password-encrypt

bx-esapi

Category: security

Leverages ESAPI and AntiSamy to provide your BoxLang applications with security and cleaning concerns.

install-bx-module bx-esapi

bx-ftp

Category: Communication

The FTP module allows you to perform various operations against an FTP or SFTP servers.

install-bx-module bx-ftp

bx-image

Category: Image Processing

The image module gives you tons of components and BIFs that will provide you with a robust and extensive image manipulation library.

install-bx-module bx-image

bx-jython

Category: Scripting

This module allows you to script in Python within BoxLang. It can also execute python scripts and modules.

install-bx-module bx-jython

bx-ini

Category: Operating System

This module allows you to interact with ini files.

install-bx-module bx-ini

bx-mail

Category: Communication

The mail module for BoxLang gives you a robust component and a collection of bifs that you can use to send mail and interact with mail services.

install-bx-module bx-mail

bx-markdown

Category: Conversion

This module provides you with native markdown parsing support in your BoxLang applications.

install-bx-module bx-markdown

bx-orm

Category: ORM

This module enables tight integration with JPA/Hibernate into your BoxLang applications.

install-bx-module bx-orm

bx-oshi

Category: Hardware

You can use this module to get information about the operating system and hardware of your machine. This is a great way to get sensor or embedded system information like batteries, Raspberry Pi, etc.

install-bx-module bx-oshi

bx-pdf

Category: Document Services

The pdf module will give you the capabilities to create and stream PDF documents from your BoxLang server code. We also offer the enhanced version in our BoxLang +,++ subscriptions.

install-bx-module bx-pdf

bx-ui-forms

Category: UI

This module contributes several semantic UI components using the BoxLang templating language.

install-bx-module bx-ui-forms

bx-unsafe-evaluate

Category: Compiler

This module will allow you to install an evaluate() function that can execute BoxLang and CFML expressions. Please note that this approach to coding is discouraged and unsafe.

install-bx-module bx-unsafe-evaluate

bx-wddx

Category: Conversion

The WDDX module provides the bridge between the WDDX exchange format and BoxLang. It involves reading and parsing XML, converting data types, handling errors, and ensuring performance and compatibility. The module enables the integration of legacy systems with new applications.

install-bx-module bx-wddx

bx-web-support

Category: Testing

This module provides the CLI runtime with all the web server BIFS, components and utilities need for mocking, testing and feature auditing. It also provides with testing facilities to mock a web server and interact with it. This is great for doing CLI based testing on a web application or running the feature audit commands.

THIS MODULE IS NOT NEEDED FOR COMMANDBOX OR THE MINISERVER. IT'S PURELY FOR TESTING, MOCKING AND AUDITING.

install-bx-module bx-web-support

bx-yaml

Category: Conversion

This module will serialize BoxLang native types to YAML and YAML to BoxLang Types.

install-bx-module bx-yaml

+/++ Modules

bx-redis

Category: Caching

This module will enhance your language by allowing you to connect to Redis instances, clusters, or sentinel instances. Here are some features:

Add native Redis functionality to the language
Connect to a Redis server or a Redis cluster, or Redis Sentinel
Store session variables in a distributed Redis cluster
Leverage the Redis publish/subscribe features to create real-time messaging
Get rid of sticky session load balancers, come to the round-robin world!
Session variable persistence even after server restarts
Cache connection capabilities for providing distributed & highly scalable query, object, template, and function caching
Much more

install-bx-module bx-redis

JDBC Modules

install-bx-module bx-derby

install-bx-module bx-hypersql

install-bx-module bx-mysql

install-bx-module bx-mariadb

install-bx-module bx-mssql

install-bx-module bx-oracle

install-bx-module bx-postgresql

CLI Scripting

The core runtime allows you to build CLI scripting applications

BoxLang is a modern, dynamic scripting language built for more than just simple automation—it empowers you to create full-fledged, high-performance CLI applications with ease. Designed to run seamlessly on the JVM, BoxLang provides powerful scripting capabilities, a rich standard library, and first-class support for modular development.

Whether you're automating repetitive tasks, building interactive command-line tools, or developing complex CLI-driven workflows, BoxLang offers the flexibility, expressiveness, and performance you need. With intuitive syntax, robust error handling, and seamless integration with Java and other JVM-based technologies, BoxLang makes CLI scripting more efficient and enjoyable.

Script Files

With BoxLang, you can execute a few types of files right from any OS CLI by adding them as the second argument to our boxlangbinary:

Please note that you will need the bx-compat-cfmlmodule if you want to execute CFML scripts

Here are some examples of executing the files. Just pass in the file by relative or absolute path location.

Other Scopes

Please note that you have access to other persistent scopes when building CLI applications:

application- This scope lives as long as your application lives as well, but it is technically attached to an Application.bxfile that activates framework capabilities for your application.
request- A scope that matches a specific request for your application. We also get one per CLI app since there is no concept of sessions or user state. There is always only one request.

Executing Classes

BoxLang allows you to execute any *.bxclass as long as it has a method called main()by convention. All the arguments passed into the file execution will be collected and passed into the function via the argsargument.

The argsargument is an array and it will contain all the arguments passed to the execution of the class.

If you execute this function above, the output will be:

Class executions are a great way to build tasks that have a deterministic approach to execution. We parse the arguments for you, and you can focus on building your task.

Executing Scripts / Templates

In addition to executing classes, you can execute *.bxsscripts that can do your bidding. The difference is that this is a flat source code script that executes from the top down. It can contain functions, scope usage, imports, and create any class.

Then, if we execute it, we can see this output:

What do you see that's different? We don't have the incoming arguments as an argument since it's a script. However, we can use the CLIGetArgs()BIF, and it will give you a structure of two keys:

positionals- An array of positional values passed to the script
options- Name value pairs detected as options

You can also get the arguments via the server.cli.parsedvariable, which already contains this structure.

Here is the output:

Please note that executing templates is the same as scripts, but your template uses templating language instead, which can be helpful if you produce some markup (HTML, Markdown, etc.)

SheBang Scripts

SheBang scripts are text files containing a sequence of commands for a computer operating system. The term "shebang" refers to the #! characters at the beginning of the script, which specify the interpreter that should be used to execute the script. These scripts are commonly used in Unix-like operating systems to automate tasks. You can run scripts directly from the command line using a shebang line without explicitly invoking the interpreter. BoxLang supports these scripts, so the OS sees them as just pure shell scripts, but you are coding in BoxLang scripting.

A SheBang script is just basically a *.bxsscript.

As you can see from the sample above, the first line is what makes it a SheBang script the operating system can use. It passes it to the boxlangbinary for interpretation. Also, note that you can pass arguments to these scripts like any other script and the CLIGetArgs()or the server.cli.parsed variables will be there for you to use.

CLI Built-In Functions

BoxLang also gives you several built-in functions for interacting with the CLI:

CLIClear():void - Clears the console
CLIGetArgs():struct - Return a structure of the parsed incoming arguments
CLIRead( [prompt] ):any- Read input from the CLI and return the value
CLIExit( [exitCode=0] )- Do a System.exit()with the passed-in exit code

Please note that you have a wealth of built-in functions and components that you can use to build your scripts.

Parsed Arguments

BoxLang will automatically parse the incoming arguments into a structure of two types when using the CLIGetArgs()BIF or by using the server.cli.parsed variable.

options - A structure of the options (name-value pairs) used to invoke the script
positionals - An array of the positional arguments used to invoke the script

The options can be provided in the following formats, which are standard in CLI applications:

--option - A boolean option that is set to true
--option=value - An option with a value
--option="value" - An option with a quoted value
--option='value' - An option with a single quoted value
-o=value - A shorthand option with a value
-o - A shorthand boolean option that is set to true
--!option - A negation option that is set to false
--no-{option} - A negation option

For example, the following CLI arguments:

Will be parsed into the following struct:

Some Ground Rules

Options are prefixed with --
Shorthand options are prefixed with -
Options can be negated with --! or --no-
Options can have values separated by =
Values can be quoted with single or double quotes
Repeated options will override the previous value

Reading Input

You can easily read input from users by using our handy CLIRead()bif. You can also pass in a promptas part of the method call.

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 to System out
print() - Print with no line break to System out
writeOutput(), echo() - Writes to the output buffer (Each runtime decides what its buffer is. The CLI is the system output, the Web is the HTML response buffer, etc)
writeDump()- Takes any incoming output and will serialize to a nice string output representation. This will also do complex objects deeply.

I get the output:

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

You can now call it with zero or more arguments!

Piping code

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

CLI App Modules

If you want to package your own or core BoxLang modules into your CLI app you can use the convention of boxlang_modulesand install the modules there using the --localflag of the install-bx-moduleinstaller script.

This is incredibly useful as BoxLang will check this convention folder first and then the OS home modules.

Dad Joke Script

Now you execute it

Let's modify it now so that we can prompt the user for the term using the CLIRead()BIF instead of passing it:

MiniServer

BoxLang includes a lightning fast web server powered by Undertow!

Tip: Please note that the BoxLang MiniServer is NOT a servlet server. There is no servlet container; the web server is just a simple, fast, and pure Java Undertow server.

Starting a BoxLang MiniServer

The BoxLang core OS runtime doesn't know about a web application. Our web support runtime provides this functionality, a crucial part of the MiniServer and the Servlet (JEE, Jakarta, CommandBox) runtime. This runtime enhances the core boxlang runtime, making it multi-runtime and web deployable.

If you use our Windows installer or our Quick Installer, you will have the boxlang-miniserver binary installed in your operating system. You will use this to start servers. Just navigate to any folder that you want to start a server in and run boxlang-miniserver.

# Mac / *unix
cd mySite
boxlang-miniserver

# Windows
cd mySite
boxlang-miniserver.bat

# Native Jar execution
cd mySite
java -jar /usr/local/lib/boxlang-miniserver-1.0.0.jar

Once you run the command, the following output will appear in your console:

+ Starting BoxLang Server...
- Web Root: /home/lmajano/Sites/temp
- Host: localhost
- Port: 8080
- Debug: false
- Config Path: null
- Server Home: null
+ Starting BoxLang Runtime...
+ Runtime Started in 2043ms
+ BoxLang MiniServer started in 2135ms
+ BoxLang MiniServer started at: http://localhost:8080
Press Ctrl+C to stop the server.

As you can see from the output, this is the result of the command:

Use the current working directory as the web root.
Bind to localhost:8080 by default
This configures the web server with some default welcome files and no rewrites.
BoxLang will process any BoxLang or CFML files
Uses the user's BoxLang home as the default for configuration and modules: ~/.boxlang

ALERT: The BoxLang Core knows nothing of web or HTTP, so the form, url, cookie, and cgi scopes will only exist when running the BoxLang web server (but not in the REPL, etc).

That's practically it. This is a very lightweight server that can get the job done. You can also start up servers using our VSCode IDE by opening the command palette and clicking Start a BoxLang web server.

Arguments

These are the supported arguments you can pass into the binary to configure the server.

Argument

Value

--configPath path/boxlang.json -c path/boxlang.json

Relative/Absolute location of the boxlang.json to use. By default it uses the ~/.boxlang/boxlang.json

--debug -d

Put the runtime into debug mode. By default we use false

--host ip|domain -h ip|domain

Bind the hostname to the mini server. By default we use localhost

--port 8080 -p 8080

The port to bind the mini server to. By default we use port 8080

--rewrites [index.bxm] -r [index.bxm]

Enable rewrites for applications using index.bxm as the file to use. You can also pass the name of the file to use: --rewrites myfile.bxm

--serverHome path/ -s path/

The location of the BoxLang home for the miniserver. This is where it will look for the boxlang.json, place to put the log files, the compiled classes, load modules, and much more. By default, we use the OS home via the BOXLANG_HOME environment variable which usually points to the user's home: ~/.boxlang/

--webroot path/ -w path/

The webserver root. By default, we use the directory from where you started the command.

# Custom port and webroot
boxlang-miniserver --port 80 --webroot /var/www

# Custom port and server home
boxlang-miniserver --port 80 --serverHome /var/www/servers/myServer

# Custom port and rewrites enabled
boxlang-miniserver --port 80 --rewrites

Environment Variables

The boxlang-miniserver 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 server HOME directory

BOXLANG_HOST = ip or domain

Override the localhost default to whatever IP or domain you like.

BOXLANG_PORT = 8080

Override the default port

BOXLANG_REWRITES = boolean

Enable or disable URL rewrites

BOXLANG_REWRITE_FILE = file.bxm

Choose the rewrite file to use. By default, it uses index.bxm

BOXLANG_WEBROOT = path

Override the location of the web root

BOXLANG_MINISERVER_OPTS = jvmOptions

A list of Java options to pass to the startup command

Environment variables are scanned first, then the command arguments. Thus, the command arguments take precedence.

Using 3rd Party Jars

You can load up custom third-party JARs into the runtime in two ways

BOXLANG_HOME/lib - You can place all the jars that the runtime will load in this location
1. Remember, you can use the --serverHome to choose the location of the server's home
Add via the classpath to your runner.

Please note that if you use the -cp approach, then you need to use a full java -cp syntax or you can customize the boxlang-miniserver shell scripts to do your bidding.

If you want to test 3rd part libs with the web server, you’ll need to use a different syntax that uses the -cp (classpath) JVM arg and specifies both the boxlang jar AND a semicolon-delimited list of the jars you want to use. It’s a little annoying, but this is how Java works.

# Format
java -cp {jarpath;jarpath2} ortus.boxlang.web.MiniServer


# Example
java -cp boxlang-miniserver-1.0.0.jar;/path/to/my.jar;/path/to/another.jar ortus.boxlang.web.MiniServer

Modules

The MiniServer can use any module you install into the OS home via the install-bx-module binary. However, if you choose your own server home using the server-home argument or the environment variable. Then, place the modules inside a modules directory inside the server's home.

JVM Options

You can use the BOXLANG_MINISERVER_OPTS env variable to seed the Java arguments the miniserver will start with.

BOXLANG_MINISERVER_OPTS="-Xmx512m"
boxlang-miniserver

Runtime Source Code

We welcome any pull requests, testing, docs, etc.

Variable Scopes

They gotta exist somewhere!

In the BoxLang language, many persistence and visibility scopes exist for variables to be placed in. These are differentiated by context: in a class, function, tag module, thread, or template. These scopes are Java maps but enhanced to provide case-insensitivity, member functions and more.

This idea that the variables you declare in templates, classes, and functions are stored in a structure makes your code highly flexible since you can interact with the entire scope fluently and with many different BIFs available. You can also bind them to function calls, attributes, etc. Thus, it capitulates on BoxLang being a dynamic language.

// Examples

/**
 * Get the state representation of the scheduler task
 */
function getMemento(){
	// I can do a filter on an entire scope
	return variables.filter( ( key, value ) => {
		return isCustomFunction( value ) || listFindNoCase( "this", key ) ? false : true;
	} );
}


// Argument binding
results = matchClassRules( argumentCollection = arguments );
results = matchClassRules( argumentCollection = myMap );

// I can dump entire scopes
writedump( variables )

The only language keyword that can be used to tell the variable to store in a function's local scope is called var. However, you can also just use the localscope directly or none at all. However, we do recommend being explicit on some occasions to avoid ambiguity.

It's a good idea to scope variables to avoid scope lookups, which could in turn create issues or even leaks.

function getData(){
	// Placed in the function's local scope
	var data = "luis"
	// Also placed in the function's local scope
	data = "luis"
	// Also placed in the function's local scope
	local.data = "luis"
}

Scripts & Template Scopes (bxm,bxs)

All scripts and templates have the following scopes available to them. Please note that the variablesscope can also be implicit. You don't have to declare it.

variables - The default or implicit scope to which all variables are assigned.

a = "hello"
writeOutput( a )

// Is the same as
variables.a = "hello"
writeOutput( variables.a )

Class Scopes (bx)

All classes in BoxLang follow Object-oriented patterns and have the following scopes available. Another critical aspect of classes is that all declared functions will be placed in a visibility scope.

variables - Private scope, visible internally to the class only
this - Public scope, visible from the outside world
static - Store variables in the classes blueprint and not the instance
super- Only available if you use inheritance

class extends="MyParent"{
    
    static {
        className = "MyClass"
    }
    
    variables.created = now()
    this.PUBLIC = "Hola"

    function init(){
        super.init()
    }
    
    function main(){
        println( "hello #static.className#" )
    }

}

Class Function Scopes

Depending on the function's visibility, BoxLang places a pointer for the function in the different scopes below. Why? Because BoxLang is a dynamic language. Meaning at runtime, you can add/remove/modify functions if you want to.

Private Function
- variables
Public or Remote Functions
- variables
- this

// Try it out
class {

    function main(){
        writedump( var: this, label: "public" );
        writedump( var: variables, label: "private" );
    }
    
    private function test(){}
    public function hello(){}

}

Templates/Scripts Function Scopes

All user-defined functions declared in templates or scripts will have the following scopes available:

variables - Has access to private variables within a Class or Page
local - Function-scoped variables only exist within the function execution. Referred to as var scoping. The default assignment scope in a function.
arguments - Incoming variables to a function

function sayHello( required name ){
    var fullName = "Hello #arguments.name#"
    // case insensitive
    return FULLNAME
}

writeOutput( sayHello( "luis" ) )

Closure Scopes

All closures are context-aware. Meaning they know about their birthplace and surrounding scopes. If closures are used in side classes, then they will have access to the class' variablesand thisscope.

variables - Has access to private variables from where they were created (Classes, scripts or templates)
this - Has access to public variables from where they were created (Classes)
local - Function-scoped variables only exist within the function execution. Referred to as var scoping. The default assignment scope in a function.
arguments - Incoming variables to a function

variables.CONSTANT = 1.4

// Define a closure that returns another function
function makeMultiplier( factor ) {
    return ( number ) => number * factor * variables.CONSTANT;
}

// Create multiplier functions using closures
double = makeMultiplier( 2 )
triple = makeMultiplier( 3 )

// Call the closure functions
println( double( 5 ) )  // Output: 10
println( triple( 5 ) )  // Output: 15

// Closures can also capture outer variables
function counter() {
    var count = 0;
    return () => {
        count++
        return count
    };
}

increment = counter()
println( increment() )  // Output: 1
println( increment() )  // Output: 2
println( increment() )  // Output: 3

Lambdas (Pure Function) Scopes

Lambdas are pure functions in BoxLang, they do not carry their surrounding or birth context. They are simpler and faster.

local - Function-scoped variables only exist within the function execution. Referred to as var scoping. The default assignment scope in a function.
arguments - Incoming variables to a function

// Define a simple lambda that squares a number
square = (x) -> x * x

println( square( 4 ) ) // Output: 16
println( square( 5 ) ) // Output: 25

// Lambda that adds two numbers
add = (a, b) -> a + b

println( add( 10, 20 ) ) // Output: 30

// Using a lambda to filter even numbers
numbers = [1, 2, 3, 4, 5, 6]
evens = numbers.filter( (n) -> n % 2 == 0 )

println( evens ) // Output: [2, 4, 6]


// Sorting a list in descending order
numbers = [3, 1, 4, 1, 5, 9]
numbers.sort( (a, b) -> b - a )

println( numbers ) // Output: [9, 5, 4, 3, 1, 1]

The following will throw an exception as it will try to reach outside of itself:

function testLambdaScope() {
    localVar = "I am local"

    // This lambda will fail because it tries to access localVar
    brokenLambda = () -> localVar 

    println( brokenLambda() ) // This will cause an error
}

testLambdaScope()

Custom Component Scopes

In BoxLang, you can extend the language and create your own custom components that can be used in script or templating syntaxes. They allow you to encapsulate behavior that can wrap up anything.

attributes - Incoming component attributes
variables - The default scope for variable assignments inside the component
caller - Used within a custom component to set or read variables within the template that called it.

// Call a component using script
bx:component template="path/MyComponent.bxm" name="luis"{
    // Content here or more component calls or whatever
}

// Call a component in the templating language: thus looks like custom tags
<bx:component template="path/MyComponent.bxm" name="luis">
    More content
</bx:component>

Here is the component:

path/MyComponent

<bx:param name="attributes.name" default="nobody">
<bx:set fullName = "Welcome #attributes.name#">

<cfoutput>
Hello from Component world #fullName#
</cfoutput>

We highly discourage peeking out of your component using the callerscope, but it can sometimes be beneficial. Use with caution.

Thread Scopes

When you create threads with the threadcomponent, you will have these scopes:

attributes - Passed variables via a thread
thread - A thread-specific scope that can be used for storage and retrieval. Only the owning thread can write to this scope. All other threads and the main thread can read the variables.
local - Variables local to the thread context
variables - The surrounding declared template or class variablesscope
this- The surrounding declared class scope

bx:thread 
    name="exampleThread" 
    message="Hello from the thread!"
{
    
    // You can use var, local or none
    var incomingMessage = attributes.message

    // Defining local variables inside the thread
    local.threadLocalVar = "This is a local thread variable"
    threadLocalVar2 = "Another local var"

    // Setting variables in the thread scope (can be accessed after completion)
    // Only this thread can write to it.
    thread.finalMessage = "Thread has completed execution!"
    thread.calculationResult = 42

    println( "Thread is running..." )
    println( "Incoming Message: " & incomingMessage )
    println( "Local Variable in Thread: " & threadLocalVar )
}

// Wait for the thread to finish before accessing thread scope variables
threadJoin( "exampleThread" )

// Accessing thread scope variables after execution
println( "Thread Final Message: " & bxthread.exampleThread.finalMessage )
println( "Thread Calculation Result: " & exampleThread.calculationResult )

Evaluating Unscoped Variables

If you use a variable name without a scope prefix, BoxLang checks the scopes in the following order to find the variable:

Local (function-local, UDFs and Classes only)
Arguments
Thread local (inside threads only)
Query (not a true scope; variables in query loops)
Thread
Variables
CGI
CFFILE
URL
Form
Cookie
Client

IMPORTANT: Because BoxLang must search for variables when you do not specify the scope, you can improve performance by specifying the scope for all variables. It can also help you avoid nasty lookups or unexpected results.

Persistence Scopes

Can be used in any context, used for persisting variables for a period of time.

session - stored in server RAM or external storages tracked by unique web visitor
client - stored in cookies, databases, or external storages (simple values only)
application - stored in server RAM or external storage tracked by the running BoxLang application
cookie - stored in a visitor's browser
server - stored in server RAM for ANY application for that BoxLang instance
request - stored in RAM for a specific user request ONLY
cgi - read only scope provided by the servlet container and BoxLang
form - Variables submitted via HTTP posts
URL - Variables incoming via HTTP GET operations or the incoming URL

Operators

Operate all things++--==!^%/\

Operators are the foundation of any programming language. Operators are symbols that help a programmer to perform specific mathematical, structuring, destructuring, and logical computations on operands (variables or expressions). We can categorize the BoxLang operators into the following categories:

Arithmetic/Mathematical
Assignment
Logical
Comparison
Ternary
Elvis (Null Coalescing)
Function
Collections

BoxLang does not offer the capability to overload operators like other languages.

Operator Precedence

The order of precedence exists in BoxLang, just like in mathematics. You can also control the order of precedence by using the grouping operator () like in mathematics, the magical ordering parenthesis.

^
*, /
\
MOD
+, -
&
EQ, NEQ, LT, LTE, GT, GTE, CONTAINS, DOES NOT CONTAIN, ==, !=, >, >=, <, <=
NOT, !
AND, &&
OR, ||
XOR
EQV
IMP

Remember that using parenthesis (Grouping Operator) is very important to denote precedence.

Arithmetic Operators

These operators are used to perform arithmetic/mathematical operations on operands.

Operator

Name

Description

+

Add

a = 1 + 4

-

Subtract

a = 4 - 2

*

Multiply

a = 4 * b

/

Divide

a = 4 / myVariable

^

Exponentiate

a = 2^2 // 4

%, MOD

Modulus / Remainder

5 % 2 = 1 or 5 mod 2

\

Integer Divide

a = 7 \ 3 is 2. Please note it does not round off the integer.

++

Increment

a = b++ assign b to a and THEN increment b a = ++b increment b and THEN assign to a

--

Decrement

a = b-- assign b to a and THEN decrement b a = --b decrement b and THEN assign to a

-

Negate

a = -b Negate the value of b

+

Positive

a = +b Make the value of b a positive number

()

Grouping

The grouping operator is used just like in mathematics, to give precedence to operations. result = 3 * (2+3) which is not the same as result = 3 * 2 + 3

Bitwise Operators

These operators are used to perform bitwise operations on operands.

The bitwise operators look a bit different in BoxLang vs other languages like Java since the normal bitwise operators are already used for other purposes in BoxLang.

Operator

Name

Description

b|

Bitwise OR

a = 12 b| 25

b&

Bitwise AND

a = 5 b& 9

b^

Bitwise XOR

a = 10 b^ 12

b~

Bitwise Complement

a = b~ 35

b<<

Bitwise Signed Left Shift

a = 14 b<< 4

b>>

Bitwise Signed Right Shift

a = 4 b>> 2

b>>>

Bitwise Unsigned Right Shift

a = 25 b>>> 3

Assignment Operators

These operators are usually used for compound evaluations and assignments.

Operator

Name

Description

=

Assignment

a = 5 The way to assign a value to a variable. You can also assign them to multiple variables by chaining them: a=b=c=5 which is the same as saying: a=5;b=5;c=5

+=

Compound Add

a += b is equivalent to a = a + b

-=

Compound Substract

a -= b is equivalent to a = a - b

*=

Compound Multiply

a *= b is equivalent to a = a * b

/+

Compound Divide

a /= b is equivalent to a = a / b

%=

Compound Modulus

a %= b is equivalent to a = a % b

&=

Compound Concatenation

A way to concatenate strings together a = "hello " a &= "luis" The result will be hello luis

&

Concatenation

Concatenates two strings: "Hola" & space & "Luis"

Logical Operators

Logical operators perform logic between values or values, usually denoting a boolean result.

Operator

Name

Description

!,NOT

Negation

!true = false or a = not true

&&,AND

And

Returns true if both operands are true. a = b && c

||, OR

Returns true if either operand is true. a = b

XOR

Exclusive Or

Returns true when either of the operands is true (one is true, and the other is false), but both are not true, and both are not false. true XOR true = false true XOR false = true false XOR false = false

EQV

Equivalence

The exact opposite of an exclusive or. Meaning that it will return true when both operands are either true or false. true EQV true = true true EQV false = false false EQV false = true

IMP

Implication

A implies B is equivalent to if a then b. A imp b is false ONLY if a is true and b is false; else, it returns true always.

Comparison Operators

Comparison operators are used when comparing two values, expressions, or variables. The return of a comparison is either true or false.

Operator

Name

Description

eq, ==

Equality

True if a eq b or a == b

neq, !=, <>

Not Equal

The opposite of equality: a neq b, a != b, a <> b

===

Identity

Returns true if the operands are equal in value and in type. 2 === "2" // false 2 === 2 // true

!===

Negated Identity

Same as the identity operator but negating the result.

gt, >

Greater than

If the left operand is greater in value than the right operand

gte, >=

Greater than o equal

If the left operand is greater than or equal in value than the right operand

lt, <

Less than

If the left operand is less than in value than the right operand

lte, <=

Less than or equal

If the left operand is less than or equal in value than the right operand

contains, ct

Contains

Returns true if the left operand contains the right one. 'hello' contains 'lo'

does not contain, nct

Negated contains

Returns true if the left operand does NOT contain the right one. 'hello' does not contain 'pio'

assert

Assert an expression

Evaluate an expression and if the expression is falsey it will throw an assert exceptions.

Assert Statement

BoxLang offers an assert statement that will evaluate an expression, and if the expression is falsey, it will throw an assert exception.

// Asserts that the name is truthy
assert name;

// Assert an expression
assert myService.hasData();
assert name.length() > 3;

// Assert a lambda/closure result.
assert ()-> { do something }
assert ()=> { do something }

Ternary Operator

The ternary operator is a conditional operator that works just like an if-then-else statement but in shorthand syntax. It has three operands:

condition ? value1 if true : value2 if false

The condition must evaluate to a Boolean value. If true then the value1 will be used, or else value2 will be used. You can combine this operator with parenthesis, Elvis operators, etc., to build rich expressions.

result = ( 10 > 0 ) ? true : false
result = animal eq 'dog' ? 'bark' : 'not a dog'

// More complex approach
result = creditScore > 800 ? "Excellent" :
    ( creditScore > 700 ) ? "Good" :
    ( creditScore > 600 ) ? "Average" : "Bad"

Elvis Operator (Null Coalescing)

expression ?: defaultValueOrExpression

Here is a simple example:

function process( result ){
    writeOutput( result ?: "nothing passed" )
}
process() // produces 'nothing passed'
process( "hello" ) // produces 'hello'

displayName = rc.name ?: 'Anonymous'

event
    .getResponse()
    .setError( true )
    .setData( rc.id ?: "" )

Function Expressions

In BoxLang, a function invocation can be used as an expression, where the results of the function call is the effective value used.

results = ucase( "this is text " ) & toString( 12 + 50 )

Function is also a proper type, allowing a reference to a function to be passed as an argument to another function or returned from another function as the return value. Functions which accept or return other functions are called higher order functions**.

// I can also pass lambdas or anonymous functions as arguments
results = listener( 2 * 3, (result) => result + 1 )

Collections Operators

Many operators can work on collection objects like arrays, structs, and queries. So let's start investigating them.

var user = userService.findById( id )
// If user is not found, then this will still work but no exception is thrown.
echo( user?.getSalary() )

s = { name : "luis" }
echo( s.name )
echo( s?.name )

Spread Operator

Feature coming soon

The spread operator allows an iterable object to expand and merge in certain declarations in code. These objects in BoxLang are mostly arrays and structures. This operator can quickly merge all or parts of an existing array or object into another array or object. This operator is used by leveraging three dots ... in specific expressions.

// Spread
var variableName = [ ...myArray ]
// Traditional
var variableName = [].append( myArray )

// Spread
var mergedObject = { ...obj1, ...obj2 }
// Traditional
mergedObject.append( obj1 ).append( obj2 )

You can accomplish the result of the spread operator with the append() member function or traditional function in a very elegant and user-friendly syntax. It also allows you NOT to do chaining but inline expressions.

,The Spread syntax also allows an iterable such as an array expression or string, to be expanded in places where zero or more arguments (for function calls) are expected. Here are some examples to help you understand this operator:

Function Calls

numbers = [ 1, 2, 3 ]
function sum( x, y, z ){
    return x + y + z;
}
// Call the function using the spread operator
results = sum( ...numbers ) // 6

// Ignore the others
numbers = [ 1, 2, 3, 4, 5 ]
results = sum( ...numbers ) // 6

Array Definitions

numbers = [ 1, 2, 3 ]
myArray = [ 3, 4, ...numbers ]
myArray2 = [ ...numbers ]
myArray2 = [ ...numbers, 4, 66 ]

Struct Definitions

var mergedObject = { ...obj1, ...obj2 }

user1 = { name : "luis", age: 15 }
user2 = { name : "joe", location : "miami" }

mergedUsers = { ...user1, ...user2 }
// What will the output be?
writeDump( mergedUsers )
// { name : "joe" , age : 15, location : "miami" }

Rest Operator

Feature coming soon

The Rest function operator is similar to the Spread Operator but behaves oppositely. The spread syntax expands the iterable constructs into individual elements, and the Rest syntax collects and condenses them into a single construct, usually an array.

Imagine I need to create a function that takes in an unlimited number of Identifiers so I can return all items that have that ID:

function findById( ...ids ){
}

findById( 1 ) // ids is a single value of 1
findById( 1, 23, 34, 456 ) // ids is an array of values

You can also combine them in functions with other arguments:

function findById( entityName, ...ids ){
}

findById( "User", 1 ) // ids is a single value of 1
findById( "Car", 1, 23, 34, 456 ) // ids is an array of values

Structures

Collection of key-value pairs; a data dictionary

A structure is a collection of data where each element of data is addressed by a name or key and it can hold a value of any type. Like a dictionary but on steroids:

// Create a struct via function
myStruct = structnew()

// Create a struct via literal syntax
myStruct = {}

Tip Underneath the hood, all BoxLang structures are based on the java.util.Map interface. So if you come from a Java background, structures are untyped HashMaps.

As an analogy, think about a refrigerator. If we’re keeping track of the produce inside the fridge, we don’t really care about where the produce is in, or basically: order doesn’t matter. Instead, we organize things by name, which are unique, and each name can have any value. The name grapes might have the value 2, then the name lemons might have the value 1, and eggplants the value 6.

All BoxLang structures are passed to functions as memory references, not values. Keep that in mind when working with structures. There is also the passby=reference|value attribute to function arguments where you can decide whether to pass by reference or value.

Key-Value Pairs

A structure is an unordered collection where the data gets organized as a key and value pair. BoxLang syntax for structures follows the following syntax:

produce = {
    grapes     = 2,
    lemons     = 1,
    eggplants  = 6
};

Tip Please note that = sign and : are interchangeable in BoxLang. So you can use any to define your structures.

Since BoxLang is a case-insensitive language, the above structure will store all keys in uppercase. If you want the exact casing to be preserved in the structure, then surround the keys with quotes (").

The exact casing is extremely important if you will be converting these structures into JSON in the future.

produce = {
    "grapes"     = 2,
    "lemons"     = 1,
    "eggplants"  = 6
};

The key is the address, and the value is the data at that address. Please note that the value can be ANYTHING. It can be an array, an object, a simple value, or even an embedded structure. It doesn't matter.

Retrieving Values

Retrieving values from structures can be done via dot or array notation or the structFind() function. Let's explore these approaches:

Array Notation

writeOutput( "I have #produce[ "grapes" ]# grapes in my fridge!" );
writeOutput( "I have #produce[ "eggplants" ]# eggplants in my fridge!" );

Dot Notation

writeOutput( "I have #produce.grapes# grapes in my fridge!" );
writeOutput( "I have #produce.eggplants# eggplants in my fridge!" );

structFind( structure, key, [defaultValue ] )

// Member Function
writeOutput( "I have #produce.find( "grapes" )# grapes in my fridge!" );
writeOutput( "I have #produce.find( "eggplants" )# eggplants in my fridge!" );

// Global Function
writeOutput( "I have #structFind( produce, "grapes" )# grapes in my fridge!" );
writeOutput( "I have #structFind( produce, "eggplants" ) eggplants in my fridge!" );

However, please be aware that when dealing with native Java hashmaps, we recommend using array notation as the case is preserved in array notation, while in dot notation, it does not.

user = { age : 40 }

echo( user.age ) // 40
echo( user.salary ) // throws exception
echo( user?.salary ) // nothing, no exception
echo( user?.salary ?: 0 ) // 0

Setting Values

// new key using default uppercase notation
produce.apples = 3;
// new key using case sensitive key
produce[ "apples" ] = 3;

// I just ate one grape, let's reduce it
produce[ "grapes" ] = 1; // or
produce.grapes--;

produce.insert( "newVeggie", 2 )
produce.update( "newVeggie", 1 )

structInsert( produce, "carrots", 5 )
structUpdate( produce, "carrots", 2 )

Tip You can use the toString() call on any structure to get a string representation of its keys+values: produce.toString()

Checking Contents & Size

BoxLang also offers some useful methods when dealing with structures:

Function

Member Function

structIsEmpty()

isEmpty()

structCount()

count()

Key Values & Existence

Here are some great functions that deal with getting all key names, and key values or checking for existence:

Function

Member Function

structKeyArray()

keyArray()

structKeyList()

keyList()

structKeyExists()

keyExists()

produce.keyArray()
    .each( (item) => echo( item ) )

writeOutput( "My shopping bag has: #produce.keyList()# " )
writeOutput( "Do you have carrots? #produce.keyExists( 'carrots' )#" )

Structure Types

case-sensitive
normal
ordered or linked
ordered-case-sensitive
soft
synchronized
weak

Here is the signature for the structnew() function:

structNew( [type[[,sortType][,sortOrder][,localeSensitive]|[,callback]]] )

structNew( [type, [onMissingKey] ] )

Now let's create some different types of structures

produce = structNew();
pickyProduce = structNew( "casesensitive" )

queue = structNew( "ordered" )
pickyQueue = structNew( "ordered-casesensitive" )
linkedList = structNew( 'ordered' );
cache = structnew( 'soft' );

Literal Syntax

You can also use literal syntax for some of these types:

// ordered struct
myStruct = [:] or [=]

Common Methods

As you can see, there are many cool methods for detecting keys, values, lengths, counts, etc. A very cool method is keyArray() which gives you the listing of keys as an array:

Looping Over Structures

You can use different constructs for looping over structures:

for loops
loop constructs
each() closures

for( var key in produce ){
 systemOutput( "I just had #produce[ key ]# #key#" );
}

produce.each( function( key, value ){
  systemOutput( "I just had #value# #key#" );
} );

Multi-Threaded Looping

BoxLang allows you to leverage the each() operations in a multi-threaded fashion. The structEach() or each() functions allow for a parallel and maxThreads arguments so the iteration can happen concurrently on as many maxThreads as supported by your JVM.

structEach( struct, callback, parallel:boolean, maxThreads:numeric );
each( collection, callback, parallel:boolean, maxThreads:numeric );

This is incredibly awesome as now your callback will be called concurrently! However, please note that once you enter concurrency land, you should shiver and tremble. Thread concurrency will be of the utmost importance, and you must ensure that var scoping is done correctly and that appropriate locking strategies are in place.

myStruct.each( function( key, value ){
   myservice.process( value );
}, true, 20 );

Even though this approach to multi-threaded looping is easy, it is not performant and/or flexible. Under the hood, the BoxLang uses a single thread executor for each execution, do not allow you to deal with exceptions, and if an exception occurs in an element processor, good luck; you will never know about it. This approach can be verbose and error-prone, but it's easy. You also don't control where the processing thread runs and are at the mercy of the engine.

ColdBox Futures Parallel Programming

If you would like a functional and much more flexible approach to multi-threaded or parallel programming, consider using the ColdBox Futures approach (usable in ANY framework or non-framework code). You can use it by installing ColdBox or WireBox into any BoxLang application and leveraging our async programming constructs, which behind the scenes, leverage the entire Java Concurrency and Completable Futures frameworks.

Here are some methods that will allow you to do parallel computations:

all( a1, a2, ... ):Future : This method accepts an infinite amount of future objects, closures, or an array of closures/futures to execute them in parallel. When you call on it, it will return a future that will retrieve an array of the results of all the operations.
allApply( items, fn, executor ):array : This function can accept an array of items or a struct of items of any type and apply a function to each of the items in parallel. The fn argument receives the appropriate item and must return a result. Consider this a parallel map() operation.
anyOf( a1, a2, ... ):Future : This method accepts an infinite amount of future objects, closures, or an array of closures/futures and will execute them in parallel. However, instead of returning all of the results in an array like all(), this method will return the future that executes the fastest! Race Baby!
withTimeout( timeout, timeUnit ) : Apply a timeout to all() or allApply() operations. The timeUnit can be days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds.

Trailing Commas

BoxLang supports trailing commas when defining array and struct literals. Just in case you miss a dangling comma, we won't shout at you!

myArray = [
    "BoxLang",
    "ColdBox",
    "TestBox",
    "CommandBox",
]
println( myArray )

myStruct = {
    name: "BoxLang",
    type: "JVM Dynamic Language",
    version: "1.0.0",
}
println( myStruct )

Arrays

An array is a data structure consisting of a collection of elements.

An array is a number-indexed list. Imagine you had a blank piece of paper and drew a set of three small boxes in a line:

 ---  ---  ---
|   ||   ||   |
 ---  ---  ---

You could number each one by its position from left to right:

 ---  ---  ---
|   ||   ||   |
 ---  ---  ---
  1    2    3

Then put strings in each box:

 -------------  ---------  ----------
| "Breakfast" || "Lunch" || "Dinner" |
 -------------  ---------  ----------
       1            2           3

We have a three-element Array. BoxLang arrays can grow and shrink dynamically at runtime, just like Array Lists or Vectors in Java, so if we added an element, it’d usually go on the end or be appended at the end.

 -------------  ---------  ----------  -----------
| "Breakfast" || "Lunch" || "Dinner" || "Dessert" |
 -------------  ---------  ----------  -----------
       1            2           3           4

If you asked the array for the element in position two, you’d get back Lunch. Ask for the last element, and you’ll get back: Dessert.

The Story of One

Now, have you detected something funny with the ordering of the elements? Come on, look closer....... They start with 1 and not 0, now isn't that funny. BoxLang is one of the few languages where array indexes start at 1 and not 0. So if you have a PHP, Ruby, or Java background, remember that 1 is where you start. Is this good or bad? Well, we will refrain from pointing fingers for now.

All arrays in BoxLang are passed by passed by reference. Please remember this when working with arrays and passing them to functions. There is also the passby=reference|value attribute to function arguments where you can decide whether to pass by reference or value.

Arrays in Code

Let's go ahead and model some code in BoxLang using our fancy REPL tool CommandBox:

Check it out:

The array was created by putting pieces of data between square brackets ([]) and separated by commas
We added an element to the array using the member function append()
We fetched the element at a specific position by using square brackets ([ x ]) and replaced x with the index, we wanted
We retrieved the size of the array by using the member function len()
We searched the contents of the array using the member function findNoCase() , and it gave us the index position of the element in the array.

Tip: You can use the toString() call on any array to get a string representation of its values: grid.toString()

Multi-Dimensional Arrays

To create grids or matrix constructs, you must create two-dimensional arrays. This gives you an x and y axis of data. You will do so using the arrayNew( dimensions = max 3 ) method:

grid = arrayNew( 2 );
grid[ 1 ][ 1 ] = 'Hammer';
grid[ 1 ][ 2 ] = 'Nail';
grid[ 2 ][ 1 ] = 'Screwdriver';
grid[ 1 ][ 2 ] = 'Screw';

Tip: BoxLang only supports two and three-dimensional arrays, so you can easily represent x, y, and z axis.

Common Methods

// Sort an array
meals.sort( "textnocase" );

// Clear the array
meals.clear();

// Go on a diet
meals.delete( "Dessert" );
meals.deleteAt( 4 );

// Iterate
meals.each( function( element, index) {
   systemOutput( element & " " & index );
} );

// Filter an array
meals.filter( function( item ){
 return item.findNoCase( "unch" ) gt 0 ? true : false;
} );

// Convert to a list
meals.toList();

// Map/ Reduce
complexData = [ {a: 4}, {a: 18}, {a: 51} ];
newArray = arrayMap( complexData, function(item){
   return item.a;
});
writeDump(newArray);

complexData = [ {a: 4}, {a: 18}, {a: 51} ];
 sum = arrayReduce( complexData, function(prev, element)
 {
 return prev + element.a;
 }, 0 );
writeDump(sum);

Negative Indices

BoxLang also supports the concept of negative indices. This allows you to retrieve the elements from the end of the array backward. So you can easily count back instead of counting forwards:

numbers = [1,2,3,4,5]

writedump( numbers[ -1 ] ) // 5
writedump( numbers[ -2 ] ) // 4
writedump( numbers[ -3 ] ) // 3
writedump( numbers[ -4 ] ) // 2
writedump( numbers[ -5 ] ) // 1
writedump( numbers[ -6 ] ) // EXCEPTION!!! Array index out of range

Array Slices

// Signature
arraySlice( array, offset, length )
// Member method
array.slice( offset, length )

Tip: You can also use negative offsets.

array = [ 1, 2, 3, 4, 5, 6, 7, 8 ]
newArray = array.slice( 2, 3 )
println( newArray ) // [ 2, 3, 4 ]

Looping Over Arrays

You can use different constructs for looping over arrays:

for loops
loop constructs
each() closures

for( var thisMeal in meals ){
 systemOutput( "I just had #thisMeal#" );
}

for( var x = 1; x lte meals.len(); x++ ){
 systemOutput( "I just had #meals[ x ]#" );
}

meals.each( function( element, index ){
  systemOutput( "I just had #element#" );
} );

bx:loop( from=1, to=meals.len(), index=x ){
  systemOutput( "I just had #meals[ x ]#" );
}

Multi-Threaded Looping

BoxLang allows you to leverage the each() operations in a multi-threaded fashion. The arrayEach() or each() functions allow for a parallel and maxThreads arguments so the iteration can happen concurrently on as many maxThreads as supported by your JVM.

arrayEach( array, callback, parallel:boolean, maxThreads:numeric );
each( collection, callback, parallel:boolean, maxThreads:numeric );

This is incredibly awesome, as your callback will now be called concurrently! However, please note that once you enter concurrency land, you should shiver and tremble. Thread concurrency will be of the utmost importance, and you must ensure that var scoping is done correctly and that appropriate locking strategies are in place when accessing shared scopes and/or resources.

myArray.each( function( item ){
   myservice.process( item );
}, true, 20 );

Even though this approach to multi-threaded looping is easy, it is not performant and/or flexible. Under the hood, the engine uses a single thread executor for each execution. They do not allow you to deal with exceptions, and if an exception occurs in an element processor, good luck; you will never know about it. This approach can be verbose and error-prone, but it's easy. You also don't control where the processing thread runs and are at the mercy of the engine.

ColdBox Futures Parallel Programming

Here are some methods that will allow you to do parallel computations:

all( a1, a2, ... ):Future : This method accepts an infinite amount of future objects, closures, or an array of closures/futures to execute them in parallel. When you call on it, it will return a future that will retrieve an array of the results of all the operations.
allApply( items, fn, executor ):array : This function can accept an array of items or a struct of items of any type and apply a function to each item in parallel. The fn argument receives the appropriate item and must return a result. Consider this a parallel map() operation.
anyOf( a1, a2, ... ):Future : This method accepts an infinite amount of future objects, closures, or an array of closures/futures and will execute them in parallel. However, instead of returning all of the results in an array like all(), this method will return the future that executes the fastest! Race Baby!
withTimeout( timeout, timeUnit ) : Apply a timeout to all() or allApply() operations. The timeUnit can be days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds.

// Let's find the fastest dns server
var f = asyncManager().anyOf( ()=>dns1.resolve(), ()=>dns2.resolve() );

// Let's process some data
var data = [1,2, ... 100 ];
var results = asyncManager().all( data );

// Process multiple futures
var f1 = asyncManager.newFuture( function(){
    return "hello";
} );
var f2 = asyncManager.newFuture( function(){
    return "world!";
} );
var aResults = asyncManager.newFuture()
    .withTimeout( 5 )
    .all( f1, f2 );

// Process mementos for an array of objects
function index( event, rc, prc ){
    return async().allApply(
        orderService.findAll(),
        ( order ) => order.getMemento()
    );
}

Spread Operator

Coming soon, still in development

Arrays also allow the usage of the spread operator syntax to quickly copy all or part of an existing array or object into another array or object. This operator is used by leveraging three dots ... in specific expressions.

The Spread syntax allows an iterable such as an array expression or string, to be expanded in places where zero or more arguments (for function calls) or elements (for array literals) are expected. Here are some examples to help you understand this operator:

Function Calls

numbers = [ 1, 2, 3 ]
function sum( x, y, z ){
    return x + y + z;
}
// Call the function using the spread operator
results = sum( ...numbers ) // 6

// Ignore the others
numbers = [ 1, 2, 3, 4, 5 ]
results = sum( ...numbers ) // 6

Array Definitions

numbers = [ 1, 2, 3 ]
myArray = [ 3, 4, ...numbers ]
myArray2 = [ ...numbers ]
myArray2 = [ ...numbers, 4, 66 ]

Rest Operator

Coming soon, still in development

The rest operator is similar to the spread operator but behaves oppositely. Instead of expanding the literals, it contracts them into an array you designate via the ...{name} syntax. You can use this to define endless arguments for a function, for example. In this case, I can create a dynamic findBy function that takes in multiple criteria name-value pairs.

function findBy( ...args ){
    writeDump( args )
}
findBy( 1, 2, 3, 4, 5 )

function findBy( entityName, ...args ){
    writeDump( args )
}
findBy( "Luis", 1, 2, 3, 4, 5 )

Trailing Commas

BoxLang supports trailing commas when defining array and struct literals. Just in case you miss a dangling comma, we won't shout at you!

myArray = [
    "BoxLang",
    "ColdBox",
    "TestBox",
    "CommandBox",
]
println( myArray )

myStruct = {
    name: "BoxLang",
    type: "JVM Dynamic Language",
    version: "1.0.0",
}
println( myStruct )

Queries

BoxLang provides the easiest way to query a database

CFML became famous in its infancy because it was easy to query databases with a simple cfquery tag and no verbose ceremonious coding. There is no ceremony, just a plain datasource definition in the administrator, and we could easily query the database.

What is a query?

A query is a request to a database representing the results' rows and columns. It returns a BoxLang query object containing a record set and other metadata information about the query. The query can ask for information from the database, write new data to the database, update existing information in the database, or delete records from the database. This can be done in several ways:

Here's the tag syntax for a query using a named "pantry" datasource:

Defining Datasources

The datasource configuration struct should be defined exactly the same whether you are using an inline, ad-hoc datasource or configuring a datasource in your boxlang.json or Application.bx. Make sure you have a "driver" key defined OR the driver clearly denoted in the JDBC url:

Displaying Results

The query object can be iterated on like a normal collection through a for, bx:loop or bx:output , each() constructs.

In a BXM Template

You leverage the bx:output tag by passing the query to it. Then in the block of the tag you use dot/array notation and interpolation to output the column you want. BoxLang will iterate over all rows in the query for you.

By specifying encodefor="html" each variable is encoded using the encodeForHTML function before it is output.

Using Loops

As you can see, many ways to iterate over the query exist. Choose the approach that suits your needs.

Multi-Threaded Looping

BoxLang allows you to leverage the each() operations in a multi-threaded fashion. The queryEach() or each() functions allow for a parallel and maxThreads arguments so the iteration can happen concurrently on as many maxThreads as supported by your JVM.

This is incredibly awesome, as now your callback will be called concurrently! However, please note that once you enter concurrency land, you should shiver and tremble. Thread concurrency will be of the utmost importance, and you must ensure that var scoping is done correctly and that appropriate locking strategies are in place.

ColdBox Futures Parallel Programming

Here are some methods that will allow you to do parallel computations:

all( a1, a2, ... ):Future : This method accepts an infinite amount of future objects, closures, or an array of closures/futures to execute them in parallel. When you call on it, it will return a future that will retrieve an array of the results of all the operations.
allApply( items, fn, executor ):array : This function can accept an array of items or a struct of items of any type and apply a function to each of the items in parallel. The fn argument receives the appropriate item and must return a result. Consider this a parallel map() operation.
anyOf( a1, a2, ... ):Future : This method accepts an infinite amount of future objects, closures, or an array of closures/futures and will execute them in parallel. However, instead of returning all of the results in an array like all(), this method will return the future that executes the fastest! Race Baby!
withTimeout( timeout, timeUnit ) : Apply a timeout to all() or allApply() operations. The timeUnit can be days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds.

Using Input

You can use the :varname notation in your SQL construct to denote a variable placeholder or ? to denote a positional placeholder. The bx:queryparam tag or the inline sqltype construct will bind the value to a specific database type to avoid SQL injection and to further the database explain plan via types. The available SQL binding types are:

bigint
bit
char
blob
clob
nclob
date
decimal
double
float
idstamp
integer
longvarchar
longnvarchar
money
money4
nchar
nvarchar
numeric
real
refcursor
smallint
sqlxml
time
timestamp
tinyint
varchar

Query Methods

queryNew()
queryAddRow()
queryAddColumn()
queryColumnArray()
queryColumnCount()
queryColumnData()
queryColumnExists()
queryColumnList()
queryCurrentRow()
queryDeleteColumn()
queryDeleteRow()
queryEach()
queryEvery()
queryFilter()
queryGetCell()
queryGetResult()
queryGetRow()
queryMap()
queryRecordCount()
queryReduce()
queryRowData()
querySetCell()
querySlice()
querySome()
querySort()
quotedValueList()
valueList()

Building Queries

You can use a combination of the methods above to create your own queries:

Query of Queries

Query a local database variable without going through your database is another great way to query an already queried query. Too many queries?

Please note that using a query of queries can be quite slow sometimes, not all the time. An alternative approach is to use modern queryFilter() operations to actually filter out the necessary data from a query or querySort(), etc.

Returning Arrays of Structs or Struct of Structs

You can also determine the return type of database queries as something other than the BoxLang query object. You can choose an array of structs or a struct of structs. This is fantastic for modern applications that rely on rich JavaScript frameworks and produce JSON.

QB = Query Builder

Using qb, you can:

Quickly scaffold simple queries
Make complex, out-of-order queries possible
Abstract away differences between database engines

BoxLang Query Options

BoxLang supports the following query options:

result - Name of the variable to store the query results in.
maxRows - Limit the number of rows retrieved from the database.
queryTimeout - Max execution time to allow the query to run before aborting with a query timeout error.
returnType - Return the result as an array, query, or struct.
fetchSize - Set a custom result set batch size to improve performance on large queries. Is equivalent to blockfactor in CFML, but matches the JDBC statement option name.
cache - Enable or disable caching
cacheKey - A unique string used to identify this query for caching purposes.
cacheProvider - Name of the cache provider used for caching this query. A default cache provider will be assigned if none set,
cacheTimeout - Max time, as a duration, to allow cached results to be returned.

blockfactor - alias for fetchSize
cacheID - alias for cacheKey
cacheRegion - alias for cacheProvider
cachedAfter - coerced to a cacheTimeout duration if the current datetime is "after" the cachedAfter value.
cachedWithin - alias for cacheTimeout, unless value is "request". Support planned for cachedWithin=request.

The following options are unimplemented, but support is planned:

cachedWithin=request
timezone
psq
dbtype=query
lazy

The following query options are unimplemented, with no support planned:

username
password
debug
clientInfo
fetchClientInfo
ormoptions

Conditionals

Operators

Conditional statements evaluate to true or false only. The most common conditional operators are == (equal), != (not equal), > (greater than), >= (greater than or equal to), < (less than), and <= (less than or equal to). You can also define the operators as abbreviations: EQ, NEQ, GT, GTE, LT, and LTE.

Some instructions return a true or false, so they're used in conditional statements, for example, IsArray which is true only when the variable is an "array". Structures have an instruction named structKeyExists() or keyExists() which returns true if a key is present in a structure. Strings can also be used for conditional operations by checking the .length() member function.

Also integers can be evaluated as true or false. In BoxLang, 0 (zero) is false and any other integers are true.

If, Else If, & Else

Why do we have conditional statements? Most often it's to control conditional instructions, especially if / else if / else expressions. Let's write an example by adding a method to our PersonalChef.bx class:

Try this example using 5, 7, 8 and 9 for the values of minutes.

When the minutes is 5, here is how the execution goes: Is it true that 5 is less than 7? Yes, it is, so print out the line The water is not boiling yet..
When the minutes is 7, it goes like this: Is it true that 7 is less than 7? No. Next, is it true that 7 is equal to 7? Yes, it is, so print out the line It's just barely boiling.
When the minutes is 8, it goes like this: Is it true that 8 is less than 7? No. Next, is it true that 8 is equal to 7? No. Next, is it true that 8 is equal to 8? Yes, it is, so print out the line It's boiling!.

Lastly, when total is 9, it goes:" Is it "true" that 9 is less than 7?

No. Next, is it true that 9 is equal to 7? No. Next, is it true that 9 is equal to 8? No. Since none of those are true, execute the else and print the line Hot! Hot! Hot!.

An if block has:

One if statement whose instructions are executed only if the statement is true
Zero or more else if statements whose instructions are executed only if the statement is true
Zero or one else statement whose instructions are executed if no if nor else if statements were true

Only one section of the if / else if / else structure can have its instructions run. If the if is true, for instance, BoxLang will never look at the else if. Once one block executes, that’s it.

Ternary Operator

The ternary operator is a compact way to do an if, else, else if expression statements. It is very common in other languages and can be used for a more fluent expressive conditional expression.

The way it works is that the condition is evaluated. If it is true, then the true statement executed; if it is false, then the false statement executes.

Please note that you can chain the trueStatement and the falseStatement into more tenrary operations. However, don't abuse it as they will look ugly and just be very complex to debug.

The output of the above statement will be..... true of course!

Elvis Operator

Before Elvis we had isDefined(), structKeyExists() and IF statements to do these kind of evaluations. They work, but not very expressive or concise.

The Elvis operator is primarily used to assign the right default for a variable or an expression Or it is a short-hand way to do parameterization. It will allow us to set a value if the variable is Null or does not exist.

For instance,

If userName does not exist or evaluates to null then the default value of the myName will be assigned the right part of the ?: elvis operator -> Anonymous

The safe navigation operator allows for you to navigate structures by not throwing the dreaded key not exists exception but returning an undefined or null value. You can then combine that with the elvis operator and create nice chainable struct navigation. For example instead of doing things like:

You can do things like this:

The hook operator (?) along with the dot operator (.) is known as safe navigation operator(?.). The safe navigation operator makes sure that if the variable used before the operator is not defined or java null, then instead of throwing an error, the operator returns undefined for that particular access.

Switch, Case, & Default

Another situation that involves conditional logic is when a single variable or expression that can have a variety of values and different statements or functions needed to be executed depending on what that value is. One way of handling this situation is with a switch / case / default block.

Much like how the if statement marks the start of an if block and contains one or more else if statements and perhaps one (and only one) else statement, the switch statement marks the start of a switch block and can contain multiple case statements and perhaps one (and only one) default statement.

The main difference is that switch / case / default can only evaluate the resulting value of a single variable or expression, while the if / else if / else block lets you evaluate the true or false result of different variables or expressions throughout the block.

Please note that you can create a body for the case statements with curly braces. As best practice, do so for all case and/or default blocks

While Loops

The while( conditional ) expression allows you to execute a code block as many times as the conditional expression evaluates to true. This is a great way to work with queues, stacks or just simple evaluations.

The `==` and `=` Common Mistake

The #1 mistake people encounter when writing conditional statements is the difference between = and ==.

= is an assignment. It means "take what's on the right side and stick it into whatever is on the left side" (or its telling not asking.)
== is a question. It means "is the thing on the right equal to the thing on the left" (or its asking not telling.)

Variables

name = "Amazing Programmer"

In BoxLang, variables are just pointers to a piece of data. They can hold any value you like and even change their value or type at runtime since BoxLang is a dynamic language. In some languages, you need to specify the type of data you want your variable to hold at compile-time and it can never change. You do not need to assign one in BoxLang, as everything is dynamic and/or inferred. It infers types according to the initial value you assign to your variable.

Please note that assignments are evaluated from right to left instead of traditional reading from left to right.

BIFs

Case Insensitive

BoxLang is a case-insensitive language as well. Meaning if you create a variable a and reference it as A they are the same. This can be a big gotcha for developers from languages like Java or JavaScript. However, as best practice, we would recommend ALWAYS using the same case as when you define the variable:

Don't do this

Do this

Naming Requirements

Most BoxLang variables have a few requirements imposed by the Virtual Machine (VM)

It must begin with a letter, underscore, or Unicode currency symbol.
It can contain letters, numbers, underscore characters, and Unicode currency symbols.
NO SPACES!
Not case-sensitive

Reserved Words

As with any programming language, there are specific names you can't use, and some you can use. Here are the rules:

The name of any of the internal BoxLang persistent scopes: form, session, cgi, client, url, application, function
- Technically you can create the variable by long scoping (local.form), but it is confusing and error-prone. So please be careful.
Reserved Operators
- AND
- EQ
- EQUAL
- EQV
- GE
- GREATER
- GT
- GTE
- IMP
- IS
- LE
- LESS
- LT
- LTE
- MOD
- NEQ
- NOT
- OR
- THAN
- XOR
Reserved Keywords
- ABSTRACT
- ANY
- ARRAY
- AS
- ASSERT
- BOOLEAN
- BREAK
- CASE
- CASTAS
- CATCH
- CLASS
- CONTAIN
- CONTAINS
- CONTINUE
- DEFAULT
- DO
- DOES
- ELIF
- ELSE
- FALSE
- FINAL
- FINALLY
- FOR
- FUNCTION
- IF
- IMPORT
- IN
- INCLUDE
- INSTANCEOF
- INTERFACE
- JAVA
- MESSAGE
- NEW
- NULL
- NUMERIC
- PACKAGE
- PARAM
- PRIVATE
- PROPERTY
- PUBLIC
- QUERY
- REMOTE
- REQUEST
- REQUIRED
- RETHROW
- RETURN
- SERVER
- SETTING
- STATIC
- STRING
- STRUCT
- SWITCH --> Could possibly be a var name, but not a function/method name
- THROW
- TO
- TRUE
- TRY
- TYPE
- VARIABLES
- VAR
- WHEN
- WHILE

Flexible Typing

You can also create a variable with one type and then switch it to another dynamically:

As you can see, the last equality wins! In this case, a is now an array.

Types

BoxLang is a typeless language, but internal types always exist which can be inferred or declared. BoxLang will automatically cast so you can do flexible typing assignments when evaluating expressions. It does all the tedious and hard job for you. If we were to categorize BoxLang variables into categories, these would be:

BoxLang also includes many validation functions that are available to you to test for the type of variable you are working with. You can also use the getmetdata() function to get the metadata about the variable as well.

isArray()
isBinary()
isBoolean()
isCustomFunction()
isClosure()
isDate()
isDateObject()
isFileObject()
isJSON()
isIPv6()
isLeapYear()
isNumeric()
isNumericDate()
isObject()
isLocalHost()
isNull()
isPDFFile()
isPDFObject()
isQuery()
isSimpleValue()
isStruct()
isValid( type, value )
isXML()
isXmlDoc()
isXMLElem()
isXMLNode()
ixXMLRoot()

Conversions

You can also convert variables from one type to another in BoxLang. Here are some functions that will assist you in conversions:

arrayToList()
binaryDecode()
binaryEncode()
charsetDecode()
charsetEncode()
deserializeJSON()
entityToQuery()
hash()
hmac()
HTMLParse()
lcase()
listToArray()
parseNumber()
serializeJSON()
toBase64()
toBinary()
toScript()
toString()
URLDecode()
URLEncode()
URLEncodedFormat()
val()
XMLFormat()
XMLParse()
XMLTransform()

Outputting Variables (Interpolation)

You can also output or evaluate variables by using the # operators and using the variable name. This is referred to as interpolation in some languages:

Also, note that using the # hashes for output on assignments can be redundant if you do NOT use string interpolation but just variable assignments.

Don't do this

Do this

Debugging Variables

BoxLang offers one of the most used functions/tags ever: <bx:dump>, writeDump() and <bx:abort>, abort;. These are used to dump all the contents of a variable into the browser, console, or even a file. You can then leverage the abort construct to abort the request and see the output of your dumped variables. This will work with both simple and complex variables. However, be very careful when using it with Nested ORM objects, as you can potentially dump your entire database and crash the server. Leverage the top argument to limit dumping.

Server Debugging Templates

BoxLang also allows you to turn on/off a debugging template that shows up at the bottom of requests when running in server mode. You can activate this debugging by logging in to the appropriate engine administrator and looking for the debugging section. Turn it on and debug like a champ.

Paraming Variables

BoxLang allows you to set default values for variables if you use a variable that doesn't exist. You can use the <bx:param> tag or the param construct:

Checking For Existence

You can verify if variables exist in many different ways. The following section showcases how variables are stored in visibility and persistence scopes, all of which are structures or hash maps in Java terms. This means you can leverage structure operations to check for existence and much more. Below are several ways to verify variable existence:

isDefined() - Evaluates a string value to determine whether the variable
named in it exists.
isNull() - Returns true if the specified object is null, else false.
structKeyExists( key, value ) - Verifies if the specified key variable exists in a structure.

Java Integration

As we have discussed, BoxLang is a dynamic language built on Java. Thus each variable internally is represented by a native Java data type: String, Int, Float, Array, Vector, HashMap, etc. This is important because each variable you create has member functions available to you that delegate or reflect its native Java class.

If you run the script above in the REPL tool, you will see the output as java.lang.String. Therefore, the variable is typed as a String and can call on any method that java.lang.String implements. You can try this for the many types in BoxLang, like structs, arrays, objects, etc.

Member Functions

Here are some examples:

Member functions for the following data types are supported:

Array
String
List
Struct
Date
Spreadsheet
XML
Query
Image

Naming Coding Standards

Datasources

A datasource is a named connection to a specific database with specified credentials. You can define a datasource in one of three locations:

The datasource is then used to control the database's connection pool and allow the BoxLang engine to execute JDBC calls against it.

What Database Vendors Are Supported?

The following database vendors are supported and available:

Each database we support comes with an installable BoxLang module which either

provides the necessary client dependencies for making JDBC connections to a running database server (MySQL, Postgres, etc.)
OR contains the database vendor itself, as in the case of Apache Derby or HyperSQL, which are both in-memory database.

To use any of these databases you'll need to install its BoxLang module to support JDBC connections to that datasource.

Make Sure to Specify a Driver

this.datasources[ "testDB" ] = {
	"driver": "mysql",
	// OR:
	"url" : "jdbc:mysql://localhost:3306/test"
};

Defining Datasources In `boxlang.json`

You can define a datasource at the BoxLang runtime level by placing it in your boxlang.json:

boxlang.json

  "datasources": {
      "theDerbyDB": {
      	"driver": "derby",
    	"connectionString": "jdbc:derby:memory:testDB;create=true"
      },
      "theMysqlDB": {
      	"driver": "mysql",
        "host": "${env.MYSQL_HOST:localhost}",
        "port": "${env.MYSQL_PORT:3306}",
        "database": "${env.MYSQL_DATABASE:myDB}",
        "username": "${env.MYSQL_USERNAME:root}",
        "password": "${env.MYSQL_PASSWORD}"
      }
  },

Defining Datasources In `Application.bx`

For web runtimes, you can also define the datasources in the Application.bx, which is sometimes our preferred approach as the connections are versioned controlled and more visible than in the admin. You will do this by defining a struct called this.datasources. Each key will be the name of the datasource to register and the value of each key a struct of configuration information for the datasource. However, we recommend that you setup environment variables in order to NOT store your passwords in plain-text in your source code.

Application.bx

class{
    this.datasources = {
        // Driver Approach
        mysql = {
            database : "mysql",
            host : "localhost",
            port : "3306",
            driver : "MySQL",
            username : "root",
            password : "mysql",
            options : value
        },
        // URL approach
        mysql2 = {
            driver : "mysql",
            url : "jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true",
            username : "",
            password : ""
        },
        // Shorthand Approach
        myDSN = {
            class : "com.mysql.jdbc.Driver",
            connectionString : "jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true",
            username : "",
            password : ""
        },
        // Long Approach
        myDSN = {
            type : "mysql",
            database : "mysql",
            host : "localhost",
            port : "3306",
            username : "",
            password : ""
        }
    };
}

For the inline approach, you will use the struct definition, as you see in the Application.bx above and pass it into the bx:query or queryexecute call.

Defining Inline Datasources

Finally, for smaller or simpler applications with few queries, you may find it useful to define your datasource at query time. So instead of giving the name of the datasource, it can be a struct definition of the datasource you want to connect to:

queryExecute(
  "SELECT * FROM Employees WHERE empid = ? AND country = ?", // sql
  [ 1, "USA" ], // params
  { // options
    datasource : {
      "driver": "mysql",
      "host": "${env.MYSQL_HOST:localhost}",
      "port": "${env.MYSQL_PORT:3306}",
      "database": "${env.MYSQL_DATABASE:myDB}",
      "username": "${env.MYSQL_USERNAME:root}",
      "password": "${env.MYSQL_PASSWORD}"
    }
  }
)

Default Datasource

You can also define a default datasource to allow you to omit the datasource completely from query calls.

To do this, you'll need to define a default datasource in one of two locations:

In your BoxLang runtime's boxlang.json config file via the defaultDatasource key
or, for web server runtimes, in a this.datasource variable in your Application.bx file

Defining a default datasource via boxlang.json

boxlang.json

   "defaultDatasource: {
      "driver": "mysql",
       "host": "${env.MYSQL_HOST:localhost}",
       "port": "${env.MYSQL_PORT:3306}",
       "database": "${env.MYSQL_DATABASE:myDB}",
       "username": "${env.MYSQL_USERNAME:root}",
       "password": "${env.MYSQL_PASSWORD}"
    },
   "datasources": {
      // You can still define additional datasources here! You're not limited to the default datasource
   },

Defining a default datasource via Application.bx

Application.bx

class{
    this.name = "myApp";

    // Default Datasource Name
    this.datasource = "pantry";

}

Portable Datasources

CF Mappings
Data sources
Mail servers
Request, session, or application timeouts
Licensing information
Passwords
Template caching settings
Basically any settings in the web based administrator

You can easily place a .cfconfig.json in the web root of your project, and if you start up a CommandBox server on any BoxLang engine, CFConfig will transfer the configuration to the engine's innards:

.cfconfig.json

{
    "requestTimeoutEnabled":true,
    "whitespaceManagement":"white-space-pref",
    "requestTimeout":"0,0,5,0",
    "cacheDefaultObject":"coldbox",
    "caches":{
        "coldbox":{
            "storage":"true",
            "type":"RAM",
            "custom":{
                "timeToIdleSeconds":"1800",
                "timeToLiveSeconds":"3600"
            },
            "readOnly":"false"
        }
    },
    "datasources" : {
         "coldbox":{
             "host":"${DB_HOST}",
             "dbdriver":"${DB_DRIVER}",
             "database":"${DB_DATABASE}",
             "dsn":"jdbc:mysql://{host}:{port}/{database}",
             "custom":"useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true&autoReconnect=true",
             "port":"${DB_PORT}",
             "class":"${DB_CLASS}",
             "username":"${DB_USER}",
             "password":"${DB_PASSWORD}",
             "connectionLimit":"100",
             "connectionTimeout":"1"
         }
    }
}

Datasource Configuration

All Configuration Properties

Property

Type

Default

Description

driver

String

dbdriver

String

Alias for driver. Deprecated

class

String

Specify a custom or specific class to use as the database driver. Not recommended - use the correct driver instead.

custom

Struct

Struct of custom properties.

username

String

Database connection username.

password

String

Database connection password.

maxConnections

Integer

The maximum number of connections. Alias for Hikari's maximumPoolSize

minConnections

Integer

The minimum number of connections. Alias for Hikari's minimumIdle

connectionTimeout

Integer

Maximum time to wait for a successful connection, in seconds.

idleTimeout

Integer

600

The maximum number of idle time in seconds (10 Minutes = 600). Refers to the maximum amount of time a connection can remain idle in the pool before it is eligible for eviction.

maxLifetime

Integer

1800

This property controls the maximum lifetime of a connection in the pool. An in-use connection will never be retired, only when it is closed will it then be removed. 30 minutes by default = 1800 seconds.

keepaliveTime

Integer

600

This property controls how frequently HikariCP will attempt to keep a connection alive, in order to prevent it from being timed out by the database or network infrastructure. 10 Minutes = 600 seconds.

autoCommit

Boolean

true

The default auto-commit state of connections created by this pool.

registerMbeans

Boolean

true

"coldbox":{
    ...
   "connectionInitSql":"custom SQL statement to run on connection initialize...",
}

Datasource Connection Pooling

maxConnections
minConnections
connectionTimeout
idleTimeout
maxLifetime
keepaliveTime

Pool Statistics

BoxLang offers a number of pool statistics which can be retrieved from the datasource object. To do this, first find your datasource name from the list of registered datasources:

// get array of unique datasource names for all apps
writeDump( getBoxContext().getRuntime().getDatasourceService().getNames() );

Next, retrieve the datasource by its unique datasource name, and call .getPoolStats() on the result:

writeDump( getBoxContext().getRuntime().getDatasourceService().get( "app_12345_my_Datasource_Name" ).getPoolStats() );

This returns a struct of pool metadata including the following keys:

pendingThreads
idleConnections
totalConnections
activeConnections
maxConnections
minConnections

Find out what datasources you have defined by dumping out this getBoxContext().getRuntime().getDatasourceService().getNames()

https://github.com/ortus-boxlang/BoxLang/blob/development/src/main/resources/config/boxlang.json

/**
 * BoxLang Configuration File
 *
 * Here are some of the available variables you can use in this file:
 * ${boxlang-home} - The BoxLang home directory
 * ${user-home} - The user's home directory
 * ${user-dir} - The user's current directory
 * ${java-temp} - The java temp directory
 * ${env.variablename:defaultValue} - The value of a valid environment variable or the default value. Example: ${env.CFCONFIG_HOME:/etc/cfconfig}
 */
{
	// The version of the runtime
	"version": "@build.version@",
	// Extensions BoxLang will process as classes
	"validClassExtensions": [
		"bx",
		// Moving to compat at final release
		"cfc"
	],
	// Additional Extensions BoxLang will process as templates.  The default extensions such as bxm, bxs, cfm, cfs, etc. are always processed as templates
	// This is used by the RunnableLoader
	"validTemplateExtensions": [],
	// Where all generated classes will be placed
	"classGenerationDirectory": "${boxlang-home}/classes",
	// This puts the entire runtime in debug mode
	// Which will produce lots of debug output and metrics
	// Also the debugging error template will be used if turned on
	"debugMode": false,
	// This setting if enabled will remove all the class files from the class generation directory
	// This is useful for debugging and testing, but not recommended for production
	"clearClassFilesOnStartup": false,
	// This enables the class locations cache for the runtime.  It's used when resolving class paths
	// mostly using mappings, per request mappings, etc.
	// We recommend you always enable this setting, unless debugging a very specific issue
	"classResolverCache": true,
	// This enables the runnable loader's cache on disk for compiled BoxLang classes
	// This means that it will load a Boxlang class and never inspect the file again
	// Turn this on for production, but off for development so you can see your changes
	"trustedCache": false,
	// The default timezone for the runtime; defaults to the JVM timezone if empty
	// Please use the IANA timezone database values
	"timezone": "",
	// The default locale for the runtime; defaults to the JVM locale if empty
	// Please use the IETF BCP 47 language tag values
	"locale": "",
	// Enable whitespace compression in output.  Only in use by the web runtimes currently.
	"whitespaceCompressionEnabled": true,
	// By default BoxLang uses high-precision mathematics via BigDecimal operations
	// You can turn this off here for all applications
	"useHighPrecisionMath": true,
	// Use Timespan syntax: "days, hours, minutes, seconds"
	"applicationTimeout": "0,0,0,0",
	// The request timeout for a request in seconds; 0 means no timeout
	"requestTimeout": "0,0,0,0",
	// The session timeout: 30 minutes
	"sessionTimeout": "0,0,30,0",
	// Where sessions will be stored by default.  This has to be a name of a registered cache
	// or the keyword "memory" to indicate our auto-created cache.
	// This will apply to ALL applications unless overridden in the Application.cfc
	"sessionStorage": "memory",
	// A collection of BoxLang mappings, the key is the prefix and the value is the directory
	"mappings": {
		"/": "${user-dir}"
	},
	// A collection of BoxLang module directories, they must be absolute paths or expanded paths
	"modulesDirectory": [
		"${user-dir}/boxlang_modules",
		"${boxlang-home}/modules"
	],
	// A collection of BoxLang custom tag directories, they must be absolute paths
	"customTagsDirectory": [
		"${boxlang-home}/customTags"
	],
	// A collection of directories to lookup box classes in (.bx files), they must be absolute paths
	"classPaths": [],
	// A collection of directories we will class load all Java *.jar files from
	"javaLibraryPaths": [
		"${boxlang-home}/lib"
	],
	// Logging Settings for the runtime
	"logging": {
		// The location of the log files the runtime will produce
		"logsDirectory": "${boxlang-home}/logs",
		// The maximum number of days to keep log files before rotation
		// Default is 90 days or 3 months
		// Set to 0 to never rotate
		"maxLogDays": 90,
		// The maximum file size for a single log file before rotation
		// You can use the following suffixes: KB, MB, GB
		// Default is 100MB
		"maxFileSize": "100MB",
		// The total cap size of all log files before rotation
		// You can use the following suffixes: KB, MB, GB
		// Default is 5GB
		"totalCapSize": "5GB",
		// The root logger level
		// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
		// If the runtime is in Debug mode, this will be set to DEBUG
		"rootLevel": "WARN",
		// Default Encoder for file appenders.
		// The available options are "text" and "json"
		"defaultEncoder": "text",
		// Activate the status printer on load to print out the logging configuration
		// Turn on to debug LogBack and BoxLang logging configurations
		"statusPrinterOnLoad": false,
		// A collection of pre-defined loggers and their configurations
		"loggers": {
			// The runtime main and default log
			"runtime": {
				// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
				// Leave out if it should inherit from the root logger
				"level": "INFO",
				// Valid values are: "file", "console",
				// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
				// Please note that we only use Rolling File Appenders
				"appender": "file",
				// Use the defaults from the runtime
				"appenderArguments": {},
				// The available options are "text" and "json"
				"encoder": "text",
				// Additive logging: true means that this logger will inherit the appenders from the root logger
				// If false, it will only use the appenders defined in this logger
				"additive": false
			},
			// All async operations and facilities will log here.
			"async": {
				// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
				// Leave out if it should inherit from the root logger
				"level": "INFO",
				// Valid values are: "file", "console",
				// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
				// Please note that we only use Rolling File Appenders
				"appender": "file",
				// Use the defaults from the runtime
				"appenderArguments": {},
				// The available options are "text" and "json"
				"encoder": "text",
				// Additive logging: true means that this logger will inherit the appenders from the root logger
				// If false, it will only use the appenders defined in this logger
				"additive": false
			},
			// All cache operations and facilities will log here.
			"cache": {
				// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
				// Leave out if it should inherit from the root logger
				"level": "WARN",
				// Valid values are: "file", "console",
				// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
				// Please note that we only use Rolling File Appenders
				"appender": "file",
				// Use the defaults from the runtime
				"appenderArguments": {},
				// The available options are "text" and "json"
				"encoder": "text",
				// Additive logging: true means that this logger will inherit the appenders from the root logger
				// If false, it will only use the appenders defined in this logger
				"additive": false
			},
			// The datasource log is used by the creation, debugging, and management of datasources
			"datasource": {
				// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
				// Leave out if it should inherit from the root logger
				"level": "WARN",
				// Valid values are: "file", "console",
				// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
				// Please note that we only use Rolling File Appenders
				"appender": "file",
				// Use the defaults from the runtime
				"appenderArguments": {},
				// The available options are "text" and "json"
				"encoder": "text",
				// Additive logging: true means that this logger will inherit the appenders from the root logger
				// If false, it will only use the appenders defined in this logger
				"additive": false
			},
			// The modules log is used by the module service and records all module activity
			"modules": {
				// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
				// Leave out if it should inherit from the root logger
				"level": "INFO",
				// Valid values are: "file", "console",
				// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
				// Please note that we only use Rolling File Appenders
				"appender": "file",
				// Use the defaults from the runtime
				"appenderArguments": {},
				// The available options are "text" and "json"
				"encoder": "text",
				// Additive logging: true means that this logger will inherit the appenders from the root logger
				// If false, it will only use the appenders defined in this logger
				"additive": false
			},
			// All applications will use this logger for any custom logging
			"application": {
				// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
				// Leave out if it should inherit from the root logger
				"level": "WARN",
				// Valid values are: "file", "console",
				// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
				// Please note that we only use Rolling File Appenders
				"appender": "file",
				// Use the defaults from the runtime
				"appenderArguments": {},
				// The available options are "text" and "json"
				"encoder": "text",
				// Additive logging: true means that this logger will inherit the appenders from the root logger
				// If false, it will only use the appenders defined in this logger
				"additive": false
			},
			// All scheduled tasks logging will go here
			"scheduler": {
				// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
				// Leave out if it should inherit from the root logger
				"level": "INFO",
				// Valid values are: "file", "console",
				// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
				// Please note that we only use Rolling File Appenders
				"appender": "file",
				// Use the defaults from the runtime
				"appenderArguments": {},
				// The available options are "text" and "json"
				"encoder": "text",
				// Additive logging: true means that this logger will inherit the appenders from the root logger
				// If false, it will only use the appenders defined in this logger
				"additive": false
			}
		}
	},
	// This is the experimental features flags.
	// Please see the documentation to see which flags are available
	"experimental": {
		// This choose the compiler to use for the runtime
		// Valid values are: "java", "asm"
		"compiler": "asm",
		// If enabled, it will generate AST JSON data under the project's /grapher/data folder
		"ASTCapture": false
	},
	// Global Executors for the runtime
	// These are managed by the AsyncService and registered upon startup
	// The name of the executor is the key and the value is a struct of executor settings
	// Types are: cached, fixed, fork_join, scheduled, single, virtual, work_stealing`
	// The `threads` property is the number of threads to use in the executor. The default is 20
	// Some executors do not take in a `threads` property
	"executors": {
		// Use this for IO bound tasks, does not support scheduling
		// This is also the default executor for parallel operations
		// This is also the default when requestion an executor service via executorGet()
		"io-tasks": {
			"type": "virtual"
		},
		// Use this for CPU bound tasks, supports scheduling
		"cpu-tasks": {
			"type": "scheduled",
			"threads": 10
		},
		// Used for all scheduled tasks in the runtime
		"scheduled-tasks": {
			"type": "scheduled",
			"threads": 10
		}
	},
	// BoxLang Scheduler
	// These are managed by the SchedulerService and registered upon startup
	// or via a boxlang schedule [scheduler.bx] call
	"scheduler": {
		// The default scheduler for all scheduled tasks
		// Each scheduler can have a different executor if needed
		"executor": "scheduled-tasks",
		// The cache to leverage for server fixation or distribution
		"cacheName": "default",
		// An array of BoxLang Schedulers to register upon startup
		// Must be an absolute path to the scheduler file
		// You can use the ${user-dir} or ${boxlang-home} variables or any other environment variable
		// Example: "schedulers": [ "/path/to/Scheduler.bx" ]
		"schedulers": [],
		// You can also define tasks manually here
		// Every task is an object defined by a unique name
		// The task object is a struct with the following properties:
		// - `crontime:string` - The cron time to run the task (optional), defaults to empty string
		// - `eventhandler:path` - The absolute path to the task event handler(optional), defaults to empty string
		// - `exclude:any` - Comma-separated list of dates or date range (d1 to d2) on which to not execute the scheduled task
		// - `file:name` - Name of the log file to store output of the task (optional), defaults to `scheduler`
		// - `group:string` - The group name of the task (optional), defaults to empty string
		"tasks": {}
	},
	"defaultDatasource": "",
	// The registered global datasources in the language
	// The key is the name of the datasource and the value is a struct of the datasource settings
	"datasources": {
		// "testDB": {
		// 	  "driver": "derby",
		//    "connectionString": "jdbc:derby:memory:testDB;create=true"
		// }
		// "testdatasource": {
		// 	  "driver": "derby",
		// 	  "host": "localhost",
		// 	  "port": 3306,
		// 	  "database": "test"
		// }
	},
	// The default return format for class invocations via web runtimes
	"defaultRemoteMethodReturnFormat": "json",
	/**
	* Register any named caches here.
	* The key is the name of the cache and the value is the cache configuration.
	*
	* A `provider` property is required and the value is the name of the cache provider or the fully qualified class name.
	* The `properties` property is optional and is a struct of properties that are specific to the cache provider.
	*/
	"caches": {
		// The configuration for the BoxLang `default` cache.  If empty, we use the defaults
		// See the ortus.boxlang.runtime.config.segments.CacheConfig for all the available settings
		// This is used by query caching, template caching, and other internal caching.
		// You can use the cache() BIF in order to get access to the default cache.
		"default": {
			"provider": "BoxCacheProvider",
			"properties": {
				// How many to evict at a time once a policy is triggered
				"evictCount": 1,
				// The eviction policy to use: Least Recently Used
				// Other policies are: LRU, LFU, FIFO, LIFO, RANDOM
				"evictionPolicy": "LRU",
				// The free memory percentage threshold to trigger eviction
				// 0 = disabled, 1-100 = percentage of available free memory in heap
				// If the threadhold is reached, the eviction policy is triggered
				"freeMemoryPercentageThreshold": 0,
				// The maximum number of objects to store in the cache
				"maxObjects": 1000,
				// The maximum in seconds to keep an object in the cache since it's last access
				// So if an object is not accessed in this time or greater, it will be removed from the cache
				"defaultLastAccessTimeout": 1800,
				// The maximum time in seconds to keep an object in the cache regardless if it's used or not
				// A default timeout of 0 = never expire, careful with this setting
				"defaultTimeout": 3600,
				// The object store to use to store the objects.
				// The default is a ConcurrentStore which is a memory sensitive store
				"objectStore": "ConcurrentStore",
				// The frequency in seconds to check for expired objects and expire them using the policy
				// This creates a BoxLang task that runs every X seconds to check for expired objects
				"reapFrequency": 120,
				// If enabled, the last access timeout will be reset on every access
				// This means that the last access timeout will be reset to the defaultLastAccessTimeout on every access
				// Usually for session caches or to simulate a session
				"resetTimeoutOnAccess": false,
				// If enabled, the last access timeout will be used to evict objects from the cache
				"useLastAccessTimeouts": true
			}
		},
		// This is the holder of all sessions in a BoxLang runtime.
		// The keys are prefixed by application to create separation.
		"bxSessions": {
			"provider": "BoxCacheProvider",
			"properties": {
				// How many objects to evict when the cache is full
				"evictCount": 1,
				// The eviction policy to use: FIFO, LFU, LIFO, LRU, MFU, MRU, Random
				"evictionPolicy": "LRU",
				// The maximum number of objects the cache can hold
				"maxObjects": 100000,
				// How long should sessions last for in seconds. Default is 60 minutes.
				"defaultTimeout": 3600,
				// The object store to use to store the objects.
				// The default is a ConcurrentStore which is a thread safe and fast storage.
				// Available Stores are: BlackHoleStore, ConcurrentSoftReferenceStore, ConcurrentStore, FileSystemStore, Your own.
				"objectStore": "ConcurrentStore",
				// The free memory percentage threshold to start evicting objects
				// Only use if memory is constricted and you need to relieve cache pressure
				// Please note that this only makes sense depending on which object store you use.
				"freeMemoryPercentageThreshold": 0,
				// The frequency in seconds to check for expired objects and expire them using the policy
				// This creates a BoxLang task that runs every X seconds to check for expired objects
				// Default is every 2 minutes
				"reapFrequency": 120,
				// This makes a session extend it's life when accessed.  So if a users uses anything or puts anything
				// In session, it will re-issue the timeout.
				"resetTimeoutOnAccess": true,
				// Sessions don't rely on the last access timeouts but on the default timeout only.
				"useLastAccessTimeouts": false
			}
		},
		// Stores all dynamic regular expressions used in the runtime
		"bxRegex": {
			"provider": "BoxCacheProvider",
			"properties": {
				"evictCount": 1,
				"evictionPolicy": "LRU",
				"freeMemoryPercentageThreshold": 0,
				"maxObjects": 500,
				// 30 minutes ifnot used
				"defaultLastAccessTimeout": 1800,
				// 60 minutes default
				"defaultTimeout": 3600,
				"objectStore": "ConcurrentSoftReferenceStore",
				"reapFrequency": 120,
				"resetTimeoutOnAccess": false,
				"useLastAccessTimeouts": true
			}
		}
	},
	// These are the security settings for the runtime
	"security": {
		// All regex patterns are case-insensitive
		// A list of regex patterns that will match class paths, and if matched, execution will be disallowed
		// This applies to import statements, createObject, new, and class creation
		// Ex: "disallowedImports": ["java\\.lang\\.(ProcessBuilder|Reflect", "java\\.io\\.(File|FileWriter)"]
		"disallowedImports": [],
		// A list of BIF names that will be disallowed from execution
		// Ex: "disallowedBifs": ["createObject", "systemExecute"]
		"disallowedBifs": [],
		// A list of Component names that will be disallowed from execution
		// Ex: "disallowedComponents": [ "execute", "http" ]
		"disallowedComponents": [],
		// An explicit whitelist of file extensions that are allowed to be uploaded - overrides any values in the disallowedWriteExtensions
		"allowedFileOperationExtensions": [],
		// The list of file extensions that are not allowed to be uploaded. Also enforced by file relocation operations ( e.g. copy/move )
		"disallowedFileOperationExtensions": [
			"bat",
			"exe",
			"cmd",
			"cfm",
			"cfc",
			"cfs",
			"bx",
			"bxm",
			"bxs",
			"sh",
			"php",
			"pl",
			"cgi",
			"386",
			"dll",
			"com",
			"torrent",
			"js",
			"app",
			"jar",
			"pif",
			"vb",
			"vbscript",
			"wsf",
			"asp",
			"cer",
			"csr",
			"jsp",
			"drv",
			"sys",
			"ade",
			"adp",
			"bas",
			"chm",
			"cpl",
			"crt",
			"csh",
			"fxp",
			"hlp",
			"hta",
			"inf",
			"ins",
			"isp",
			"jse",
			"htaccess",
			"htpasswd",
			"ksh",
			"lnk",
			"mdb",
			"mde",
			"mdt",
			"mdw",
			"msc",
			"msi",
			"msp",
			"mst",
			"ops",
			"pcd",
			"prg",
			"reg",
			"scr",
			"sct",
			"shb",
			"shs",
			"url",
			"vbe",
			"vbs",
			"wsc",
			"wsf",
			"wsh"
		]
	},
	/**
	 * The BoxLang module settings
	 * The key is the module name and the value is a struct of settings for that specific module
	 * The `enabled` property is a boolean that determines if the module should be enabled or not.  Default is true
	 * The `settings` property is a struct of settings that are specific to the module and will be override the module settings
	 */
	"modules": {
		// The Compat Module
		// "compat": {
		// 	"enabled": true,
		// 	"settings": {
		// 		"isLucee": true,
		// 		"isAdobe": true
		// 	}
		// }
	}
}