Add some doc

Author: Karang

doc/compiler.md

@@ -0,0 +1,205 @@
+# Using the ProtoDef compiler
+
+The ProtoDef compiler can convert your protocol JSON into javascript code that can read and write buffers directly instead of using the ProtoDef interpreter. Depending on the types, the expected speedups are in the range of x10 - x100.
+
+## Simple usage
+
+Let's take a simple ProtoDef definition and convert it to use the ProtoDef compiler:
+
+ProtoDef:
+```javascript
+const ProtoDef = require('protodef').ProtoDef
+
+// Create a ProtoDef instance
+const proto = new ProtoDef()
+proto.addTypes(require('./protocol.json'))
+
+// Encode and decode a message
+const buffer = proto.createPacketBuffer('mainType', result)
+const result = proto.parsePacketBuffer('mainType', buffer)
+```
+
+ProtoDef Compiler:
+```javascript
+const { ProtoDefCompiler } = require('protodef').Compiler
+
+// Create a ProtoDefCompiler instance
+const compiler = new ProtoDefCompiler()
+compiler.addTypesToCompile(require('./protocol.json'))
+
+// Compile a ProtoDef instance
+const compiledProto = await compiler.compileProtoDef()
+
+// Use it as if it were a normal ProtoDef
+const buffer = compiledProto.createPacketBuffer('mainType', result)
+const result = compiledProto.parsePacketBuffer('mainType', buffer)
+```
+
+## New datatypes
+
+Like the ProtoDef interpreter, the ProtoDef compiler can be extended with custom datatypes. To register a custom type, use the `addTypes(types)` method of the ProtoDef compiler. The `types` parameter is an object with the following structure:
+
+```javascript
+{
+  Read: {
+    'type1': ['native', /* implementation */],
+    'type2': ['context', /* implementation */],
+    'type3': ['parametrizable', /* implementation */],
+    /* ... */
+  },
+
+  Write: {
+    'type1': ['native', /* implementation */],
+    'type2': ['context', /* implementation */],
+    'type3': ['parametrizable', /* implementation */],
+    /* ... */
+  },
+
+  SizeOf: {
+    'type1': ['native', /* implementation */],
+    'type2': ['context', /* implementation */],
+    'type3': ['parametrizable', /* implementation */],
+    /* ... */
+  }
+}
+```
+
+The types can be divided into 3 categories:
+
+### Native Type
+
+A native type is a type read or written by a function that will be called in its original context. Use this when you need access to external definitions.
+
+Example:
+```javascript
+const UUID = require('uuid-1345')
+
+{
+  Read: {
+    'UUID': ['native', (buffer, offset) => {
+      return {
+        value: UUID.stringify(buffer.slice(offset, 16 + offset)), // A native type can access all captured definitions
+        size: 16
+      }
+    }]
+  },
+  Write: {
+    'UUID': ['native', (value, buffer, offset) => {
+      const buf = UUID.parse(value)
+      buf.copy(buffer, offset)
+      return offset + 16
+    }]
+  },
+  SizeOf: {
+    'UUID': ['native', 16] // For SizeOf, a native type can be a function or directly an integer
+  }
+}
+```
+
+### Context Type
+
+A context type is a type that will be called in the protocol's context. It can refer to registred native types using `native.{type}()` or context types (provided and generated) using `ctx.{type}()`, but cannot access its original context.
+
+Example:
+```javascript
+const originalContextDefinition = require('something')
+/* global ctx */
+{
+  Read: {
+    'compound': ['context', (buffer, offset) => {
+      // originalContextDefinition.someting() // BAD: originalContextDefinition cannot be accessed in a context type
+      const results = {
+        value: {},
+        size: 0
+      }
+      while (true) {
+        const typ = ctx.i8(buffer, offset) // Access to a native type (that was copied in the context)
+        if (typ.value === 0) {
+          results.size += typ.size
+          break
+        }
+
+        const readResults = ctx.nbt(buffer, offset) // Access to a type that was compiled and placed in the context
+        offset += readResults.size
+        results.size += readResults.size
+        results.value[readResults.value.name] = {
+          type: readResults.value.type,
+          value: readResults.value.value
+        }
+      }
+      return results
+    }]
+  },
+
+  Write: {
+    'compound': ['context', (value, buffer, offset) => {
+      for (const key in value) {
+        offset = ctx.nbt({
+          name: key,
+          type: value[key].type,
+          value: value[key].value
+        }, buffer, offset)
+      }
+      offset = ctx.i8(0, buffer, offset)
+      return offset
+    }]
+  },
+
+  SizeOf: {
+    'compound': ['context', (value) => {
+      let size = 1
+      for (const key in value) {
+        size += ctx.nbt({
+          name: key,
+          type: value[key].type,
+          value: value[key].value
+        })
+      }
+      return size
+    }]
+  }
+}
+```
+
+### Parametrized Type
+
+A parametrizable type is a function that will be generated at compile time using the provided maker function.
+
+Example:
+```javascript
+{
+  Read: {
+    'option': ['parametrizable', (compiler, type) => {
+      let code = 'const {value} = ctx.bool(buffer, offset)\n'
+      code += 'if (value) {\n'
+      code += '  const { value, size } = ' + compiler.callType(type) + '\n'
+      code += '  return { value, size: size + 1 }\n'
+      code += '}\n'
+      code += 'return { value: undefined, size: 1}'
+      return compiler.wrapCode(code)
+    }]
+  },
+
+  Write: {
+    'option': ['parametrizable', (compiler, type) => {
+      let code = 'if (value !== null) {\n'
+      code += '  offset = ctx.bool(1, buffer, offset)\n'
+      code += '  offset = ' + compiler.callType('value', type) + '\n'
+      code += '} else {\n'
+      code += '  offset = ctx.bool(0, buffer, offset)\n'
+      code += '}\n'
+      code += 'return offset'
+      return compiler.wrapCode(code)
+    }]
+  },
+
+  SizeOf: {
+    'option': ['parametrizable', (compiler, type) => {
+      let code = 'if (value !== null) {\n'
+      code += '  return 1 + ' + compiler.callType('value', type) + '\n'
+      code += '}'
+      code += 'return 0'
+      return compiler.wrapCode(code)
+    }]
+  }
+```

