Pipi autonomous Read-Eval-Print-Loop (REPL)

Mike's Notes

Deployment roadmap

Later in the year, Pipi will be able to deploy infrastructure on any platform using Infrastructure as Code (IaC).

Options on how to do this include;

  • CL (Command Line)
  • REPL (Read-Eval-Print-Loop)
  • API

Implementing a REPL (Read-Eval-Print-Loop) programmatically in CFML

I asked Google Search AI Mode (powered by Google Gemini) how to use CFML to write and read REPL.

The Google output has been reformatted but not edited, and the code needs to be tested. The questions were turned into headings. There is a lot of duplication.

I find that carefully using Gemini to write CFML code and then checking everything is making me more productive.

There is now enough here to set up REPL.

Once this automation is complete, productivity will increase by at least x10.

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

04/04/2026

Pipi autonomous Read-Eval-Print-Loop (REPL)

By: Mike Peters and Gemini
On a Sandy Beach: 04/04/2026

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

Gemini is still cool.

A Read-Eval-Print-Loop (REPL) is an interactive computer programming environment that accepts single-user input, executes it, and returns the result immediately. It is also known as an interactive toplevel or language shell. [1, 2, 3] 

The Four Steps of the Loop

The name describes the precise cycle the environment follows: [4, 5] 

  • Read: The system accepts a line of input (usually a single expression or command) from the user.
  • Eval: It parses and evaluates the input code to determine its value or effect.
  • Print: The resulting value or output is displayed back to the user on the screen.
  • Loop: The process repeats, returning to the prompt to wait for the next input. [1, 5, 6, 7, 8, 9, 10] 

Why Developers Use REPLs

REPLs are highly valued for their tight feedback loop, which allows for: [6, 7, 11] 

  • Interactive Prototyping: Quickly testing small snippets of code without creating and saving files.
  • Debugging: Investigating the state of a program and testing potential fixes in real-time.
  • Learning: Experimenting with new language features or libraries with instant results.
  • Calculations: Using the environment as a high-powered calculator for mathematical expressions. [1, 12, 13, 14, 15, 16, 17] 

Common Examples

Most modern programming languages provide a built-in REPL or have popular third-party versions: [1, 18] 

References

Implementing REPL programmatically in CFML

Implementing a REPL (Read-Eval-Print-Loop) programmatically in CFML involves creating a loop that captures user input, evaluates it as live code, and returns the result. [1, 2, 3] 

While Adobe ColdFusion (2018+) and CommandBox include built-in REPLs for terminal use, you can build your own programmatic version using the following core functions: [2, 4]

1. The Evaluation Engine

The most critical part of a REPL is the Eval step. CFML provides two primary ways to execute strings as code:

  • Evaluate(): Best for executing single expressions and returning a value.
  • Render(): (Lucee specific) Similar to Evaluate, but specifically designed to execute CFML tag or script code and return the generated output as a string. [5, 6] 

2. Building a Basic Web-Based REPL

A programmatic REPL usually consists of a simple loop (often via a form submission) that maintains state.

// 1. READ: Get input from a form or API
inputCode = form.myScript ?: "";
if (len(trim(inputCode))) {
    try {
        // 2. EVAL: Execute the code
        // Note: Evaluate() is powerful but dangerous with untrusted input
        result = evaluate(inputCode);
        
        // 3. PRINT: Output the result
        writeOutput("Result: " & result);
    } catch (any e) {
        writeOutput("Error: " & e.message);
    }
}
// 4. LOOP: Handled by the user submitting the form again

3. Advanced Implementation Details

