Merge pull request #76 from shoriwe/new-features

Documentation and project rename

cmd/plasma/execute-files.go

@@ -1,8 +1,8 @@
 package main
 
 import (
-	"github.com/shoriwe/gplasma/pkg/compiler"
-	"github.com/shoriwe/gplasma/pkg/vm"
+	"github.com/shoriwe/plasma/pkg/compiler"
+	"github.com/shoriwe/plasma/pkg/vm"
 	"os"
 )
 

cmd/plasma/repl.go

@@ -4,8 +4,8 @@ import (
 	"bufio"
 	"fmt"
 	"github.com/fatih/color"
-	"github.com/shoriwe/gplasma/pkg/compiler"
-	"github.com/shoriwe/gplasma/pkg/vm"
+	"github.com/shoriwe/plasma/pkg/compiler"
+	"github.com/shoriwe/plasma/pkg/vm"
 	"os"
 	"os/signal"
 	"strings"

docs/embedding/embedding.md

@@ -0,0 +1,40 @@
+# Embedding
+
+Embedding the language is simple:
+
+```go
+package main
+
+import (
+	"github.com/shoriwe/gplasma/pkg/vm"
+	"os"
+)
+
+const myScript = `
+args = get_args()
+if args.__len__() > 1
+    println(args.__string__())
+else
+    println("No")
+end
+`
+
+func main() {
+	plasma := vm.NewVM(os.Stdin, os.Stdout, os.Stderr)
+	plasma.Load("get_args", func(plasma *vm.Plasma) *vm.Value {
+		return plasma.NewBuiltInFunction(plasma.Symbols(),
+			func(argument ...*vm.Value) (*vm.Value, error) {
+				tupleValues := make([]*vm.Value, 0, len(os.Args))
+				for _, cmdArg := range os.Args {
+					tupleValues = append(tupleValues, plasma.NewString([]byte(cmdArg)))
+				}
+				return plasma.NewTuple(tupleValues), nil
+			})
+	})
+	_, errorChannel, _ := plasma.ExecuteString(myScript)
+	err := <-errorChannel
+	if err != nil {
+		panic(err)
+	}
+}
+```

docs/syntax/basics.md

@@ -0,0 +1,196 @@
+# Basics
+
+## Assignments
+
+You can assign values to:
+
+- Identifiers:
+
+```ruby
+my_variable = "Hello"
+```
+
+- Selectors:
+
+```ruby
+my_variable.my_property = "Hello"
+```
+
+- Indexes:
+
+```ruby
+my_array[2] = "Hello"
+
+my_hash["Antonio"] = "Hello"
+```
+
+## Deleting symbols
+
+Use the `delete` statement to delete symbols, selectors and indexes:
+
+```ruby
+delete my_variable              # Remove the symbol `my_variable`
+delete my_variable.my_property  # Remove `my_property` from `my_variable` object
+delete my_hash['Work']          # Remove the Key `Work` from `my_hash`
+```
+
+## Unary operators
+
+Not: `not`, `!`
+Negate bits: `~`
+
+## Binary operators
+
+- Boolean And: `and`, `&&`
+- Boolean Or: `or`, `||`
+- Boolean Xor: `xor`
+- In: `in`
+- Is: `is`
+- Implements: `implements`
+- Equals: `==`
+- Not Equals: `!=`
+- Greater than: `>`
+- Greater or equal than: `>=`
+- Less than: `<`
+- Less or equal than: `<=`
+- Bitwise or: `|`
+- Bitwise and: `&`
+- Bitwise xor: `^`
+- Bitwise left: `<<`
+- Bitwise right: `>>`
+- Add: `+`
+- Sub: `-`
+- Div: `/`
+- Floor division: `//`
+- Mul: `*`
+- Mod: `%`
+- Pow: `**`
+
+## Array expressions
+
+Arrays can be defined using `[` and `]`, separating its internal elements with commas:
+
+```ruby
+my_array = [0, 1, 2, 3, "A string", [0, 1, 2]]
+```
+
+Arrays have specific behavior methods:
+
+- `append(value)`: appends a value to the array
+- `clear()`: clears the contents of the array
+- `index(value)`: returns the index of a value in the array, `-1` if not found
+- `pop()`: remove and returns the last element of the array
+- `insert(index, value)`: inserts at index a new value
+- `remove(index)`: remove element at index
+
+## Tuple expressions
+
+Tuples can be defined using `(` and `)`, separating its internal elements with commas:
+
+```ruby
+my_tuple = (0, 1, 2, 3, "A string", [0, 1, 2])
+```
+
+Notice that tuples are immutable, meaning you can not modify them but the elements inside them can.
+
+## Hash expressions
+
+Hash expressions, also known as map can be defined with `{` and `}`:
+
+```ruby
+my_hash = {
+    "Antonio":  "Developer",
+    "Victor":   "Administrator"
+}
+```
+
+## String and bytes expressions
+
+Strings can be defined of 3 ways:
+
+```ruby
+single_quote = 'My string'
+double_quote = "My string"
+back_quote   = `My string`
+```
+
+Bytes work the same as String but prepending a letter `b` before the first quote:
+
+```ruby
+single_quote = b'My bytes'
+double_quote = b"My bytes"
+back_quote   = b`My bytes`
+```
+
+Special methods for both:
+
+- `join(tuple|array)`: returns a string with the content of the container but separating them with the contents of the
+  original string
+- `split(sep)`: returns a tuple with the string separated using the pattern of `sep`
+- `upper()`: returns a new string but uppercase
+- `lower()`: returns a new string but lowercase
+- `count(pattern)`: counts how many times a pattern is inside the string
+- `index(pattern)`: returns the index of the first pattern in the string, `-1` if not found
+
+## Numbers
+
+Plasma has integers and float that can be operated between both:
+
+```ruby
+my_int = 10
+my_float = 2.0
+my_result = my_int ** my_float
+```
+
+Special methods of both types are:
+
+- `to_big()`: returns a bytes string with the 64 bit big endian contents of the number
+- `from_big(bytes)`: reconstruct the number from the big endian bytes of the string
+- `to_little()`: returns a bytes string with the 64 bit little endian contents of the number
+- `from_little(bytes)`: reconstruct the number from the little endian bytes of the string
+
+## Booleans
+
+There are to booleans `true` and `false`
+
+```ruby
+# Alert of blocking code
+while true
+    pass
+end
+
+until false
+    pass
+end
+```
+
+## None
+
+```ruby
+a = none
+```
+
+## Functions calls
+
+```ruby
+my_func()
+(lambda x, y: x + y)(1, 2)
+```
+
+## One line expressions
+
+- Conditions `if` and `unless`:
+
+```ruby
+a = 2
+b = 5 if a == 2 else 10
+b = 5 unless a == 2 else 10
+```
+
+- Generators:
+
+```ruby
+for pow in (number ** 2 for number in range(1, 10))
+    println(pow)
+end
+```

docs/syntax/built-in-symbols.md

@@ -0,0 +1,23 @@
+# Built-in types
+
+These classes are previously defined in the language:
+
+- `Class`
+- `Value`
+- `Function`
+- `String`
+- `Bytes`
+- `Bool`
+- `NoneType`
+- `Int`
+- `Float`
+- `Tuple`
+- `Array`
+- `Hash`
+
+# Built-in functions
+
+- `input(string)`
+- `println(args...)`
+- `print(args...)`
+- `range(start, end [, step])`

docs/syntax/classes.md

@@ -0,0 +1,37 @@
+## Classes and interfaces
+
+Interfaces work the same way as classes, but they only permit function and generator definitions
+
+ALWAYS create `__init__` method inside your classes and interfaces:
+
+```ruby
+interface Vehicle
+    def __init__()
+        pass
+    end
+
+    def drive()
+       println("driving")
+    end
+end
+
+class Car(Vehicle)
+    def __init__(name)
+        self.name name
+    end
+end
+```
+
+# Modules
+
+Modules are a special way to organize symbols
+
+```ruby
+module MyModule
+    def calc(a)
+        println(a**2)
+    end
+end
+
+MyModule.calc(10)
+```

docs/syntax/control-flow.md

@@ -0,0 +1,58 @@
+# Control flow
+
+- Nop expression: `pass` used to do nothing
+- `if` and `unless`:
+
+If and unless blocks are the basic condition control flow of the language.
+
+Unless works the same way as `if` but it previously negates the expression.
+
+```ruby
+if my_condition
+    pass
+elif other_condition
+    pass
+else
+    pass
+end
+
+unless my_condition
+    pass
+elif other_condition
+    pass
+else
+    pass
+end
+```
+
+- `switch` statements
+
+```ruby
+a = 1
+switch a
+case 1
+    pass
+case 2
+    pass
+case 3
+    pass
+default
+    pass
+end
+```
+
+- `BEGIN` and `END` blocks
+
+This two blocks are executed before the string `BEGIN` and at the end of the script `END`:
+
+```ruby
+BEGIN
+    println("first")
+end
+
+println("middle")
+
+END
+    println("end")
+end
+```