impr: first documentation

docs/language/Attributes.md

@@ -0,0 +1,57 @@
+# Attributes
+
+Certain top level declarations can have attributes declared immediately before that will be collected by the declaration
+
+## Members (Class, Method, Field)
+
+### Annotation
+```
+.annotation name {
+    key: element
+}
+```
+
+#### Element
+An element can be one of the following, with following interpretation:
+- identifer: a type (`Ljava/lang/String;` / `I`)
+- number: a numeric type (`10.3f`)
+- string: a string value
+- character: a character value
+- array: an array containing elements (`{ element, element }`)
+- declaration: there are two possible declaration types allowed
+    - annotation: a sub annotation
+    - enum: a enum value (`.enum class name`)
+
+### Signature
+```
+.signature "generic signature"
+```
+
+## Class
+
+### Super
+```
+.super supertype
+```
+Specifies the supertype of the class, the `supertype` must be given in internal name format (`java/lang/Object`).
+### Implements
+```
+.implements interfacetype
+```
+Appends a interface to the implemented interfaces, the `interfacetype` must be given in 
+internal name format (`java/util/function/Consumer`). 
+### Inner class
+```
+.inner modifiers {
+  name: innerName, // optional
+  inner: innerClass,
+  outer: outerClass // optional
+}
+```
+Appends a inner class to the inner classes, `innerClass` and `outerClass` must be given in internal name format
+and name must be an identifier. When `outer` isn't given `name` must also be not given.
+### Source File
+```
+.sourcefile "SourceFile"
+```
+Specifies the source file of the class.

docs/language/Basics.md