To create a more robust "shell-like" experience:

  • Persistent State: To keep variables alive across multiple inputs, store a "context" structure in a persistent scope like Session or Application.
  • Capturing Console Output: If the code uses writeOutput(), you may need to use cfsavecontent to capture that output before it hits the main buffer.
  • Safety: Never expose a REPL to public users. It allows for arbitrary code execution, which can delete files or access sensitive server data.
  • Multi-line Support: For more complex scripts, you may need to detect if a block (like an if statement or function) is complete before evaluating, similar to how [CommandBox's REPLParser](https://community.ortussolutions.com/t/replparser-multiline-support/9559) works. [6, 7, 8] 

Summary of Tools

Feature [2, 3] Function/Tool Platform
Expression Eval Evaluate(string) Adobe & Lucee
Full Code Execution Render(string) Lucee Only
Terminal REPL cf.bat / cf.sh Adobe (2018+)
CLI REPL box repl CommandBox

References

Using workflows written in CFML to write and read REPL

To build a workflow in CFML that programmatically reads from and writes to a REPL, you need to treat the REPL as an external process. This is most effectively done using CommandBox, which provides a robust CLI and REPL environment for CFML. [1, 2] 

1. Using CommandBox via cfexecute

The standard way to interact with a REPL from a running CFML workflow (like a background task or a web request) is to use <cfexecute> or the execute() function to call the [CommandBox binary](https://modern-cfml.ortusbooks.com/intro/instructions-and-interpreters).

  • Writing to REPL: You can pass CFML code directly to the CommandBox repl command using the --code flag or by piping input.
  • Reading from REPL: The output of the command is captured in a variable for your workflow to process. [3, 4, 5] 

Example: Running a Snippet and Capturing the Result

// Define the CFML code you want the REPL to evaluate
replInput = "x = 10; y = 20; writeOutput(x + y);";
// Execute CommandBox REPL with the code
execute(
    name = "box", 
    arguments = "repl --code=""#replInput#""", 
    variable = "replOutput", 
    timeout = 10
);
// Read the result back into your workflow
writeOutput("The REPL returned: " & replOutput);

2. Interactive Workflows with Piping

If your workflow needs to chain multiple operations, you can use the cfml command in CommandBox. This allows you to [pipe data](https://commandbox.ortusbooks.com/usage/execution/cfml-functions) between CFML functions as if they were terminal commands.

  • Workflow logic: #listGetAt www.foo.com 2 . | #ucase | #reverse
  • Result: The REPL processes each step and passes the "Read" result of one to the "Eval" of the next. [6, 7] 

3. Asynchronous "Daemon" REPL

For a long-running workflow that needs to keep a REPL "warm" (to avoid startup overhead), consider using an Event Gateway or a persistent background thread. [8] 

  1. Start a process: Use java.lang.ProcessBuilder via CFML to open a persistent connection to the CommandBox shell.
  2. Write to Stream: Send commands to the process's OutputStream.
  3. Read from Stream: Use a separate CFML thread to constantly poll the InputStream for the REPL's response. [9, 10] 

4. Safety and Best Practices

  • Sanitisation: If the input for your REPL comes from an external source, treat it as unsafe. Programmatic REPLs can execute fileDelete() or access system environment variables.
  • Timeouts: Always set a timeout in your execute calls to prevent a "loop" in the REPL from hanging your entire server.
  • Context: Remember that code executed in a separate REPL process does not share the same variable scope (like Session or Request) as your main workflow unless you explicitly pass those values in. [11] 

References

Pass complex data (like a Struct) between your workflow and a CommandBox REPL

To pass complex data, such as a Struct or Array, between a CFML workflow and a REPL, the most reliable method is to use JSON serialisation. Since the REPL and your main application run in separate memory spaces, JSON acts as a universal bridge for data exchange.

1. Passing a Struct into the REPL (Write)

When calling the REPL, convert your CFML Struct into a JSON string and inject it into the command as a literal. CommandBox’s REPL is smart enough to interpret a JSON string as a native Struct if it's the first input to certain functions or assigned directly. [1, 2] 

// Your complex workflow data
userData = {
    "id": 123,
    "roles": ["admin", "editor"],
    "settings": { "theme": "dark" }
};
// Serialize to JSON (use single quotes for the shell command)
jsonInput = serializeJSON(userData);
// Build the REPL command
// Note: We assign the JSON string directly to a variable inside the REPL
replCommand = "data = #jsonInput#; writeOutput(data.roles[1]);";
execute(
    name = "box",
    arguments = "repl --code=""#replCommand#""",
    variable = "replResponse"
);
writeOutput("REPL processed role: " & replResponse); // "admin"

2. Getting a Struct back from the REPL (Read)

To read complex data back into your workflow, have the REPL print the result as JSON. You then use deserializeJSON() in your main workflow to turn that string back into a live CFML Struct. [3] 

// REPL code that performs logic and returns a new struct
replCode = "result = { 'status': 'success', 'timestamp': now() }; writeOutput(serializeJSON(result));";
execute(
    name = "box",
    arguments = "repl --code=""#replCode#""",
    variable = "rawJsonResponse"
);
// Read the complex data back into your workflow
if (isJSON(rawJsonResponse)) {
    finalData = deserializeJSON(rawJsonResponse);
    writeOutput("Status received: " & finalData.status);
}

Key Considerations for Data Integrity

  • Key Casing: Adobe ColdFusion typically converts struct keys to UPPERCASE during serialisation unless you quote the keys (e.g., {"name": "value"}).
  • Shell Escaping: Be careful with double quotes inside your JSON. When building the arguments string for execute(), ensure you escape quotes correctly so the shell doesn't break the command.
  • Performance: If you are passing very large datasets (multi-MB structs), the overhead of serialisation and shell execution will increase. For high-frequency workflows, consider writing the data to a temporary JSON file and having the REPL read that file instead of passing it as a command-line argument. [4, 5, 6, 7] 

Using temporary files to handle larger datasets between your workflow and the REPL

To handle larger datasets between your CFML workflow and a REPL, using temporary files is the most reliable method. This avoids shell character limits and prevents memory issues. [1] 

1. The Workflow: Writing to a Temp File

First, your main application serialises the data into a JSON file. Use getTempFile() to ensure a unique filename that won't collide with other processes. [2, 3] 

// 1. Prepare your large dataset
complexData = {
    "users": queryToArray( myLargeUserQuery ), // Assume 10k rows
    "metadata": { "source": "workflow_alpha", "processed": now() }
};
// 2. Create a unique temp file
tempFilePath = getTempFile( getTempDirectory(), "repl_data" );
// 3. WRITE: Save the JSON to the file
fileWrite( tempFilePath, serializeJSON( complexData ) );

2. The REPL: Reading the File

When you execute the REPL, pass the file path as a variable. The REPL code will then read the file from disk and deserialise it back into a native CFML object. [4, 5] 

// 4. Build the REPL script to READ the file
replCode = "
    data = deserializeJSON( fileRead('#tempFilePath#') );
    // Perform complex logic on the data
    resultCount = data.users.len();
    writeOutput( resultCount );
";
// 5. EXECUTE: Call CommandBox REPL
execute(
    name = "box",
    arguments = "repl --code=""#replCode#""",
    variable = "replOutput"
);

3. Cleaning Up

Because these files are stored in the system's temporary directory, they will eventually be cleared, but it is best practice to delete them manually once your workflow is finished to save disk space. [1, 6] 

// 6. Cleanup after reading the result
if ( fileExists( tempFilePath ) ) {
    fileDelete( tempFilePath );
}
writeOutput( "REPL processed #replOutput# records." );

Why use files instead of variables?

  • Memory Efficiency: Large strings in shell commands can lead to "Out of Memory" (OOM) errors or exceed operating system command-line length limits.
  • Data Integrity: Files eliminate the need for complex shell quoting and escaping of special characters in your JSON.
  • Persistent Context: If the REPL crashes, the data remains safely on disk for debugging or a retry attempt. [1, 7] 

References

CommandBox Task Runners to make these multi-step REPL workflows even cleaner

While a REPL is great for ad-hoc snippets, CommandBox Task Runners provide a more structured way to handle multi-step workflows. A Task Runner is a CFML component (.cfc) that runs directly from the command line, allowing you to pass complex arguments naturally and use built-in helpers for file and shell interaction. [1, 2, 3, 4]

1. Create the Task Runner (MyTask.cfc) [5]

Instead of cramming logic into a string for the REPL, you write a standard CFML function. You can create one by running task create --open in [CommandBox](https://commandbox.ortusbooks.com/task-runners). [2, 3, 6] 

/**
 * MyTask.cfc
 * Automates a workflow with complex data
 */
component {
    
    function run( string inputPath ) {
        // 1. READ: Load the large dataset from the file
        var data = deserializeJSON( fileRead( arguments.inputPath ) );
        
        print.greenLine( "Processing #data.users.len()# users..." );

        // 2. EVAL: Perform your workflow logic
        var result = {
            "processedCount": data.users.len(),
            "timestamp": now(),
            "status": "complete"
        };

        // 3. PRINT: Return the result as JSON for the calling workflow
        print.text( serializeJSON( result ) );
    }
}

2. Execute the Task from your Workflow [5]

In your main application, you call the task just like you did with the REPL, but it’s much cleaner because the logic is encapsulated in its own file. [7, 8] 


// Path to your Task Runner CFC
taskPath = expandPath( "./MyTask.cfc" );
tempDataFile = getTempFile( getTempDirectory(), "data" );

// Prepare and write data
fileWrite( tempDataFile, serializeJSON( myLargeStruct ) );

// Execute the task via CommandBox
execute(
    name = "box",
    arguments = "task run taskFile=#taskPath# inputPath=#tempDataFile#",
    variable = "rawResult"
);
// Process the structured return
workflowResult = deserializeJSON( rawResult );
writeOutput( "Workflow finished at: #workflowResult.timestamp#" );

Why Task Runners are better for workflows:

  • Portability: Tasks are self-contained in a CFC and can be dropped into any folder without being a full module.
  • Built-in Helpers: You get access to the print helper for formatted console output and filesystemUtil for easy path resolution.
  • Named Parameters: Unlike the REPL, tasks support [named parameters](https://commandbox.ortusbooks.com/task-runners/running-other-tasks), making it easy to pass file paths, IDs, or configuration flags.
  • Readability: Your code is written in a standard IDE with syntax highlighting and error checking rather than as a string inside an execute() call. [1, 3, 9, 10, 11] 

References

Scheduling these tasks to run automatically at specific intervals

To schedule CommandBox Task Runners at specific intervals, you have three primary approaches depending on whether you want to use the operating system, a background process (daemon), or the ColdFusion engine itself. [1] 

1. The Daemon Approach (Self-Scheduling)

For workflows that need to run continuously in the background without external dependencies, you can write your task as a daemon. This involves a while(true) loop and a sleep() command within the CFC. [2, 3] 

/**
 * ScheduledTask.cfc
 * Run: box task run taskFile=ScheduledTask.cfc
 */
component {
    function run() {
        try {
            while( true ) {
                print.blueLine( "Running workflow at #now()#..." );
                
                // INSERT YOUR WORKFLOW LOGIC HERE
                
                // Sleep for 5 minutes (300,000 milliseconds)
                sleep( 300000 );
            }
        } catch( any e ) {
            print.redLine( "Task interrupted: #e.message#" );
        }
    }
}

2. OS-Level Scheduling (Cron / Task Scheduler)

This is the most "production-ready" method for strictly timed intervals (e.g., every day at 2 AM). You simply tell your OS to execute the CommandBox binary and your specific task file. [3, 4, 5, 6] 

  • Linux (Crontab): Add a line to your crontab using crontab -e:
    0 2 * * * /usr/local/bin/box task run /path/to/MyTask.cfc
  • Windows (Task Scheduler): Create a new task that runs the box.exe program with the arguments task run taskFile=C:\path\to\MyTask.cfc. [7, 8, 9] 

3. CFML Engine Scheduling (cfschedule) [10] 

If you want to manage the schedule from within your web application's admin interface or code, you can use the native <cfschedule> tag or cfschedule() function to call the CommandBox CLI. [10, 11] 

cfschedule(
    action    = "update",
    task      = "HourlyWorkflow",
    operation = "HTTPRequest",
    url       = "http://localhost/run_my_task.cfm", // A script that runs the task
    interval  = "3600" // Every hour
);

Note: Your run_my_task.cfm file would then contain the execute() call to trigger the CommandBox task.

4. Advanced: ColdBox Scheduled Tasks

If you are using the [ColdBox Framework](https://coldbox.ortusbooks.com/digging-deeper/scheduled-tasks), you can use the built-in Async Scheduler to define tasks with a fluent, human-readable API. [1, 9, 12] 

// inside your Scheduler.cfc
task( "CleanTempFiles" )
    .call( function(){
        // CommandBox execution logic here
    } )
    .every( 1, "hours" )
    .delay( 5, "minutes" );

References
By ,
Tags , , ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)