TOML Editor - Terminal User Interface

A powerful, keyboard-driven TUI application for creating and editing TOML configuration files with template support and real-time validation.

🚀 Quick Start

# Install dependencies (Ubuntu/Debian)
sudo apt-get install build-essential libncurses5-dev

# Build
make

# Run
./bin/toml-editor

New to the editor? Start with QUICKSTART.md for a 5-minute tutorial.

Features

• ✨ Full-featured TUI - Built with ncurses for a responsive terminal interface
• 📝 Create & Edit - Create new TOML files or edit existing ones
• 🎨 Syntax Highlighting - Color-coded display for sections, keys, values, and comments
• 📋 Template Support - Load pre-defined templates from the templates/ directory
• ✅ Real-time Validation - Uses toml-c library to validate TOML syntax before saving
• 🔍 Preview Changes - Review modifications before committing to disk
• 💾 Safe Saving - Warns before overwriting existing files with save-as option
• ⌨️ Keyboard Navigation - Fully navigable with arrow keys and shortcuts
• 📊 Line Management - Insert, edit, and delete lines with ease
• 💬 Comment Preservation - Maintains all comments when editing files

Requirements

• GCC compiler (C11 or later)
• ncurses library
• make

Installing Dependencies

Ubuntu/Debian:

sudo apt-get install build-essential libncurses5-dev libncursesw5-dev

Fedora/RHEL:

sudo dnf install gcc make ncurses-devel

Arch Linux:

sudo pacman -S base-devel ncurses

macOS:

brew install ncurses

Building

1. Clone or download this repository
2. Navigate to the project directory
3. Build the project:

make

The executable will be created at bin/toml-editor.

Build Options

• make all - Build the project (default)
• make clean - Remove build artifacts
• make debug - Build with debug symbols
• make run - Build and run the program
• make install - Install to /usr/local/bin (requires sudo)
• make uninstall - Remove from /usr/local/bin (requires sudo)

Usage

Running the Editor

./bin/toml-editor

Or if installed:

toml-editor

Main Menu Options

1. Create new TOML file from template - Select from available templates in templates/
2. Create new TOML file (blank) - Start with an empty file
3. Open existing TOML file - Load and edit an existing TOML file
4. ESC - Exit the application

Editor Keyboard Shortcuts

Key	Action
↑ / ↓	Navigate up/down through lines
E	Edit the current line
I	Insert a new line after the current line
D	Delete the current line
P	Preview changes before saving
S	Save the file
ESC	Return to main menu (warns if unsaved changes)

File Input Mode

• Type the file path/name
• Press ENTER to confirm
• Press ESC to cancel

Save Confirmation

When saving a file that already exists:

• S - Overwrite the existing file
• N - Save as a new filename
• ESC - Cancel and return to editing

Templates

Templates are TOML files stored in the templates/ directory. The editor will automatically detect and list all .toml files in this directory.

Creating Templates

1. Create a .toml file in the templates/ directory
2. Add your template content with placeholders or default values
3. The template will appear in the template selection menu

Included Templates

• basic.toml - Simple configuration with owner and database sections
• config.toml - Application configuration with server, logging, and plugins

TOML Validation

The editor uses the toml-c library for parsing and validation. Before saving, the editor validates that:

• All TOML syntax is correct
• Sections are properly formatted
• Key-value pairs are valid
• Arrays and tables are correctly structured

If validation fails, the editor will display an error message and prevent saving until the issues are resolved.

Line Types

The editor recognizes and color-codes different line types:

• Comments - Lines starting with # (Magenta)
• Sections - Lines like [section] (Cyan, Bold)
• Array Tables - Lines like [[array]] (Cyan, Bold)
• Key-Value Pairs - Lines with key = value (Green)
• Empty Lines - Blank lines (No color)
• Invalid Lines - Syntax errors (Red)

Project Structure

mag-cfg-c/
├── assets/              # Documentation and specifications
├── bin/                 # Compiled executable
├── build/               # Object files
├── include/             # Header files (toml.h, toml.c)
├── src/                 # Source code
│   ├── main.c          # Main entry point
│   ├── init.c          # Initialization and utilities
│   ├── file_ops.c      # File operations and TOML validation
│   ├── ui_render.c     # UI rendering functions
│   ├── input_handler.c # Input handling
│   └── toml_editor.h   # Header with data structures
├── templates/           # TOML templates
├── Makefile            # Build configuration
└── README.md           # This file

Technical Details

Data Structures

• EditorState - Main state container for the entire application
• EditorLine - Represents a single line with content, type, and modification status
• Template - Template metadata (name and path)

Editor Modes

• MODE_MENU - Main menu
• MODE_TEMPLATE_SELECT - Template selection
• MODE_FILE_INPUT - File path input
• MODE_EDIT - Main editing mode
• MODE_PREVIEW - Preview changes
• MODE_SAVE_CONFIRM - Save confirmation dialog
• MODE_SAVE_AS - Save as new filename

TOML-C Integration

The editor uses toml-c in "header-only mode" by including both toml.h and toml.c. The library is used for:

1. Parsing existing files - Load and validate TOML structure
2. Validation before save - Ensure syntax correctness
3. Error reporting - Provide detailed error messages

Limitations

• Maximum 1000 lines per file
• Maximum 1024 characters per line
• Maximum 50 templates
• Lines longer than screen width are truncated in display (but preserved in file)

Troubleshooting

Build Errors

Error: ncurses.h not found

• Install ncurses development libraries (see Requirements section)

Error: toml.h not found

• Ensure include/toml.h and include/toml.c exist
• Re-run the download commands from the build instructions

Runtime Issues

Terminal display issues

• Ensure your terminal supports colors
• Try resizing the terminal window
• Check that TERM environment variable is set correctly

File permission errors

• Ensure you have read/write permissions for the target directory
• Check that the templates/ directory exists and is readable

Contributing

Contributions are welcome! Please ensure:

1. Code follows the existing style
2. All features are tested
3. Documentation is updated
4. Commit messages are clear

License

This project is provided as-is for educational and practical use.

Credits

• toml-c library by CK Tan - https://github.com/cktan/tomlc99
• ncurses library for terminal UI

Future Enhancements

Potential features for future versions:

• Search and replace functionality
• Undo/redo support
• Multi-line value editing
• Inline help for TOML syntax
• Configuration file for editor settings
• Export to JSON/YAML
• Syntax error highlighting with line numbers
• Mouse support
• Copy/paste between lines
• Bookmarks for quick navigation

Contact

For issues, questions, or suggestions, please refer to the project repository or documentation.