Overview

Lumarsh is a small Lua script runner (powered by Lumars) with a small built-in library primarily for use with shell scripts.

Installation

Either compile it yourself with dub build -b release or fetch it from the latest release page.

e.g.

curl -o lumarsh -L https://github.com/BradleyChatha/lumarsh/releases/download/v0.2.2/lumarsh
chmod +x lumarsh
mv lumarsh /usr/local/bin

Using Lumarsh

There are two ways to use Lumarsh:

• Execute a file lumarsh file_name
• Execute a string lumarsh execute "print('henlo world!')"

Additionally any extra args are directly passed into the script via the LUMARSH_ARGS global variable:

for i,v in ipairs(LUMARSH_ARGS) do
    print(i,v)
end

Library

While Lumarsh does support luarocks my aim is to not have to rely on it for most operations, so Lumarsh provides a decent set of libraries that are helpful for processing data.

An EmmyLua file is provided for editors with EmmyLua support, which serves as an overview of the API.

Lumarsh provides the following libraries:

• sh.path - Exposes std.path into Lua.
• sh.proc - Exposes std.process into Lua.
• sh.fs - Exposes std.file into Lua.
• sh.regex - Exposes std.regex into Lua.
• sh.json - Exposes std.json into Lua.

Additionally, the following third party libraries are bundled with Lumarsh:

• luafun - Provides high-performance functional programming
  • luafun is added into the global scope, so you can simply go range(0, 10, 2):each(print) easily.

I'm very willing to add more into lumarsh, so please tell me any suggestions you may have.

Luarocks support

If luarocks can be detected then lumarsh will set the LUA_PATH and LUA_CPATH variables to the output of luarocks path --lua-version 5.1.

Please note lumarsh only supports Lua 5.1 as that's the only version lumars supports

When installing packages, make sure to pass --lua-version 5.1 into luarocks, otherwise it might not be in the correct location.

If you're getting an error such as cannot find module luarocks.loader, then try the following command:

luarocks install luarocks --lua-version 5.1

Execution shorthand syntax

Instead of calling sh.proc.executeEnforceZero directly, you can instead use the sh:COMMAND(ARGS) shortcut:

print(sh.proc.executeEnforceZero("echo", {"This is what you'd normally do"}).output)
print(sh:echo("But instead, you can do this!").output)

Additionally, you can chain calls together to pass the output of one command into another's stdin:

-- Conventional way (If you don't specify `.output`, then the command's output is sent to stdin)
print(sh.proc.executeShell("grep", {"import", sh.proc.executeShell("cat", {"./source/api/execute.d"})}).output)

-- Easier way
print(
    sh:cat("./source/api/execute.d")
      :grep("import")
      .output
)

Remember, call .output on a result object if you don't want it's data being sent to stdin!

-- Good
print(
    sh:echo("This is my License: ", sh:cat("./LICENSE.md").output).output
)

-- Bad
print(
    sh:echo("This is my License: ", sh:cat("./LICENSE.md")).output
)

Command echoing

By default lumarsh will echo the output of any command it runs.

To disable this, please set sh.echo to false.