CFML Transpiler

Transpile your CFML code to BoxLang.

This CLI tool will allow you to transpile your CFML code into BoxLang native code. This is a great way to move forward and leverage BoxLang for your future projects. It will also transpile your Tag-based CFCs into script.

🚀 Usage

Make sure you have installed the OS version of BoxLang so you get all the tools installed as well. Please note that the action command funnels through the boxlang binary, so you can use all the CLI arguments for the boxlang runner.

You can call the tool using our script or the full path to the JAR:

# Using the OS binary
boxlang cftranspile [OPTIONS]

# Using the full path to the JAR
java -jar boxlang-1.6.0.jar ortus.boxlang.compiler.CFTranspiler [OPTIONS]

Getting Help

# Display comprehensive help
boxlang cftranspile --help
boxlang cftranspile -h

📋 CLI Options

Option	Short	Description	Default
--help	-h	Show help message and exit	-
--verbose	-v	Enable verbose output with detailed progress information	false
--source <PATH>	-	Path to source directory or file to transpile	Current directory (.)
--target <PATH>	-	Path to target directory or file (required)	-
--stopOnError [BOOL]	-	Stop processing on first error	false

New in 1.6.0: The --verbose / -v flag provides detailed transpilation progress, showing file-by-file status, parsing issues, and directory creation operations.

🔄 File Extension Mapping

The transpiler automatically converts ColdFusion file extensions to their BoxLang equivalents:

ColdFusion	BoxLang	Description
.cfm	.bxm	ColdFusion markup → BoxLang markup
.cfc	.bx	ColdFusion component → BoxLang class
.cfs	.bxs	ColdFusion script → BoxLang script

💡 Examples

Transpile Current Directory

# Transpile all ColdFusion files in current directory
boxlang cftranspile --target ./boxlang-output

Transpile Specific Directory

# Convert an entire project with directory structure preserved
boxlang cftranspile \
    --source ./coldfusion-code \
    --target ./boxlang-code

Transpile Single File

# Convert a single file (extension auto-detected)
boxlang cftranspile \
    --source app.cfm \
    --target app.bxm

Verbose Mode (New in 1.6.0)

# See detailed progress information during transpilation
boxlang cftranspile \
    --source ./cf-app \
    --target ./bx-app \
    --verbose

The verbose output will show:

• 🚀 Transpiler initialization

• 📂 Directory scanning progress

• 🔄 File-by-file transpilation status

• ⚙️ Parsing operations

• 📁 Directory creation

• ✅ Success confirmations

• ❌ Detailed error messages with parsing issues

Stop on Error

# Stop transpilation on first error encountered
boxlang cftranspile \
    --source ./cf-app \
    --target ./bx-app \
    --stopOnError

Complete Example with All Options

# Full-featured transpilation with verbose output
boxlang cftranspile \
    --source /path/to/cf/project \
    --target /path/to/bx/project \
    --verbose \
    --stopOnError

📂 Behavior

• Directory Transpilation: Preserves folder structure from source to target

• Single File Transpilation: Allows custom target naming

• Auto Directory Creation: Missing target directories are created automatically

• Error Handling: Parsing errors are logged; processing continues unless --stopOnError is used

• Parallel Processing: Directory mode processes files in parallel for better performance

• Extension Auto-Mapping: Target extensions are automatically determined based on source type

🔧 Supported Source Files

The transpiler supports the following ColdFusion file types:

• .cfm - ColdFusion markup pages

• .cfc - ColdFusion components

• .cfs - ColdFusion script files

⚠️ Known Limitations

The transpiler has some current limitations to be aware of:

• Whitespace: May not preserve the exact whitespace from the original source. Since the Abstract Syntax Tree (AST) doesn't store whitespace from script-based code, you'll get whatever formatting the tool applies. We plan to make some of this configurable (tabs vs. spaces, etc.)

• Annotations: ALL function and class annotations are converted to the new @foo bar syntax. We'll update this eventually to keep inline annotations as inline and only move CF "JavaDoc" style annotations to pre-annotations

• Script Conversion: All CFCs will be converted to script. This is by design as BoxLang enforces classes to only be written in script

📖 Additional Resources

• BoxLang Documentation

• Community Forums

• GitHub Repository