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<StringView, Bofa> output = new .();
+		List<int64> 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