tio/docs/interactive-lua-scripting.md

Interactive Lua Scripting

Introduction

Tio provides an interactive Lua scripting interface that allows scripts and Lua commands to be executed while Tio is running.

In earlier versions, the script interpreter was restarted for each script execution. The interpreter now remains active, preserving its state across executions.

This makes it possible to:

• run Lua commands interactively
• reuse functions defined in previously loaded scripts
• experiment with Lua code without restarting the interpreter
• avoid repeated initialization overhead when working with large scripts

---

Starting Interactive Script Mode

To start interactive script mode, press:

Ctrl-t r

Tio displays the script prompt:

[08:45:46.514] Run Lua script
[08:45:46.514] Enter file name or "!" Lua commands or "@" interpreter directive:
>>

At this prompt you can:

Input	Description
filename	Execute a Lua script file
!commands	Execute Lua commands
@directive	Execute an interpreter control directive

You can use the cursor keys and backspace key to edit the line and recall command history. The history is maintained while tio is running.

---

Running a Script File

To execute a Lua script file, enter the filename at the prompt.

Example script (banner.tio):

function tio.banner()
    local banner = [[
 _    _               _                _               __
| |_ (_)  ___    ___ | |_  __ _  _ __ | |_      _      \ \
| __|| | / _ \  / __|| __|/ _` || '__|| __|    (_)_____ | |
| |_ | || (_) | \__ \| |_| (_| || |   | |_  _   _|_____|| |
 \__||_| \___/  |___/ \__|\__,_||_|    \__|(_) (_)      | |
                                                       /_/
]]
    tio.echo(string.gsub(banner, "\n", "\r\n"))
end

tio.banner()

Run the script:

>> banner.tio
[09:08:13.786] Running script banner.tio
 _    _               _                _               __
| |_ (_)  ___    ___ | |_  __ _  _ __ | |_      _      \ \
| __|| | / _ \  / __|| __|/ _` || '__|| __|    (_)_____ | |
| |_ | || (_) | \__ \| |_| (_| || |   | |_  _   _|_____|| |
 \__||_| \___/  |___/ \__|\__,_||_|    \__|(_) (_)      | |
                                                       /_/

The script is loaded and executed immediately. Any functions defined in the script remain available in the interpreter.

---

Executing Lua Commands

Lua commands can be executed directly by prefixing them with !.

This allows you to interact with previously defined functions or variables.

Example script (calc_sum.tio):

function tio.calc_sum(t)
    local sum = 0
    for _, v in ipairs(t) do
        sum = sum + v
    end
    return sum
end

function tio.disp_sum(t)
    local sum = tio.calc_sum(t)
    tio.echo(sum)
    tio.echo("\r\n")
end

Example session:

>> calc_sum.tio
[09:15:22.372] Running script calc_sum.tio

<<press Ctrl-t r again>>
>> !t = {1,2,3,4,5,6,7,8,9,10}

<<press Ctrl-t r again>>
>> !tio.disp_sum(t)
55
>> !sum = tio.calc_sum(t); tio.echo(sum); tio.echo("\r\n")
55

---

Interpreter Directives

Interpreter behavior can be controlled using directives prefixed with @.

@new

Restart the script interpreter.

All interpreter state is cleared and the interpreter is reinitialized.

If a script-init-file is configured, it is executed again.

---

@doopt

Execute the script specified by the script or script-file option, if present.

---

@nuldo=opt

If Ctrl-t r is pressed and Enter is pressed without entering a command, @doopt is executed.

This is the default behavior for compatibility with Tio v3.9.

---

@nuldo=none

If Ctrl-t r is pressed and Enter is pressed without entering a command, no action is performed.

This helps prevent accidental script execution.

---

@repl

Start REPL (Read–Eval–Print Loop) mode.

---

REPL Mode

Enter:

@repl

to start REPL mode.

In REPL mode:

• Lua commands can be entered continuously
• each line is executed immediately
• multi-line statements can be continued using a trailing \
• @exit leaves REPL mode

Example:

[10:17:30.215] Run Lua script
[10:17:30.215] Enter file name or "!" Lua commands or "@" interpreter directive:
>> @repl
[10:17:31.956] Enter Lua REPL mode (@exit to exit)
>> p=1
>> for i=1,10 do\
>>     p = p * i\
>> end
>> print(p, "\r")
3628800
>> @exit

---

Summary

The interactive Lua scripting interface provides:

• persistent interpreter state
• interactive Lua command execution
• script reuse without interpreter restart
• an integrated REPL environment

These capabilities make it easier to develop, test, and experiment with Tio scripts while the program is running.

Enjoy using Tio's Interactive Lua Scripting.