literal

literal is a library for safe evaluation of Lua literal expressions, written in pure Lua. It can evaluate literals like nil, true, false, decimal and hexadecimal numerical constants, short and long strings, and tables of other literals. It can use grammar of Lua 5.1 or Lua 5.2, and provides error messages similar to those of Lua compiler.

Contents

• Usage
• Documentation
• Installation
• Testing
• License

Usage

Importing

This works:

local literal = require "literal"

This doesn't work:

require "literal"

Evaluating

Evaluate strings using literal.eval function. Pass a string as the first argument.

local s = [[
{
	foo = "bar", -- Comments are skipped
	true,
	[0xFFA] = [=[baz]=]
}

-- Whitespace and comments before and after literal are discarded as well
]]

local t = literal.eval(s)
print(t.foo) -- bar
print(t[1]) -- true
print(t[4090]) -- baz

literal.eval raises an error if the string is not a valid literal.

local s = [[
{
   foo = "bar"
]]

local t = literal.eval(s)
-- Raises: [string "{..."]:3: '}' expected (to close '{' at line 1) near <eof>

literal.eval takes two optional arguments. The first one should be a string 5.1 or 5.2 and specifies which grammar will be used. By default, it is the grammar of the Lua version used to run literal.

local s = "0x1p1"
print(literal.eval(s, "5.2")) -- 2
literal.eval(s, "5.1")
-- Raises: [string "0x1p1"]:1: <eof> expected near 'p1'

The second optional argument sets the filename to be used in error messages.

local s = "0x1p1"
literal.eval(s, "5.1", "test.lua")
-- Raises: test.lua:1: <eof> expected near 'p1'

Evaluating configuration files

It is common to use Lua scripts as configuration files. Usually such files consist of several assignments in form name = expression. In this case, it is possible to load configuration using literal.eval_config.

local s = [[
foo = "bar"
names = {"Alice", "Bob"}

-- comments are allowed
enable_magic = true
]]

local config = literal.eval_config(s)
print(config.foo) -- bar
print(config.names[1] .. ", " .. config.names[2]) -- Alice, Bob
print(config.enable_magic and "Magic" or "No magic :(") -- Magic

Getting error message

literal.eval and literal.eval_config raise an error if the passed string is not valid. The error message can be extracted using pcall, but it will be automatically prepended with information about where the error was raised.

To avoid this, use literal.peval and literal.peval_config, which return a boolean flag indicating success of evaluation and the result or error message.

For more information, see documentation.

Documentation

LDoc generated documentation is available in doc directory. It can be viewed online here.

Installation

Using luarocks

Installing literal using luarocks is easy.

luarocks install literal

Problem with old luarocks versions

You may get an error like Parse error processing dependency '30log >= 0.7' if you use luarocks 2.1 or older. In this case, either upgrade to at least luarocks 2.1.1 or install 30log manually, then download the rockspec for literal, remove the line "30log >= 0.7" and run

luarocks install /path/to/literal/rockspec

Without luarocks

Download /src/literal.lua file and put it into the directory for libraries or your working directory. Install 30log using luarocks or manually download 30log.lua file from 30log repo.

Testing

literal comes with a testing suite located in spec directory. The requirements for testing are busted and serpent, both can be installed using luarocks. The command for running tests is

busted path/to/spec/directory

License

literal is public domain. See LICENSE file.