@@ -0,0 +1,59 @@
+# Basics
+
+In Jasm, attributes and classes, methods and fields are represented via [declarations]()
+
+The most simple declarations are:
+
+## Class
+<pre>
+.class modifiers name { [members] }
+</pre>
+
+Members is a [list of declarations](Syntax.md#declaration-list)
+
+Valid members for a class declaration are:
+- [method](#method)
+- [field](#field)
+
+### Modifiers
+Valid modifiers for the `class` type are:   
+`public private protected static final native
+abstract interface synthetic strict annotation
+enum super module`
+
+## Method
+<pre>
+.method modifiers name descriptor {
+    parameters: { parameter... }, // optional
+    exceptions: { <a href="#exception">exception</a>... }, // optional
+    code: { // optional
+        <a href="Instructions.md#instruction">instruction</a>...
+    }
+}
+</pre>
+
+### Modifiers
+Valid modifiers for the `method` type are:
+`public private protected static final native
+abstract interface synthetic strict annotation
+enum synchronized bridge varargs`
+
+### Exception
+A exception is a try catch handler descriptor object, it is structured like this:
+```
+{ start, end, handler, exception }
+```
+start, end and handler are identifiers of the label they represent, so `A`, `Q` or `AB`.
+the exception is either the internal of the class, or to have an all catch block simply use `*`
+
+## Field
+<pre>
+.field <a>modifiers</a> name descriptor
+</pre>
+
+### Modifiers
+Valid modifiers for the `field` type are:
+`public private protected static final native
+abstract interface synthetic strict annotation
+enum volatile transient`
+

docs/language/Instructions.md

@@ -0,0 +1,20 @@
+# Instructions
+Code objects contain instruction. These instructions depend on the platform, there are currently 2 instruction sets
+avaiable:
+- [jvm](instructions/Jvm)
+- [dalvik](instructions/Dalvik)
+
+## Generic
+There are some things generic across both instructions
+
+### Labels
+```
+label:
+```
+Labels are used for jumps, location information and flow blocks. A label must always be placed between two instructions:
+```
+lint 3
+label:
+jmp label
+```
+Labels can be referenced before they were defined.

docs/language/Syntax.md

@@ -0,0 +1,107 @@
+# Syntax Reference
+
+## Tokens
+
+The language grammar is made up off five main tokens: 
+### identifier 
+    - Everything that is not any other token
+    - Accepts all of unicode directly, except:
+        - Operator characters (`{ } , :`)
+        - Whitespaces (`<space> <newline> <cariage return>`)
+        - String or character triggers (`' "`)
+    - Allows for escape sequences (\uXXXX or any other escape sequence),
+      which will be turned into the respective character before being evaluated
+        - Example `Hello\u0020World!`, would become `Hello World!`
+        - Example `Hello\n\"World\"!`, would become `Hello<newline>"World"!`
+### number
+    - supports integers, longs, floats and doubles using the respective suffix
+        - l/L for longs
+        - d/D for doubles
+        - f/F for floats
+        - nothing for integers
+        - default interpretation is:
+            - float (when decimal point is present)
+            - integer (when no other condition is met)
+    - supports hexadecimal (0xX), scientific floats (X.XeY), hexadecimal floats (0xX.XpY)
+    - `nan`, `-nan`, `infinity` and `-infinity` count as numbers
+### string
+    - anything within `""` is a string
+    - supports all java string escape sequences
+### character
+    - anything within `''` is a character
+    - supports all java character escape sequences
+### operator
+    - any of: `{ } , :`
+
+## Expressions
+
+The language has three main categories of `expression`s:
+- The [Declaration](#Declaration)
+- The [Object](#Objects)
+- The [Value](#Value)
+
+### Declaration
+Declarations are the core foundation of the language, as they declare components of the class file.    
+Declarations are structured like the following:
+```
+.identifier <arguments>
+```
+Where `arguments` can be any expression.    
+The end of the arguments is determined by multiple conditions:
+- another declaration is found
+- next value in object or array
+- closing `}` for object or array
+- end of file
+
+### Objects
+Objects are used as arguments for declarations, instructions or other values as they can be interpreted as values.    
+The Object has two structures, first the simple [key -> value] structure:
+```
+{
+    identifer: expression,
+    identifer: expression,
+    ...
+    identifer: expression
+}
+```
+And the second is the array structure:
+```
+{ expression, expression ... expression }
+```
+
+#### Code
+Under objects is a type of object which contain the instructions of a code object,
+which are structured like this:
+```
+{ 
+label:
+    instruction
+    instruction
+label:
+...
+}
+```
+Where labels and instructions can be in arbitrary order
+
+#### Declaration list
+Under objects is a type of object which contains a list of declarations, 
+which are structured like this:
+```
+{
+    .declaration <arguments>
+    .declaration <arguments>
+    ...
+    .declaration <arguments>
+}
+```
+
+
+### Value
+Values can be any of the four tokens (without operators) where they represent the following:
+- identifier: 
+    - a class/field/method path
+    - a class/method type
+    - a field/method descriptor
+- number: a number
+- string: a string
+- character: a character 

docs/language/instructions/Jvm.md

@@ -0,0 +1,48 @@
+# JVM Instruction set
+The jvm instruction set for jasm 
+
+## Generic
+Generic objects reused accords multiple instructions:
+
+### Constant
+A constant is a object present in the constant pool and can be represented by the following expressions:
+- identifier:
+  - class type (`Lsome/package/Class;` `[Lsome/package/Array` `[I` `I`)
+  - a method type (`(Lsome/package/Argument;IIJJZZ)Lsome/package/Return;`)
+- number:
+    represents a numeric constant, depending on context only certain number kinds are allowed
+- string:
+    a string constant
+- array:
+    - handle:
+        The jvm takes the [handle](#handle-1) and resolves it to a MethodHandle
+    - constant dynamic: The jvm evaluates the constant dynamic using the handle to resolve a method handle and then invokes it
+
+### Handle
+Format:
+```
+{ kind, owner.member, descriptor }
+```      
+A handle is a way to describe a way for the jvm to obtain a `java/lang/invoke/MethodHandle` from the instructions given.
+The way the jvm obtains this is determined by the kind:
+- invokevirtual (equivalent to: `invokevirtual owner.member descriptor`)
+- invokestatic (equivalent to: `invokestatic owner.member descriptor`)
+- invokespecial (equivalent to: `invokespecial owner.member descriptor`)
+- getfield (equivalent to: `getfield owner.member descriptor`)
+- putfield (equivalent to: `putfield owner.member descriptor`)
+- getstatic (equivalent to: `getstatic owner.member descriptor`)
+- putstatic (equivalent to: `putstatic owner.member descriptor`)
+- invokeinterface (equivalent to: `invokeinterface owner.member descriptor`)
+- newinvokespecial (equivalent to: `new owner; dup; invokespecial owner.<init> descriptor`
+
+### Constant dynamic
+Format:
+```
+{ name, descriptor { kind, owner.member, descriptor } { arguments } }
+```
+Constant dynamic is the constant equivalent of the [invokedynamic](#invokedynamic) instruction, as it evaluates the same
+but counts as a constant, thus can be used in any other place a constant of its type is permitted.
+
+It behaves the same as a invokedynamic instruction, but evaluates the value directly in place, instead of on the stack
+
+## Instructions