A Parser, Formatter, and Editor for jbeam Files
This project is a command-line tool designed to work with jbeam files (the structured, JSON-like format used in BeamNG to define vehicles, physics, and structures). Initially implemented in Haskell as a fast and robust demo, it has grown into a comprehensive utility for manipulating jbeam data.
- Parses entire
.jbeamfiles, including comments. - Ignores irrelevant whitespace.
- Handles both clean and manually edited files without breaking.
- Reformats the entire file with uniform indentation, spacing, and layout.
- Improves readability and maintainability of JBeam data.
- Sorts and sequentially renames all nodes (e.g.,
["bf1", ...]becomes["bf0", "bf1", "bf2"]). - Updates all references to renamed nodes throughout the file to prevent inconsistencies.
jbeam-edit supports user-defined rule files in JBFL (JBeam Formatting Language), a declarative mini-language for specifying formatting behavior.
.*.nodes[*][*] {
PadAmount: 8;
PadDecimals: 3;
}
.*.flexbodies[*] {
NoComplexNewLine: true;
}
- Target specific parts of the data tree using wildcard patterns.
- Control indentation, spacing, padding, and decimal precision.
- As a maintainer, enforce customized formatting rules to fit your preference.
When using jbeam-edit for the first time, you should generate a default formatting configuration file.
Run one of the following:
jbeam-edit -cminimal # Generates a simple, clean formatting config
jbeam-edit -ccomplex # Generates a more detailed and explicit configThis will create a file named rules.jbfl in your XDG config directory:
- On **Linux/macOS**:
$HOME/.config/jbeam-edit/rules.jbfl - On **Windows**:
%APPDATA%\jbeam-edit\rules.jbfl
This configuration will be used automatically when formatting files, unless a local .jbeam_edit.jbfl file is present in the current working directory.
You can override the global configuration on a per-project basis by placing a .jbeam_edit.jbfl= file in the root of your project.
After creating the user configuration with jbeam-edit -cminimal or jbeam-edit -ccomplex, you can copy that to your project if you want to apply specific rules on a per-project basis.
cp ~/.config/jbeam-edit/rules.jbfl ./.jbeam_edit.jbflOn Windows:
copy "%APPDATA%\jbeam-edit\rules.jbfl" .\.jbeam_edit.jbflThe presence of this file takes precedence over the global configuration and allows for project-specific formatting preferences.
For detailed example files and usage instructions, please see the dedicated examples documentation:
This contains sample .jbeam files and formatting rules to help you explore and test jbeam-edit’s features
- Integration with editors via Language Server Protocol (LSP)
- Indent JBFL property to specify number of spaces for indentation
- Detect support vertices (nodes with a high number of beam connections) and group them automatically.
- Handle cases where meta nodes (e.g.,
{"group":"..."}) interrupt node groups. - Allow prefix replacement via command-line arguments (e.g., replace
"bf"in nodes, beams, triangles, and flexbodies). - Expand test coverage.
- Add dedicated, curated example files to demonstrate typical workflows and tool capabilities.
(Currently available example
.jbeamfiles come from a collaborator’s real mod and serve as examples until we produce example files dedicated for the project.) - Improve documentation to support new contributors and clarify configuration use.
- Rapid Prototyping & Robustness - Haskell’s strong type system and expressive syntax allowed for quick development of a reliable prototype.
- Elegant Parser Composition - Utilizing the Parsec family of parser combinators enabled building modular, reusable components that make the parser clear and maintainable.
- Safe Data Transformation - Haskell’s emphasis on immutability and pure functions ensures that even complex transformations of your jbeam files are performed safely and predictably.
I have considered porting this project to C/C++ in the future.
Many developers running Windows already have Visual Studio and MSVC installed, so a C/C++ version might simplify the build process by eliminating the need for additional toolchains (like GHC).
Although a C/C++ rewrite might improve accessibility on Windows, it would come at the expense of Haskell’s expressive power, type safety, and the elegant parser composition facilitated by Parsec.
For now, the project remains a Haskell-based tool, but the idea of a C/C++ port is kept in mind as it might broaden the user base in the future.
- Haskell Compiler: GHC (https://www.haskell.org/ghc/)
- Build Tool: Stack (https://docs.haskellstack.org)
Clone the repository and build the project using your preferred Haskell build tool:
git clone https://github.com/webdevred/jbeam-tool.git
cd jbeam-tool
stack buildRun the tool from the command line as follows:
stack exec jbeam-tool -- [options] <input-file>The tool will:
- Parse the provided jbeam file.
- Format it according to the default or user-defined rules.
- Automatically sort nodes, rename them sequentially, and update all related references.
- By default, write the formatted output back to the file and create a backup file named <input-file>.bak.
- Use the `-i` or `–in-place` option to modify files directly **without** creating a backup.
Example:
jbeam-edit -i example.jbeamThis will update `example.jbeam` in place, skipping the backup creation step.
For full usage details and configuration options, please refer to EXPLANATION_OF_SOURCE_CODE.org
Contributions, bug reports, and feature requests are welcome!
This project is licensed under the BSD Clause 3 License – see the LICENSE file for details.
If you have any questions or suggestions, feel free to open an issue or contact me directly.
Happy parsing and formatting!