Skip to content

wsdjeg/toml.nvim

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

toml.nvim

Run Tests GitHub License GitHub Issues or Pull Requests GitHub commit activity GitHub Release luarocks

📘 Intro

toml.nvim is a TOML parser API for Neovim, providing toml.parse() and toml.parse_file() to parse TOML strings and files into Lua tables. No external dependencies required.

✨ Features

  • 📄 Parse Strings & Files - toml.parse(text) and toml.parse_file(filename)
  • 🔢 Full Type Support - Strings, integers (hex/octal/binary), floats, booleans, datetimes
  • 📊 Tables - Standard tables, inline tables, array of tables, dotted keys
  • 📝 Arrays - Mixed types, nested arrays
  • 💬 Comments - Inline and full-line comments
  • 🚫 Zero Dependencies - Pure Lua implementation, no external libraries needed

📦 Installation

Using nvim-plug:

require('plug').add({
  {
    'wsdjeg/toml.nvim',
  },
})

Using LuaRocks:

luarocks install toml.nvim

🔧 API

Function Description
toml.parse(text) Parse a TOML string, returns a Lua table
toml.parse_file(filename) Parse a TOML file, returns a Lua table

⚙️ Usage

Parse a string

local toml = require('toml')

local text = [[
title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [8001, 8001, 8002]
]]

local data = toml.parse(text)
print(data.title)             --> "TOML Example"
print(data.owner.name)        --> "Tom Preston-Werner"
print(data.database.enabled)  --> true
print(data.database.ports[2]) --> 8001

Parse a file

local toml = require('toml')

local config = toml.parse_file('.stylua.toml')
vim.print(config)
-- {
--   call_parentheses = "Always",
--   column_width = 100,
--   indent_type = "Spaces",
--   indent_width = 2,
--   line_endings = "Unix",
--   quote_style = "AutoPreferSingle"
-- }

Error handling

toml.parse and toml.parse_file raise an error on invalid TOML. Use pcall to handle it gracefully:

local toml = require('toml')

local ok, result = pcall(toml.parse, 'invalid = = toml')
if not ok then
  print('Parse error: ' .. result)
end

📖 TOML Features

Strings

local data = toml.parse([[
basic = "hello world"
literal = 'C:\Users\name\not_escape'
multiline = """
first line
second line"""
]])

print(data.basic)     --> hello world
print(data.literal)   --> C:\Users\name\not_escape
print(data.multiline) --> first line
                       --  second line

Integers

local data = toml.parse([[
decimal = 42
hex     = 0xFF
octal   = 0o17
binary  = 0b1010
]])

print(data.decimal) --> 42
print(data.hex)     --> 255
print(data.octal)   --> 15
print(data.binary)  --> 10

Floats and booleans

local data = toml.parse([[
pi    = 3.14
ratio = 0.5
flag  = true
off   = false
]])

print(data.pi)   --> 3.14
print(data.flag) --> true
print(data.off)  --> false

Arrays

local data = toml.parse([[
ints   = [1, 2, 3]
nested = [[1, 2], [3, 4]]
mixed  = ["a", "b", "c"]
]])

print(data.ints[1])      --> 1
print(data.nested[2][1]) --> 3
print(data.mixed[3])     --> c

Tables

local data = toml.parse([[
[a.b.c]
key = "value"
]])

print(data.a.b.c.key) --> value

Inline tables

local data = toml.parse([[
point = { x = 1, y = 2 }
]])

print(data.point.x) --> 1
print(data.point.y) --> 2

Array of inline tables

local data = toml.parse([[
authors = [
  { name = "Alice", email = "alice@example.com" },
  { name = "Bob",   email = "bob@example.com" },
]
]])

print(data.authors[1].name)  --> Alice
print(data.authors[2].email) --> bob@example.com

Array of tables

local data = toml.parse([[
[[fruits]]
name = "apple"

[[fruits]]
name = "banana"
]])

print(data.fruits[1].name) --> apple
print(data.fruits[2].name) --> banana

Dotted keys

local data = toml.parse('a.b.c = "deep"')

print(data.a.b.c) --> deep

Comments

local data = toml.parse([[
# server config
port = 8080  # default port
]])

print(data.port) --> 8080

💡 Practical Examples

Parse Cargo.toml (Rust)

local toml = require('toml')

local cargo = toml.parse_file('Cargo.toml')

-- Access package metadata
print(cargo.package.name)
print(cargo.package.version)
print(cargo.package.edition)

-- Iterate over dependencies
for name, version in pairs(cargo.dependencies or {}) do
  print(name, version)
end

Parse pyproject.toml (Python)

local toml = require('toml')

local project = toml.parse_file('pyproject.toml')

-- Access build system info
print(project['build-system']['build-backend'])

-- Access project metadata
print(project.project.name)
print(project.project.version)

-- Iterate over authors (array of inline tables)
for _, author in ipairs(project.project.authors or {}) do
  print(author.name, author.email)
end

-- Get dependencies
for _, dep in ipairs(project.project.dependencies or {}) do
  print(dep)
end

📣 Self-Promotion

If you like this plugin, please star it on GitHub. Also check out my other Neovim plugins:

🙏 Acknowledgments

This project is forked from SpaceVim's toml API. Thanks to the SpaceVim team for the original implementation.

💬 Feedback & License

toml.nvim is released under the GPL-3.0 License.

About

toml parser for neovim

Topics

Resources

License

Stars

9 stars

Watchers

0 watching

Forks

Sponsor this project

Contributors