flatt
Flatbuffers code reflection based generation tool with scripting support.
Why?
Flatbuffers is awesome, but you'll eventually need to (or wish you could) write additional code generation steps for your schema files. For example, generating a network protocol handler/dispatcher for you client and server and keep them in sync.
How does it work?
flatt
exposes a lua
runtime with some additional helper functions to help you deal with Flatbuffers schema files, reflection and template rendering. You can for example write a flatt
script that will reflect your schema, manipulate that data, and render (using a template engine or not) a file with the content you just processed.
All builtin lua libraries are exported and you can use luarocks
packages with it if you want to.
An example of what a flatt script looks like:
-- luarocks install lunajson
local lunajson = require("lunajson")
flatt.log.info("Generating headers...")
flatt.flatc({ "--cpp", "./schema.fbs" })
local json = flatt.reflect("./schema.fbs")
flatt.log.trace(json)
--[[
{
"tables": [
{
"id": 182975129,
"name": "MyTable",
"namespace": "my.namespace",
"fields": [
{
"name": "some_field",
...
}
]
}
...
],
"structs": [
...
],
...
}
]]
local info = lunajson.decode(json)
-- generate a file using `info` data
Usage
Installation
npm install -g flatt
Requirements
- Windows (PRs welcome to add Linux+WSL and Mac support)
Overview
flatt some/project.lua
Building
Requirements
- Windows
- Visual Studio 2022
- CMake
- Conan
- Node.js
Compiling
npm install && npm run build
API
vars
flatt.vars.flatt_dir
Has the flatt
executable directory.
flatt.vars.project_dir
Project directory (from the given project script file).
flatt.vars.argv
A table (list) of arguments passed next to the script file.
$ flatt project.lua --hello --world abc 123
flatt.vars.argv
-- { "--hello", "--world", "abc", "123" }
flatt.vars.argv[1]
-- { "--hello" }
-- `luarocks install argparse`
local argparse = require("argparse")
local parser = argparse("example", "Arguments example.")
parser:flag("-h --hello", "Hello argument.", "")
parser:flag("-w --world", "World argument.", "")
parser:argument("a", "Some value")
parser:argument("b", "Some value")
local args = parser:parse(flatt.vars.argv)
args.hello
-- true
args.world
-- false
args.a
-- "abc"
args.b
-- "123"
flatc
flatt.flatc(arguments)
flatt.flatc({ "--cpp", "schema.fbs" })
-- return: the exit code
shell
flatt.shell(command, arguments)
flatt.shell("echo", { "hello", "world" })
-- return: the exit code
reflect
flatt.reflect(path)
flatt.reflect("schema.fbs")
--[[
{
// JSON encoded schema
}
]]
log
Functions
Level
list
trace
debug
info
warn
error
critical
flatt.file.set_level(level)
flatt.log.set_level("info")
-- Sets the current logging level
flatt.file.get_level()
flatt.log.get_level()
-- Gets the current logging level
flatt.file.trace(line)
flatt.log.trace("log line")
-- Writes to console in white (windows)
flatt.file.trace(line)
flatt.log.trace("log line")
-- Writes to console in white (windows)
flatt.file.debug(line)
flatt.log.debug("log line")
-- Writes to console in blue (windows)
flatt.file.info(line)
flatt.log.info("log line")
-- Writes to console in green (windows)
flatt.file.warn(line)
flatt.log.warn("log line")
-- Writes to console in yellow (windows)
flatt.file.error(line)
flatt.log.error("log line")
-- Writes to console in red (windows)
flatt.file.critical(line)
flatt.log.critical("log line")
-- Writes to console in white with red background (windows)
file
Functions
flatt.file.write(path, data)
flatt.dir.read("hello.txt", "Hello world!)
-- return: "Hello world!"
flatt.file.read(path)
flatt.dir.read("hello.txt")
-- return: "Hello world!"
flatt.file.exists(path)
flatt.dir.exists("./non-existing-file.ext")
-- return: false
flatt.dir.exists("hello.txt")
-- return: true
flatt.file.hash(path)
flatt.dir.hash("./non-existing-file.ext")
-- return: nil
flatt.dir.hash("some-file.ext")
-- return: "EDCBA5DD333A60F3C98452672A1AB1711409040D"
dir
Functions
flatt.dir.hash(path)
flatt.dir.hash("./non-existing-dir")
-- return: nil
flatt.dir.hash(".")
-- return: "4CF8ADEDB3B43E78645E4DE673D2D7DD4CFADA58"
templates
Builtin provided template engine functions (inja).
Use aspect
for a more Lua friendly template system.
Functions
flatt.templates.render_string(template, data)
Accepts JSON encoded string for data.
flatt.templates.render_string("hello {{name}}", "{\"name\":\"world\"}")
-- return: "hello world"
flatt.templates.render_file(src, dest, data)
Accepts JSON encoded string for data.
flatt.templates.render_string("template.txt", "output.txt", "{\"name\":\"world\"}")
-- return: true
string
Functions
flatt.string.pad_left(string, len, pad = " ")
flatt.string.pad_left("1234", 8)
-- return: " 1234"
flatt.string.pad_left("1234", 8, "0")
-- return: "00001234"
flatt.string.pad_right(string, len, pad = " ")
flatt.string.pad_left("1234", 8)
-- return: "1234 "
flatt.string.pad_right("1234", 8, "0")
-- return: "12340000"
flatt.string.starts_with(string, string)
flatt.string.starts_with("hello world", "hello")
-- return: true
flatt.string.starts_with("hello world", "world")
-- return: false
flatt.string.ends_with(string, string)
flatt.string.ends_with("hello world", "hello")
-- return: false
flatt.string.ends_with("hello world", "world")
-- return: true
flatt.string.split(string, delim, limit = 0)
flatt.string.split("hello world", " ")
-- return: {"hello", "world"}
flatt.string.split("is this real life", " ", 3)
-- return: {"is", "this", "real life"}
flatt.string.trim(string)
flatt.string.trim(" hello world ")
-- return: "hello world"
flatt.string.trim_left(string)
flatt.string.trim(" hello world ")
-- return: "hello world "
flatt.string.trim_right(string)
flatt.string.trim(" hello world")
-- return: "hello world "
flatt.string.explode(string)
Splits the string whenever one of the following characters is found:
. -_|/\
flatt.string.explode("a.b c-d|e/f\\g")
-- return: { "a", "b", "c", "d", "e", "f", "g" }
flatt.string.join(strings, delim = ",")
flatt.string.join({ "a", "b", "c", "d", "e", "f", "g" }, "~")
-- return: "a~b~c~d~e~f~g"
flatt.string.lower_case(string)
flatt.string.lower_case("NewGUIAlertBox")
-- return: "newguialertbox"
flatt.string.upper_case(string)
flatt.string.upper_case("NewGUIAlertBox")
-- return: "NEWGUIALERTBOX"
flatt.string.ucfirst(string)
flatt.string.ucfirst("NewGUIAlertBox")
-- return: "NewGUIAlertBox"
flatt.string.lcfirst(string)
flatt.string.lcfirst("NewGUIAlertBox")
-- return: "newGUIAlertBox"
flatt.string.snake_case(string)
flatt.string.snake_case("NewGUIAlertBox")
-- return: "new_gui_alert_box"
flatt.string.kebab_case(string)
flatt.string.kebab_case("NewGUIAlertBox")
-- return: "new-gui-alert-box"
flatt.string.pascal_case(string)
flatt.string.pascal_case("NewGUIAlertBox")
-- return: "NewGuiAlertBox"
flatt.string.camel_case(string)
flatt.string.camel_case("NewGUIAlertBox")
-- return: "newGuiAlertBox"
flatt.string.const_case(string)
flatt.string.const_case("NewGUIAlertBox")
-- return: "NEW_GUI_ALERT_BOX"
flatt.string.train_case(string)
flatt.string.train_case("NewGUIAlertBox")
-- return: "New-Gui-Alert-Box"
flatt.string.ada_case(string)
flatt.string.ada_case("NewGUIAlertBox")
-- return: "New_Gui_Alert_Box"
flatt.string.cobol_case(string)
flatt.string.cobol_case("NewGUIAlertBox")
-- return: "NEW-GUI-ALERT-BOX"
flatt.string.dot_case(string)
flatt.string.dot_case("NewGUIAlertBox")
-- return: "new.gui.alert.box"
flatt.string.path_case(string)
flatt.string.path_case("NewGUIAlertBox")
-- return: "new/gui/alert/box"
flatt.string.space_case(string)
flatt.string.space_case("NewGUIAlertBox")
-- return: "new gui alert box"
flatt.string.capital_case(string)
flatt.string.capital_case("NewGUIAlertBox")
-- return: "New Gui Alert Box"
flatt.string.cpp_case(string)
flatt.string.cpp_case("NewGUIAlertBox")
-- return: "new::gui::alert::box"