https://github.com/connected-web/mkvconf
Custom configuration file format that parses to JSON
https://github.com/connected-web/mkvconf
Last synced: 4 months ago
JSON representation
Custom configuration file format that parses to JSON
- Host: GitHub
- URL: https://github.com/connected-web/mkvconf
- Owner: connected-web
- Created: 2021-11-20T21:19:40.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-01-21T14:37:32.000Z (over 4 years ago)
- Last Synced: 2025-10-10T22:12:55.006Z (9 months ago)
- Language: JavaScript
- Size: 92.8 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# mkvconf
A custom configuration file format that maps to JSON; a more forgiving and less boiler plate way of writing data for systems.
This implementation of `mkvconf` is written in javascript, and uses `nodejs` and `npm`.
The format allows for groups of objects to be quickly copy and pasted, with a forgiving minimalist format for building lists of objects with complex properties quickly.
```
// mkvconf.file
[Star]
name Sol
equatorial.radius.min 695,700 km
equatorial.radius.max 696,342 km
equatorial.circumference 4.379×106 km
flattening 9×10−6
surface.area 6.09×1012 km²
volume 1.41×1018 km³
mass 1.9885×1030 kg
composition.Hydrogen 73.46%
composition.Helium 24.85%
composition.Oxygen 0.77%
composition.Carbon 0.29%
composition.Iron 0.16%
composition.Neon 0.12%
composition.Nitrogen 0.09%
composition.Silicon 0.07%
composition.Magnesium 0.05%
composition.Sulphur 0.04%
[Planet]
name Earth
distance.to.sun 149.6 million km
planet.radius 6,371 km
surface.area 510.1 million km²
land.area 148.9 million km²
mass 5.972 × 10^24 kg
[Planet]
name Mercury
distance.to.sun 57.91 million km
orbital.period 88 days
planet.radius 2,439.7 km
surface.area 74.8 million km²
length.of.day 58d 15h 30m
mass 3.285 × 10^23 kg
density 5.43 g/cm³
```
## Command line tool
If this file format is interesting to you; you may want to read about the [mkvconf command line tool](./CLI.md).
## Development Usage
Install the local package:
```
npm install mkvconf
```
### Deserialising data (parse)
To load and parse data:
```js
const mkvconf = require('mkvconf')
const fs = require('fs')
const body = fs.readFileSync('item.file', 'utf8')
const data = mkconf.parse(body)
console.log(data)
```
### Serializing data (format)
To produce a `mkvconf` file from data:
```js
const mkvconf = require('mkvconf')
const data = {
Fruits: [{
name: 'Apple',
cost: '£0.34/kg'
}, {
name: 'Orange'
cost: '£0.42/kg'
}, {
name: 'Banana',
cost: '$0.65/kg'
}]
}
const text = mkvconf.format(data)
console.log(text)
```
## Item example
```file
// item.file
[Item]
id item-1
meta.name Item One
position.x 124
position.y 523
[Item]
id item-2
meta.name Item Two
position.x 224
position.y 323
```
Parses to:
```json
{
"Item": [{
"id": "item-1",
"meta": {
"name": "Item One"
},
"position": {
"x": 124,
"y": 523
}
}, {
"id": "item-2",
"meta": {
"name": "Item Two"
},
"position": {
"x": 224,
"y": 323
}
}],
"comments": [
"// item.file"
]
}
```
## Fruit example
```
// fruit.file
[Fruit]
name Banana
skin yellow
flesh beige
icon assets/banana.png
[Fruit]
name Apple
skin green
flesh white
icon assets/apple.png
```
Parses to:
```json
{
"Fruit": [{
"name": "Banana",
"skin": "yellow",
"flesh": "beige",
"icon": "assets/banana.png"
}, {
"name": "Apple",
"skin": "green",
"flesh": "white",
"icon": "assets/apple.png"
}],
"comments": [
"// fruit.file"
]
}
```
## Parsing rules
The parsing rules are designed to be very simple.
### Line breaks
Lines are parsed using the `\n` line break.
### Tabs and other spacing
All lines are trimmed before matching; so extra spaces at the start or ends are ignored.
### Comments
Any line beginning with `//` is considered a comment, and is collected into an array property `comments` in the result.
### Object Group
Any line beginning with `[` and ending with `]` starts a new object group, with the group name based on the internals. Valid characters for the group name are Alpha-numeric with spaces and dashes matching the regex: `/[([A-z\d- ]+)]/`; the object group name will be trimmed of any additional spacing.
### Key Value Pairs
Once the first object group has been created; any line that matches the regex `/^([A-z][A-z\d.]*)\s+(.*)/` will be considered a key value pair, and added to the last object group. Values are trimmed and parsed. Multi-line values are not supported. Additional spaces between the `key` and the `value` will be ignored.
To ensure numbers are parsed as numbers, and booleans as booleans, values are passed through `JSON.parse()` - so you could get fancy and embed arrays, or more complex objects, provided they fit on one line.
### Blank lines
Empty lines are ignored; i.e. anything line that when trimmed has a length of `0`.
### Unmatched lines
Lines that do not match a supported regex will be stored in order with the comments. Maybe you can abuse this to store extra data, but your mileage may vary.
## Release notes
### v1.2.0
- Add `fast-glob` support as a dependency to fully resolve glob patterns
### v1.1.1
- Document support for glob matchers e.g. `mkvconf lint **/*.file --fix`
- Add tests around multiple file support to CLI
- Sort list of files to ensure consistency of execution
### v1.1.0
- Added json command to CLI tool
### v1.0.1
- Initial release
- Documentation for file format
- Added javacsript `.parse` API to read file format to into `js` object/lists
- Added javascript `.format` API to format JSON as `mkvconf`
- Added command line support using `npx mkvconf` and `npm install --global mkvconf`
- Added lint commmand to CLI tool
- Added lint --fix flag to CLI tool
- Added lint --suffix flag to CLI tool
## Wishlist
- Consider specifying output path for converted files
- Consider JSON output to `stdout` for single file conversions