diff --git a/JBFL_DOCS.md b/JBFL_DOCS.md new file mode 100644 index 00000000..a4c1f4a0 --- /dev/null +++ b/JBFL_DOCS.md @@ -0,0 +1,149 @@ + +- [Configuration Documentation: Value Formatting Rules](#configuration-documentation-value-formatting-rules) +- [Overview](#overview) +- [Pattern Syntax](#pattern-syntax) +- [Properties Overview](#properties-overview) +- [How Matching Works](#how-matching-works) +- [Detailed Rules Examples](#detailed-rules-examples) + - [Pattern: `.*.nodes[*][*]`](#pattern-nodes) + - [Pattern: `.*.beams[*][*]`](#pattern-beams) +- [Padding Behavior on Scalar Values](#padding-behavior-on-scalar-values) +- [Examples](#examples) +- [Summary Table](#summary-table) +- [Notes and Tips](#notes-and-tips) + + +# Configuration Documentation: Value Formatting Rules + +This documentation describes the rule-based system for formatting values inside JBeam. It explains how to use pattern matching to target specific nodes and apply formatting settings during export. + +- Example ruleset file: [minimal.jbfl](examples/jbfl/minimal.jbfl) +- Example input: [minimal.jbeam](examples/jbeam/minimal.jbeam) +- Example result after formatting: [formatted_chevy_impala.jbeam](formatted_chevy_impala.jbeam) + +# Overview + +This configuration system allows users to define formatting rules for values inside nested objects and arrays. Rules consist of: + +- Patterns: that specify which data elements to match. +- Properties: that define how matched values are formatted. + +Typical use cases include: + +- Fixed-width data export +- Consistent floating-point number formatting +- Flattening nested arrays for output + +# Pattern Syntax + +| Pattern | Description | +|----------|----------------------------------------------------------------------------------| +| `.*` | Matches **any key** at the current object level, regardless of name. | +| `[*]` | Matches **all elements** in a list (1D array). | +| `[*][*]` | Matches **all elements in the innermost lists** of 2D arrays (arrays of arrays). | +| `.test` | Matches the value with key `test` in an object. | +| `[4]` | Matches the value at index 4 in an array. | + +# Properties Overview + +| Setting Name | Description | Applies To | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| +| `PadDecimals` | When non-zero, numeric values are padded with trailing zeros after the decimal point. The fractional part is extended to match the specified PadDecimals length. | Numeric values | +| `PadAmount` | Specifies the **total length** (number of characters) the formatted value should occupy. | Any scalar except for comments | +| `NoComplexNewLine` | When true, disables multiline or indented formatting for arrays, outputting values inline. | Any complex data structure | + +# How Matching Works + +- Patterns traverse nested objects and arrays. +- `.*` matches all keys at the current level. +- `[*]` matches all elements of an array. +- Combinations like `.*.nodes[*][*]` match all elements inside inner lists under `nodes` keys. +- Properties apply **to each matched value individually**. +- Matching is agnostic to the data type; however, settings may behave differently based on type. + +# Detailed Rules Examples + +## Pattern: `.*.nodes[*][*]` + +```jbfl +.*.nodes[*][*] { + PadDecimals: 3; + PadAmount: 8; +} +``` + +- Matches all values in the innermost arrays under the key `nodes`, where: + - The top-level element is an object with arbitrary keys. + - Each key references an object containing a key named `nodes`. + - The value of `nodes` is a 2D array (array of arrays). + - The rule applies to all numeric values in the innermost arrays of this 2D array. +- Properties: + - `PadDecimals: 3` + - `PadAmount: 8` +- Behavior: Format floats as fixed-width strings of length 8, padding with trailing zeros after the decimal point. + +Examples + +| Original Value | Initial width | Exported String | +|----------------|---------------|-----------------| +| 1.2 | 3 | 1.200000 | +| 3.14 | 3 | 3.140000 | +| 12.0 | 3 | 12.00000 | + +## Pattern: `.*.beams[*][*]` + +```jbfl +.*.beams[*][*] { + PadAmount: 8; +} +``` + +- Matches values in the innermost arrays under the key `beams`, where: + - The top-level element is an object with arbitrary keys. + - Each key references an object containing a key named `beams`. + - The value of `beams` is a 2D array (array of arrays). + - The rule applies to all numeric values in the innermost arrays of this 2D array. +- Properties: + - `PadAmount: 8` +- Behavior: Format floats as fixed-width strings of length 8, padded with leading spaces to align right. + +Examples: + +| Original Value | Initial width | Exported String | +|----------------|---------------|--------------------------------| +| 5.0 | 3 | 5.0 with 7 spaces before | +| 0.1234 | 6 | 0.1234 with 2 spaces before | +| 7.89 | 4 | 7.89 with 5 spaces before | + +# Padding Behavior on Scalar Values + +- Padding applies to **all scalar types** (numbers, strings, booleans). +- If the length of the representation of the scalar is **less than `PadAmount`**, the value is padded: + - With **trailing zeros** if `PadDecimals` is non-zero. + - With **leading spaces** otherwise. +- If the length is **equal to or greater than `PadAmount`**, **no padding or truncation occurs**; the full string is output as-is. + +# Examples + +| Value | Initial width | PadDecimals | PadAmount | Output | +|--------------|---------------|-------------|-----------|------------------------------| +| 3.14 | 3 | 3 | 8 | 3.140 | +| 3.14 | 3 | 0 | 8 | 3.14 with 4 spaces before | +| "abc" | 5 | 3 | 8 | "abc" with 3 spaces before | +| "abc" | 5 | 0 | 8 | "abc" with 3 spaces before | +| true | 4 | 0 | 6 | true with 2 spaces before | +| 123456789.0 | 11 | 0 | 5 | 123456789.0 | + +# Summary Table + +| Pattern | Targeted Data | Properties | Padding Behavior | +|------------------|---------------------------------|----------------|--------------------------------------------------------| +| `.*.nodes[*][*]` | Innermost float values in nodes | PadDecimals: 3 | Trailing zeros so fractional part is at least 3 digits | +| `.*.beams[*][*]` | Innermost float values in beams | PadAmount: 8 | Leading spaces | + +# Notes and Tips + +- Patterns are powerful and flexible; combine `.*`, `[ * ]`, and object keys to precisely target values. +- `PadDecimals` applies only to numbers, while `PadAmount` applies to all non-comment scalar values. +- String values receive space padding regardless of `PadDecimals`. +- Use `NoComplexNewLine` to simplify output layout when working with complex structures like lists and objects. diff --git a/JBFL_DOCS.org b/JBFL_DOCS.org deleted file mode 100644 index d5737a70..00000000 --- a/JBFL_DOCS.org +++ /dev/null @@ -1,140 +0,0 @@ -* Configuration Documentation: Value Formatting Rules - -This documentation describes the rule-based system for formatting values inside JBeam. It explains how to use pattern matching to target specific nodes and apply formatting settings during export. - -- Example ruleset file: [[file:examples/jbfl/minimal.jbfl][minimal.jbfl]] -- Example input: [[file:examples/jbeam/minimal.jbeam][minimal.jbeam]] -- Example result after formatting chevy_impala_fender.jbeam [[formatted_chevy_impala.jbeam]] - -* Overview - -This configuration system allows users to define formatting rules for values inside nested objects and arrays. Rules consist of: - -- Patterns - that specify which data elements to match. -- Properties - that define how matched values are formatted. - -Typical use cases include: - -- Fixed-width data export -- Consistent floating-point number formatting -- Flattening nested arrays for output - -* Pattern Syntax -|---------+--------------------------------------------------------------------------------| -| Pattern | Description | -|---------+--------------------------------------------------------------------------------| -| .* | Matches *any key* at the current object level, regardless of name. | -| [*] | Matches *all elements* in a list (1D array). | -| [*][*] | Matches *all elements in the innermost lists* of 2D arrays (arrays of arrays). | -| .test | Matches the value with key test in a object | -| [4] | Matches the value at index 4 in a array | -|---------+--------------------------------------------------------------------------------| - -* Properties Overview -|------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------| -| Setting Name | Description | Applies To | -|------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------| -| PadDecimals | When non-zero, numeric values are padded with trailing zeros after the decimal point. The fractional part is extended to match the specified PadDecimals length. | Numeric values | -| PadAmount | Specifies the *total length* (number of characters) the formatted value should occupy. | Any scalar except for comments | -| NoComplexNewLine | When true, disables multiline or indented formatting for arrays, outputting values inline. | Any complex data structure | -|------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------| - -* How Matching Works - -- Patterns traverse nested objects and arrays. -- .* matches all keys at the current level. -- [*] matches all elements of an array. -- Combinations like .*.nodes[*][*] match all elements inside inner lists under nodes keys. -- Properties apply *to each matched value individually*. -- Matching is agnostic to the data type; however, settings may behave differently based on type. - -* Detailed Rules Examples - -** Pattern: .*.nodes[*][*] -#+BEGIN_SRC -.*.nodes[*][*] { - PadDecimals: 3; - PadAmount: 8; -} -#+END_SRC - -- Matches all values in the innermost arrays under the key nodes, where: - - The top-level element is an object with arbitrary keys. - - Each key references an object containing a key named nodes. - - The value of nodes is a 2D array (array of arrays). - - The rule applies to all numeric values in the innermost arrays of this 2D array. -- Properties: - - PadZeros: true - - PadAmount: 8 -- Behavior: Format floats as fixed-width strings of length 8, padding with trailing zeros after the decimal point. - -Examples -|---------------+----------------|-----------------| -| Original Value| Initial width | Exported String | -|---------------+----------------|-----------------| -| 1.2 | 3 | 1.200000 | -| 3.14 | 3 | 3.140000 | -| 12.0 | 3 | 12.00000 | -|---------------+----------------|-----------------| - -** Pattern: .*.beams[*][*] - -#+BEGIN_SRC -.*.beams[*][*] { - PadAmount: 8; -} -#+END_SRC - -- Matches values in the innermost arrays under the key beams, where: - - The top-level element is an object with arbitrary keys. - - Each key references an object containing a key named beams. - - The value of beams is a 2D array (array of arrays). - - The rule applies to all numeric values in the innermost arrays of this 2D array. -- Properties: - - PadAmount: 8 - - PadZeros: false (implicitly) -- Behavior: Format floats as fixed-width strings of length 8, *padded with leading spaces* to align right. - -Examples: -|----------------+---------------+----------------------------------| -| Original Value | Initial width | Exported String | -|----------------+---------------+----------------------------------| -| 5.0 | 3 | 5.0 with 7 spaces before | -| 0.1234 | 6 | 0.1234 with 2 spaces before | -| 7.89 | 4 | 7.89 with spaces 5 spaces before | -|----------------+---------------+----------------------------------| - -* Padding Behavior on Scalar Values - -- Padding applies to *all scalar types* (numbers, strings, booleans). -- If the length of the representation of the scalar is *less than PadAmount*, the value is padded: - - With *trailing zeros* if PadZeros: true and the value is numeric. - - With *leading spaces* otherwise (including when PadZeros is false or not set). -- If the length is *equal to or greater than PadAmount*, *no padding or truncation occurs*; the full string is output as-is. - -* Examples -|-------------+---------------+-------------+-----------+----------------------------| -| Value | Initial width | PadDecimals | PadAmount | Output | -|-------------+---------------+-------------+-----------+----------------------------| -| 3.14 | 3 | 3 | 8 | 3.140 | -| 3.14 | 3 | 0 | 8 | 3.14 with 4 spaces before | -| "abc" | 5 | 3 | 8 | "abc" with 3 spaces before | -| "abc" | 5 | 0 | 8 | "abc" with 3 spaces before | -| true | 4 | 0 | 6 | true with 2 spaces before | -| 123456789.0 | 11 | 0 | 5 | 123456789.0 | -|-------------+---------------+-------------+-----------+----------------------------| - -* Summary Table -|----------------+---------------------------------+----------------+--------------------------------------------------------| -| Pattern | Targeted Data | Properties | Padding Behavior | -|----------------+---------------------------------+----------------+--------------------------------------------------------| -| .*.nodes[*][*] | Innermost float values in nodes | PadDecimals: 3 | Trailing zeros so fractional part is at least 3 digits | -| .*.beams[*][*] | Innermost float values in beams | PadAmount: 8 | Leading spaces | -|----------------+---------------------------------+----------------+--------------------------------------------------------| - -* Notes and Tips - -- Patterns are powerful and flexible; combine .*, [ * ], and object keys to precisely target values. -- The property PadDecimals only apply to Numbers while PadAmount can apply to all non-comment scalar values -- String values receive space padding regardless of PadDecimals. -- Use NoComplexNewLine to simplify output layout when working with complex structures like lists and objects. diff --git a/README.md b/README.md new file mode 100644 index 00000000..c9144ab0 --- /dev/null +++ b/README.md @@ -0,0 +1,127 @@ +# JBeam Tool in Haskell + +[![Build and test on Windows](https://github.com/webdevred/jbeam_edit/actions/workflows/build-and-test-windows.yaml/badge.svg?branch=master)](https://github.com/webdevred/jbeam_edit/actions/workflows/build-and-test-windows.yaml) +[![Build and test on Ubuntu](https://github.com/webdevred/jbeam_edit/actions/workflows/build-and-test-ubuntu.yaml/badge.svg?branch=master)](https://github.com/webdevred/jbeam_edit/actions/workflows/build-and-test-ubuntu.yaml) + + +- [JBeam Tool in Haskell](#jbeam-tool-in-haskell) + - [Features](#features) + - [Configuration](#configuration) + - [Usage](#usage) + - [Examples](#examples) + - [Explanation of Source Code](#explanation-of-source-code) + - [Planned Features / TODO](#planned-features-todo) + - [Why Haskell + Megaparsec?](#why-haskell-megaparsec) + - [Future Considerations](#future-considerations) + - [Prerequisites](#prerequisites) + - [Contributing & License](#contributing-license) + + +A fast, robust command-line parser, formatter, and editor for JBeam files, the JSON-like format used by BeamNG to define vehicles and physics structures. + +## Features + +- **Complete Parsing:** + Parses entire `.jbeam` files, including comments and irregular whitespace, without breaking on manual edits. + +- **Consistent Formatting:** + Uniform indentation, spacing, and layout for improved readability. + +- **Automatic Node Management:** + Renames nodes sequentially (e.g., `["bf1", ...]` → `["bf0", "bf1", "bf2"]`) and updates all references automatically. + +- **Configurable Formatting with JBFL:** + Customize formatting rules using JBFL, a mini-language to specify padding, decimals, indentation, and more with wildcard targeting. + + Example JBFL snippet: + + ```jbfl + .*.nodes[*][*] { + PadDecimals: 3; + PadAmount: 8; + } + + .*.flexbodies[*] { + NoComplexNewLine: true; + } + ``` + +## Configuration + +Generate a default formatting config with: + +```bash +jbeam-edit -cminimal # simple config +jbeam-edit -ccomplex # detailed config +``` + +Config files are saved in: + +- Linux/macOS: `$HOME/.config/jbeam-edit/rules.jbfl` +- Windows: `%APPDATA%\jbeam-edit\rules.jbfl` + +Override per project by placing `.jbeam_edit.jbfl` in your project root. + +## Usage + +Build and run: + +```bash +git clone https://github.com/webdevred/jbeam-tool.git +cd jbeam-tool +stack build +stack exec jbeam-tool -- [options] +``` + +Typical workflow: + +- Parses and formats the file. +- Sorts and renames nodes, updating references. +- Writes output back with a `.bak` backup by default. + +In-place editing (no backup): + +```bash +jbeam-edit -i example.jbeam +``` + +## Examples + +For sample `.jbeam` files and JBFL rule files, see the [Examples Directory README](examples/README.org). + +## Explanation of Source Code + +For an in-depth walkthrough of the implementation and design decisions, see [EXPLANATION_OF_SOURCE_CODE.org](EXPLANATION_OF_SOURCE_CODE.org). + +## Planned Features / TODO + +- Language Server Protocol (LSP) support +- Indent control in JBFL +- Automatic grouping of support vertices +- Meta node-aware sorting +- Prefix replacement via CLI arguments +- Expanded tests and example files +- Improved documentation + +## Why Haskell + Megaparsec? + +- Strong static typing for safer, reliable parsing and transformations. +- Elegant, composable parser combinators. +- Immutable data handling ensures predictable editing. + +## Future Considerations + +- Potential C/C++ port for easier Windows distribution. +- Trade-off: loss of Haskell’s expressiveness and safety vs. broader accessibility. + +## Prerequisites + +- GHC (The Glasgow Haskell Compiler) +- Stack build tool + +## Contributing & License + +Contributions and bug reports welcome. Licensed under BSD 3-Clause. + +Happy parsing and formatting! + diff --git a/README.org b/README.org deleted file mode 100644 index bf2cd4d6..00000000 --- a/README.org +++ /dev/null @@ -1,168 +0,0 @@ -* JBeam Tool in Haskell -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. - -** Features at a glance - -*** Complete File Parsing -- Parses entire =.jbeam= files, including comments. -- Ignores irrelevant whitespace. -- Handles both clean and manually edited files without breaking. - -*** Consistent Formatting -- Reformats the entire file with uniform indentation, spacing, and layout. -- Improves readability and maintainability of JBeam data. - -*** Automatic Node Management -- 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. - -*** Configurable Formatting Rules, Powered by JBFL -=jbeam-edit= supports user-defined rule files in JBFL (JBeam Formatting Language), a declarative mini-language for specifying formatting behavior. - -**** Example rule file (rules.jbfl) - -#+BEGIN_SRC jbfl -.*.nodes[*][*] { - PadAmount: 8; - PadDecimals: 3; -} - -.*.flexbodies[*] { - NoComplexNewLine: true; -} -#+END_SRC - -**** Capabilities of JBFL -- 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. - -** Configuration - -When using =jbeam-edit= for the first time, you should generate a default formatting configuration file. - -Run one of the following: - -#+BEGIN_SRC bash -jbeam-edit -cminimal # Generates a simple, clean formatting config -jbeam-edit -ccomplex # Generates a more detailed and explicit config -#+END_SRC - -This 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. - -*** Project-Specific Configuration - -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. - -#+BEGIN_SRC bash -cp ~/.config/jbeam-edit/rules.jbfl ./.jbeam_edit.jbfl -#+END_SRC - -On Windows: - -#+BEGIN_SRC powershell -copy "%APPDATA%\jbeam-edit\rules.jbfl" .\.jbeam_edit.jbfl -#+END_SRC - -The presence of this file takes precedence over the global configuration and allows for project-specific formatting preferences. - -** Examples - -For detailed example files and usage instructions, please see the dedicated examples documentation: - -[[examples/README.org][Examples Directory README]] - -This contains sample =.jbeam= files and formatting rules to help you explore and test jbeam-edit’s features - -** Planned Features / TODO - -- 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. -- Maintain and expand curated example files (=fender.jbeam=, =suspension.jbeam=) to demonstrate typical workflows and tool capabilities -- Improve documentation to support new contributors and clarify configuration use. - -** Why Haskell + Megaparsec - -- 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. - -** Future Considerations - -I have considered porting this project to C/C++ in the future. - -*** Ease of Distribution for Windows Users - 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). - -*** Trade-Offs - 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. - -** Getting Started - -*** Prerequisites - -- Haskell Compiler: GHC (https://www.haskell.org/ghc/) -- Build Tool: Stack (https://docs.haskellstack.org) - -*** Installation - -Clone the repository and build the project using your preferred Haskell build tool: - -#+BEGIN_SRC bash -git clone https://github.com/webdevred/jbeam-tool.git -cd jbeam-tool -stack build -#+END_SRC - -*** Usage - -Run the tool from the command line as follows: - -#+BEGIN_SRC bash -stack exec jbeam-tool -- [options] -#+END_SRC - -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 .bak. -- Use the `-i` or `--in-place` option to modify files directly **without** creating a backup. - -Example: - -#+BEGIN_SRC bash -jbeam-edit -i example.jbeam -#+END_SRC - -This 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][EXPLANATION_OF_SOURCE_CODE.org]] - - -*** Contributing - -Contributions, bug reports, and feature requests are welcome! - -*** License - -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! diff --git a/examples/README.org b/examples/README.md similarity index 56% rename from examples/README.org rename to examples/README.md index 35681dc3..9f0cd681 100644 --- a/examples/README.org +++ b/examples/README.md @@ -1,36 +1,46 @@ -* Examples Directory +# Examples Directory -This file guides you through example files and formatting rules to help you learn and test jbeam-edit’s features hands-on. It includes example JBeam files and JBFL rule files to explore the tool’s capabilities. + +- [Examples Directory](#examples-directory) + - [Example JBeam Files](#example-jbeam-files) + - [JBFL Configuration Files](#jbfl-configuration-files) + - [How JBFL Affects Formatting](#how-jbfl-affects-formatting) + - [Using These Examples](#using-these-examples) + -** Example JBeam Files +This file guides you through example files and formatting rules to help you learn and test jbeam-edit's features hands-on. It includes example JBeam files and JBFL rule files to explore the tool's capabilities. -- =fender.jbeam= - - A simple, clean example JBeam file demonstrating basic parsing and formatting. Running jbeam-edit on this file will: +## Example JBeam Files + +- `fender.jbeam` + - A simple, clean example JBeam file demonstrating basic parsing + and formatting. Running jbeam-edit on this file will: - Parse the entire structure including comments - Format the file with consistent indentation and spacing - Automatically sort and rename nodes sequentially (e.g., "bf1" becomes "bf0", etc.) - Update all references accordingly - Automatically move vertices into their correct groups (e.g., LeftTree, MiddleTree, RightTree) to maintain proper structure -- =suspension.jbeam= - - A complex example JBeam file modeling a vehicle suspension assembly. Running jbeam-edit on this file will: +- `suspension.jbeam` + - A complex example JBeam file modeling a vehicle suspension + assembly. Running jbeam-edit on this file will: - Parse all nodes, beams, and collision triangles - Sort and rename nodes with attention to structural relationships - Update beam references consistently with renamed nodes - Maintain groupings and structural integrity for suspension parts - - Demonstrate the tool’s capabilities on realistic, advanced files + - Demonstrate the tool's capabilities on realistic, advanced files -*Note:* This example will gain further advanced features soon, including improved vertex grouping, meta node handling, and better structural transformations as outlined in the [VertexTree Transformation Roadmap](https://github.com/webdevred/jbeam_edit/pull/2). +**Note:** This example will gain further advanced features soon, including improved vertex grouping, meta node handling, and better structural transformations as outlined in the [VertexTree Transformation Roadmap](https://github.com/webdevred/jbeam_edit/pull/2). -** JBFL Configuration Files +## JBFL Configuration Files -- =minimal.jbfl= +- `minimal.jbfl` Defines a minimal set of formatting rules, focusing on basic indentation and spacing. Ideal for quick, clean formatting without much customization. -- =complex.jbfl= - Contains detailed rules demonstrating advanced formatting capabilities such as controlling padding, decimal precision, and line breaks using JBFL patterns. +- `complex.jbfl` + Contains detailed rules demonstrating advanced formatting capabilities such as controlling padding, decimal precision, and line breaks using JBFL patterns. -** How JBFL Affects Formatting +## How JBFL Affects Formatting JBFL (JBeam Formatting Language) is a declarative mini-language that lets you specify how different parts of the JBeam file should be formatted: @@ -38,28 +48,30 @@ JBFL (JBeam Formatting Language) is a declarative mini-language that lets you sp - Control padding amounts, decimal precision, and newline behavior - Customize formatting to fit your preferences or project standards -By swapping between the minimal and complex JBFL configs, you can see how formatting behavior changes, making the tool flexible for different workflows. +By swapping between the minimal and complex JBFL configs, you can see +how formatting behavior changes, making the tool flexible for different workflows. -** Using These Examples +## Using These Examples To format an example file with the minimal configuration: -#+BEGIN_SRC bash +```bash jbeam-edit -cminimal stack exec jbeam-edit -- examples/jbeam/fender.jbeam -#+END_SRC +``` To try the complex configuration, generate it first and run: -#+BEGIN_SRC bash +```bash jbeam-edit -ccomplex stack exec jbeam-edit -- examples/jbeam/suspension.jbeam -#+END_SRC +``` Feel free to modify these examples or create your own to better suit your projects. These examples provide a practical way to understand and customize how jbeam-edit handles your JBeam files. -For complete documentation and usage, please refer to the root [[file:README.org][README.org]]. +For complete documentation and usage, please refer to the root +[README.md](../README.md). -There is also [[file:JBFL_DOCS.org][JBFL_DOCS.org]] for detailed information on the JBFL formatting language. +See also [JBFL_DOCS.md](../JBFL_DOCS.md) for detailed information on the JBFL formatting language. diff --git a/jbeam-edit.cabal b/jbeam-edit.cabal index 16415bd2..08d54b45 100644 --- a/jbeam-edit.cabal +++ b/jbeam-edit.cabal @@ -16,7 +16,8 @@ license: BSD-3-Clause license-file: LICENSE build-type: Simple extra-source-files: - README.org + README.md + JBFL_DOCS.md data-files: examples/jbfl/complex.jbfl examples/jbfl/minimal.jbfl diff --git a/package.yaml b/package.yaml index 398425f6..53c65f73 100644 --- a/package.yaml +++ b/package.yaml @@ -8,7 +8,8 @@ copyright: 2025 webdevred data-files: examples/jbfl/*.jbfl extra-source-files: - - README.org + - README.md + - JBFL_DOCS.md # Metadata used when publishing your package # synopsis: Short description of your package