From 8d042baf8522a772399d0b1f6eed63468c74f3a8 Mon Sep 17 00:00:00 2001 From: Booklordofthedings Date: Mon, 26 Aug 2024 13:28:04 +0200 Subject: [PATCH] Update README.md --- README.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3979052..f2b4247 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,140 @@ -# Bofa -Books object format a +# Bofa - Books Object Format A +Bofa is an object notation for general purpose use in serialization and deserialization. +The primary focus is on being human readable, while also being extremely easy to parse +This repository implements a Bofa parser in the Beef programming language. + +``` +# A floating point number +n number 125.435 +l line this is a normal line +a Array + t text you can + - put more text in here + t text2 and even + - more in here +``` + +## Index +- How to install +- The Bofa notation +- Parser notes +- Bofa parser API usage +- Potential improvements + +## How to install +- Download the repository, either with git, the download zip functionality or the release tab +- Create or open your existing Beef project +- Right click on the workspace panel +- Select "Add Existing Project" +- Navigate to the BeefProj.toml file inside the Bofa folder +- Right click on the project you want to use Bofa with +- Click "Properties" -> "Dependencies" +- Check the box that says Bofa +- Add the Bofa namespace to the files you want to use Bofa with +- Use Bofa + +## The Bofa notation +The notation itself is pretty simple. +Every line contains one Bofa "Entry", but empty lines and comments are also allowed. +A normal Bofa entry has 3 Parts: `{Type} {Name} {Value}` + +The possible values of `{Type}` are: +- l - Line - A string (utf8) without a newline character +- t - Text - A string (utf8) that may contain newline characters +- b - Boolean - A boolean value of either "true" or "false" +- i - Integer - A 32bit signed integer +- ui - UnsignedInteger - A 32bit unsigned integer +- bi - BigInteger - A 64bit signed integer +- bui - BigUnsignedInteger - A 64bit unsigned integer +- n - Number - A 32bit floating point number +- bn - BigNumber - A 64bit floating point number +- c - Custom - Any custom type in a string (utf8) representation +- o - Object - A Key/Value container for other Bofa entries +- a - Array - A container for other Bofa entries, where entries may have identical names + +`{Name}` is simple just a string that does not contain a space or tab character +`{Value}` is a string that represents the choosen datatype and can be parsed into the datatype + +Empty lines are full ignored and comments start with a # as the first non whitespace character in the line. + +An entry of type custom needs additional information to work. +Instead of `{Type} {Name} {Value}` a custom entry uses `{Type} {Typename} {Name} {Value}` instead. +Similarly arrays and objects dont actually need a entry for `{Value}` and just use `{Type} {Name}`. +In order to allow multiline text without too many issues the `-` character is used to indicate that the content of this line should be appended +to the last line if it was of type text. + +Membership of containers like arrays or objects is indicated via a depth value. +In order to indicate depth the start of the line may contain any number of tabs or spaces, the total amount of which indicates the depth of the entry. +The exact object it is a member of is always the last defined object at a given depth. +``` +a Array1 + a Array2 + a Array3 + l Line this line is a member of Array3 which is itself contained inside of Array1 +``` +Objects have a key uniqueness rules, while Arrays dont have this (Entries of an array still need to have a proper name though, even if its only "-"). + +## Parser notes +Bofa should always be parsed loosely and to the best of the parsers ability, but never fail completely. +Instead it can indicate on which line an error occured and leave the user to figure out wether to stop or to continue. +This also enables a parsing pattern where Bofa data can be structured so any parser can read a document from a newer or different parser: +``` +# The following line has a type that was added by a imaginary parser using the Bofa 2.0 Standard +rgb color 255:0:255 +c rgb color 255:0:255 +``` +A parser that supports 2.0 should just parse the first entry and ignore the second, as it contains a dublicate name. +A parser still on an old version will ignore the first one, since it doesnt know a type named rgb but instead parse the second one correctly + +While the insertion at a depth needs to be done in the order of the document, the parsing and validation of the individual line does not. +As such you can theoretically multithread the parsing of each individual line to get some potential speed. + +Different parsers may add different types for their usecases, but single and 2 character typenames should stay reserved for official notation types. + +The entire standard is case sensitive. + +## Bofa parser api usage +This shows of an example of how to use the parser api +```cs +namespace Example; + +using System; +using Bofa; + +class ExampleClass +{ + public static void Main() + { + String bofaString = """ + # A floating point number + n number 125.435 + l line this is a normal line + a Array + t text you can + - put more text in here + t text2 and even + - more in here + """; + + Dictionary output = new .(); + List errors = new .(); + BofaParser.Parse(bofaString, output, errors); + + DeleteDictionaryAndValues!(output); + delete errors; + } +} +``` + +## Potential improvements +- There is still alot of speed left on the table + - Reduce the amount of allocations + - Multithread initial parsing +- New useful types + - Color + - Version + - Encrypted raw data +- More automatic serialization/deserialization in Corlib + - Hashes + - Pointers + - Tuples \ No newline at end of file