src/compiler.js

@@ -16,43 +16,6 @@ class ProtoDefCompiler {
     this.sizeOfCompiler = new SizeOfCompiler()
   }
 
-  /**
-   * A native type is a type read or written by a function that will be called in it's
-   * original context.
-   * @param {*} type
-   * @param {*} fn
-   */
-  addNativeType (type, fn) {
-    this.readCompiler.addNativeType(type, fn)
-    this.writeCompiler.addNativeType(type, fn)
-    this.sizeOfCompiler.addNativeType(type, fn)
-  }
-
-  /**
-   * A context type is a type that will be called in the protocol's context. It can refer to
-   * registred native types using native.{type}() or context type (provided and generated)
-   * using ctx.{type}(), but cannot access it's original context.
-   * @param {*} type
-   * @param {*} fn
-   */
-  addContextType (type, fn) {
-    this.readCompiler.addContextType(type, fn)
-    this.writeCompiler.addContextType(type, fn)
-    this.sizeOfCompiler.addContextType(type, fn)
-  }
-
-  /**
-   * A parametrizable type is a function that will be generated at compile time using the
-   * provided maker function
-   * @param {*} type
-   * @param {*} maker
-   */
-  addParametrizableType (type, maker) {
-    this.readCompiler.addParametrizableType(type, maker)
-    this.writeCompiler.addParametrizableType(type, maker)
-    this.sizeOfCompiler.addParametrizableType(type, maker)
-  }
-
   addTypes (types) {
     this.readCompiler.addTypes(types.Read)
     this.writeCompiler.addTypes(types.Write)
@@ -146,16 +109,35 @@ class Compiler {
     this.parameterizableTypes = {}
   }
 
+  /**
+   * A native type is a type read or written by a function that will be called in it's
+   * original context.
+   * @param {*} type
+   * @param {*} fn
+   */
   addNativeType (type, fn) {
     this.primitiveTypes[type] = `native.${type}`
     this.native[type] = fn
   }
 
+  /**
+   * A context type is a type that will be called in the protocol's context. It can refer to
+   * registred native types using native.{type}() or context type (provided and generated)
+   * using ctx.{type}(), but cannot access it's original context.
+   * @param {*} type
+   * @param {*} fn
+   */
   addContextType (type, fn) {
     this.primitiveTypes[type] = `ctx.${type}`
     this.context[type] = fn.toString()
   }
 
+  /**
+   * A parametrizable type is a function that will be generated at compile time using the
+   * provided maker function
+   * @param {*} type
+   * @param {*} maker
+   */
   addParametrizableType (type, maker) {
     this.parameterizableTypes[type] = maker
   }