Create USAGE.md

USAGE.md

@@ -0,0 +1,168 @@
+* [Basic usage](#basic-usage)
+* [Serializing class instances](#serializing-class-instances)
+* [Advanced usage](#advanced-usage)
+* [Reference](#reference)
+
+# Basic usage
+
+```lua
+local bitser = require 'bitser'
+
+-- some_thing can be almost any lua value
+local binary_data = bitser.dumps(some_thing)
+
+-- binary_data is a string containing some serialized value
+local copy_of_some_thing = bitser.loads(binary_data)
+```
+
+Bitser can't dump values of type `function`, `userdata` or `thread`, or anything that
+contains one of those. If you need to, look into [`bitser.register`](#register).
+
+# Serializing class instances
+
+(I need to finish this section.)
+
+## Supported class libraries
+
+* MiddleClass
+* SECL
+* hump.class
+* Slither
+* Moonscript classes
+
+# Advanced usage
+
+(I need to finish this section.)
+
+# Reference
+
+## dumps
+
+```lua
+local string = bitser.dumps(value)
+```
+
+Basic serialization of `value` into a Lua string.
+
+See also: [`bitser.loads`](#loads).
+
+## dumpLoveFile
+
+```lua
+bitser.dumpLoveFile(file_name, value)
+```
+
+Serializes `value` and writes the result to `file_name` more efficiently than serializing to a string and writing
+that string to a file. Only useful if you're running [LÖVE](https://love2d.org/).
+
+See also: [`bitser.loadLoveFile`](#loadlovefile).
+
+## loads
+
+```lua
+local value = bitser.loads(string)
+```
+
+Deserializes `value` from `string`.
+
+See also: [`bitser.dumps`](#dumps).
+
+## loadData
+
+```lua
+local value = bitser.loadData(light_userdata, size)
+```
+
+Deserializes `value` from raw data. You probably won't need to use this function ever.
+
+## loadLoveFile
+
+```lua
+local value = bitser.loadLoveFile(file_name)
+```
+
+Reads from `file_name` and deserializes `value` more efficiently than reading the file and then deserializing that string.
+Only useful if you're running [LÖVE](https://love2d.org/).
+
+See also: [`bitser.dumpLoveFile`](#dumplovefile).
+
+## register
+
+```lua
+bitser.register(name, resource)
+```
+
+Registers the value `resource` with the name `name`, which has to be a unique string. Registering static resources like images,
+functions, classes and huge strings, makes sure bitser doesn't attempt to serialize them, but only stores a named
+reference to them.
+
+See also: [`bitser.unregister`](#unregister).
+
+## registerClass
+
+```lua
+bitser.registerClass(class)
+bitser.registerClass(name, class)
+bitser.registerClass(name, class, classkey, deserializer)
+```
+
+Registers the class `class`, so that bitser can correctly serialize and deserialize instances of `class`.
+
+Note that if you want to serialize the class _itself_, you'll need to [register the class as a resource](#register).
+
+Most of the time the first variant is enough, but some class libraries don't store the
+class name on the class object itself, in which case you'll need to use the second variant.
+
+Class names also have to be unique, so if you use multiple classes with the same name, you'll need to use the second
+variant as well to give them different names.
+
+The arguments `classkey` and `deserializer` exist so you can hook in unsupported class libraries without needing
+to patch bitser. [See the list of supported class libraries](#supported-class-libraries)
+
+If not nil, the argument `classkey` should be a string such that
+`rawget(obj, classkey) == class` for any `obj` whose type is `class`. This is done so that key is skipped for serialization.
+
+If not nil, the argument `deserializer` should be a function such that `deserializer(obj, class)` returns a valid
+instance of `class` with the properties of `obj`. `deserializer` is allowed to mutate `obj`.
+
+See also: [`bitser.unregisterClass`](#unregisterclass).
+
+## unregister
+
+```lua
+bitser.unregister(name)
+```
+
+Deregisters the previously registered value with the name `name`.
+
+See also: [`bitser.register`](#register).
+
+## unregisterClass
+
+```lua
+bitser.unregisterClass(name)
+```
+
+Deregisters the previously registered class with the name `name`. Note that this works by name and not value,
+which is useful in a context where you don't have a reference to the class you want to unregister.
+
+See also: [`bitser.registerClass`](#registerclass).
+
+## reserveBuffer
+
+```lua
+bitser.reserveBuffer(num_bytes)
+```
+
+Makes sure the buffer used for reading and writing serialized data is at least `num_bytes` large.
+You probably don't need to ever use this function.
+
+## clearBuffer
+
+```lua
+bitser.clearBuffer()
+```
+
+Frees up the buffer used for reading and writing serialized data for garbage collection.
+You'll rarely need to use this function, except if you needed a huge buffer before and now only need a small buffer
+(or are done (de)serializing altogether). Most of the time, using this function will decrease performance needlessly.