HDF

Beginners Guide to LUTX

LUTX is a lean, powerful tool for generating configuration files from data. It uses the HDF (Human Data Form) format for data and a Lisp-inspired template system.

1. The Core Idea

To use LUTX, you need two things:
  1. A Dataset (.hdf): Where your information lives.
  2. A Template (.lutx or .tpl): A text file with placeholders like ${name}.
LUTX combines them to create your final configuration file.

2. Your First "No-Lua" Template

The easiest way to use LUTX is the Simple Query mode. You don't need to know any programming; just use placeholders.

Step 1: Create your Data (inventory.hdf)

Save this as inventory.hdf. It contains a list of server records. 
(servers
  (server 
    (id "web-01") 
    (ip "10.0.0.1") 
    (role "frontend")
  )
  (server 
    (id "db-01")  
    (ip "10.0.0.5") 
    (role "database")
  )
)

Step 2: Create your Template (config.tpl)

Save this as config.tpl. Notice there is no code here, just placeholders. 
# Configuration for ${id}
# Role: ${role}
Address: ${ip}
Status: Online

Step 3: Run LUTX

Tell LUTX to look in inventory.hdf for a server where id is web-01: 
lua lutx.lua --dataset inventory.hdf --simple-query 'servers.(id=web-01)' config.tpl
The Output: 
# Configuration for web-01
# Role: frontend
Address: 10.0.0.1
Status: Online

3. Powerful Placeholders

LUTX placeholders (${...}) do more than just simple replacement.

Default Values

If a value might be missing, provide a default using :-. 
Port: ${port:-8080}
If port isn't in your data, it will output 8080.

Nested Variables

You can use variables to choose other variables. 
# Data: (lang "en") (msg_en "Hello") (msg_es "Hola")
Greeting: ${msg_${lang}}
This resolves to ${msg_en} which becomes Hello.

Environment Variables

You can access your system's environment variables directly. 
User Home: ${os.getenv('HOME')}

4. Advanced: Generating Multiple Files

If you want to generate a file for every item in your dataset at once, you can embed a small amount of Lua code.

The Template (generate_all.lutx)

{{ 
  -- Find all servers
  local all = hdf_query("servers.server")
  
  for _, s in ipairs(all) do
    -- Create a config string for this server
    local content = string.format("IP=%s
ROLE=%s
", s.ip, s.role)
    
    -- Save it to a file automatically!
    save("configs/" .. s.id .. ".conf", content)
  end
}}
Successfully generated {{ echo(#all) }} files.

The Command

lua lutx.lua --dataset inventory.hdf generate_all.lutx

5. CLI Cheat Sheet

Command Description
--dataset path.hdf Load a data file.
--dataset name=path.hdf Load a data file and give it a name for specific queries.
--simple-query 'Path.(Key=Val)' Select one record and inject its fields as variables.
--output filename Save the main template output to a file instead of the screen.
\${VAR} Escape a variable if you want the literal text ${VAR} in your file.

6. Summary for Beginners

  1. Organize data in HDF using nested parentheses: (key "value").
  2. Write templates using ${variable_name} for values.
  3. Use --simple-query to pick one specific "row" from your data.
  4. Use save("path", content) inside {{ ... }} blocks if you need to output many files at once.