Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status

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.




This works:

local literal = require "literal"

This doesn't work:

require "literal"


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

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

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

local t = literal.eval(s)
print( -- 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( -- 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.


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


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.


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


literal is public domain. See LICENSE file.


Safely evaluate literal Lua expressions







No packages published