spade 0.1.0.0 → 0.1.0.1

raw patch · 21 files changed

+1154/−6 lines, 21 files

Files

• docs/functions/concurrency.md +182/−0
• docs/functions/container.md +1/−0
• docs/functions/debugging.md +10/−0
• docs/functions/dictionary.md +17/−0
• docs/functions/error-handling.md +6/−0
• docs/functions/file.md +18/−0
• docs/functions/graphics.md +159/−0
• docs/functions/keyboard.md +26/−0
• docs/functions/list.md +115/−0
• docs/functions/math.md +42/−0
• docs/functions/misc.md +44/−0
• docs/functions/serializing.md +9/−0
• docs/functions/sound.md +44/−0
• docs/functions/string.md +9/−0
• docs/functions/time.md +5/−0
• docs/graphics-and-animation.md +76/−0
• docs/ide.md +23/−0
• docs/language-reference.md +290/−0
• docs/toc.md +58/−0
• spade.cabal +20/−1
• src/IDE/Help/Contents.hs +0/−5

@@ -0,0 +1,182 @@+### Concurrency Functions++#### startthread++Starts a thread that executes the passed callback. Immediately returns a special+result object, that can be used with #link: awaitresult#, to get the value returned+from the callback, after it has finished execution in the thread. This can also+be used with #link: killthread# to stop the execution of a thread.++Example:+```+proc thread1(threadname)+  for i = 1 to 10+    println(threadname)+    wait(1)+  endfor+endproc++proc thread2(threadname)+  for i = 1 to 10+    println(threadname)+    wait(1)+  endfor+endproc++let t1 = startthread(thread1, "thread 1")+let t2 = startthread(thread2, "thread 2")+await(t1)+await(t2)+getkey()++-- Outputs:++-- thread 1+-- thread 2+-- thread 2+-- thread 1+-- thread 2+-- thread 1+-- thread 1+-- thread 2+-- thread 2+-- thread 1+-- thread 1+-- thread 2+-- thread 2+-- thread 1+-- thread 2+-- thread 1+-- thread 1+-- thread 2+-- thread 1+-- thread 2++```++#### killthread++Kill a thread using the thread info object returned by the `startthread` function.++Example:++```+proc thread1(threadname)+loop+    println("loop")+    wait(1)+  endloop+endproc++let t1 = startthread(thread1, "thread 1")+wait(3) -- Wait 3 seconds+killthread(t1)+println("Thread killed")+getkey()++-- Outputs:++-- loop+-- loop+-- loop+-- Thread killed+```++#### awaitresult++Wait till the procedure in corresponding thread finish executing and return the result.++Example:++```+proc thread1(threadname)+wait(3)+return 100+endproc++let t1 = startthread(thread1, "thread 1")+println("Thread started, waiting for result...")+println(awaitresult(t1))+getkey()++-- Outputs+-- Thread started, waiting for result...+-- 100++```++#### await++Just wait till the procedure in corresponding thread finish executing. Does not expect the+thread callback to return a value.++```+proc thread1(threadname)+  wait(3)+endproc++let t1 = startthread(thread1, "thread 1")+println("Thread started, waiting to end...")+await(t1)+println("Thread finished")+getkey()++-- Outputs+-- Thread started, waiting to end...+-- Thread finished+```++#### newchannel++Create a new channel for communication with threads.++#### writechannel++Write a value to a channel++#### readchannel++Wait till a value is available on a channel, and return it when it is available.++#### newref++Get a new mutable reference.++#### readref++Get the current value of the mutable reference.++#### writeref++Write a new value to the mutable reference.++#### modifyref++Modify the current value of the mutable reference by a call back. The call back+gets the current value, and should return the modified value.++Example:++Increments a counter in a mutable reference in two threads.++```+proc thread1(ref)+  for i = 1 to 50000+    modifyref(ref, fn (x) (x + 1) endfn)+  endfor+endproc++proc thread2(ref)+  for i = 1 to 50000+    modifyref(ref, fn (x) (x + 1) endfn)+  endfor+endproc+let r = newref(0)+let t1 = startthread(thread1, r)+let t2 = startthread(thread2, r)+await(t1)+await(t2)+println(readref(r))+-- Prints 100000+getkey()+```

@@ -0,0 +1,1 @@+### List/Dictionary Functions

@@ -0,0 +1,10 @@+### Debugging Functions++#### debug++Use this function to break into the IDE debugger at the point where it is+called.++#### inspect++Prints the argument value for debugging.

@@ -0,0 +1,17 @@+### Dictionary Functions++#### haskey++Checks if a dictionary contains a given key.++Example:++```+let mydict = { name: "John", age: 33 }+inspect(haskey(mydict, "address"))+getkey()+```++#### Getting number of items in dictionary++Use #link: size#

@@ -0,0 +1,6 @@+### Error Handling Functions++#### try++Returns the first argument itself, if it is an non-error value. Or else+returns the second argument.

@@ -0,0 +1,18 @@+### File Functions++#### readfile++Reads the file at path provided as argument, and returns its contents+as bytes.++#### readtextfile++Reads the file at path provided as argument, and returns its contents+as a string.++#### writefile++Accept a file path as the first argument, and content as a second argument+and writes content to the file at path. Any existing content is truncated.++Content can be either bytes or text.

@@ -0,0 +1,159 @@+### Graphics Functions++##### graphics++Starts the graphics mode. The argument here is an optional+boolean. A true value indicates the graphics will use acceleration.++In accelerated graphics mode, screen is only updated on #link: drawscreen#++Example:++```+graphics(true)+```++#### graphicswindow++Starts the graphics windowed mode. The first two arguments decides the width+and height of the window. The third argument decides if the display is accelerated.++Example:++```+graphicswindow(400, 200, true)+```++#### drawscreen++Draws everything to the screen at once.++Example:++```+drawscreen()+```++#### point++Turns the pixel at given cordinates on, with the current drawing color.++use #link: setcolor# to set drawing color.++Example:++```+point(100, 100)+```++#### points++Turns the pixels at the given coordinates on, with current drawing color.++use #link: setcolor# to set drawing color.++Example:++```+points([[100, 100], [200, 200]])+```++#### line+++Draws a line from co-ordinates (100, 100) to (200, 200) using the current color+use #link: setcolor# to set drawing color.++Example:++```+line(100, 100, 200, 200)+```++#### lines++Draws a sequence of lines from a list of points. Each point is represented+by a list of two numbers, first one representing the x coordinate and the second+one representing the y-coordinate.++use #link: setcolor# to set drawing color.++Example:++```+lines([[100, 100], [200, 200]])+```++#### box++Draws a rectangle in current color, with top left corner at co-ordinates (100,+100) and having 20 pixels wide and 30 pixel tall.++use #link: setcolor# to set drawing color.++Example:++```+box(100, 100, 20, 30)+```++#### circle++Draws a rectangle in current color, with center at co-ordinates (100,+100) and having a radius of 20 pixels.++use #link: setcolor# to set drawing color.++Example:++```+circle(100, 100, 20)+```++#### setcolor++Sets the current drawing color using red, green and blue component values.++Example:++```+setcolor(100, 10, 200)+```++#### clearscreen++Fills the graphics screen with current draw color.++Example:++```+setcolor(0, 0, 0)+clearscreen() -- paints the entire screen black.+```++#### getwindowsize++Gets the dimensions of the graphics window.++```+graphics()+let windowsize = getwindowsize()+println(windowsize.width)+println(windowsize.height)+```++#### setlogicalsize++Sets the logical size of the display, so that things being drawn on screen+are scaled to fit the entire dimensions of actual display. Check #link: Graphics and Animation# to+read more about using this function.++#### waitforkey++Waits for the user to press a key when the graphics window is in focus.++Example:++```+waitforkey()+```

@@ -0,0 +1,26 @@+### Keyboard Functions++#### getkeystate++Captures the keyboard state and returns the captured state.+This state can be used with #link: inkeystate# function to check if some+keys were pressed during the capture.++#### inkeystate++Checks if the provided key was pressed when the keyboard state was captured.+The function accept the keyboard scancode, and should be passed values in+the builtin #link: scancodes# dictionary.++#### getkeypresses++Returns the keycodes of all the keys that were pressed since the last call+to this function, in a list.++#### keycodes++Contains the keycodes for the different keys.++#### scancodes++Contains the scancodes for the different keys.

@@ -0,0 +1,115 @@+### List Functions++#### insertleft++Inserts an element at the start of the list, and returns the modified+list.++Example:++```+let mylist = [2, 3]+let newlist = insertleft(10, mylist)+inspect(newlist) -- outputs : [10, 2, 3]+getkey()+```++#### insertright++Inserts an element at the end of the list, and returns the modified+list.++Example:++```+let mylist = [2, 3]+let newlist = insertright(mylist, 10)+inspect(newlist) -- outputs : [2, 3, 10]+getkey()+```++#### head++Gets the first item in the list.++Example:++```+let mylist = [2, 3]+inspect(head(mylist)) -- outputs : 2+getkey()+```++#### take++Returns another list made by taking the given number of items from the beginning of the list.++Example:++```+let mylist = [2, 3, 4, 5, 6]+inspect(take(mylist, 2)) -- outputs : [2, 3]+getkey()+```++#### drop++Returns another list made by dropping the given number of items from the beginning of the list.++Example:++```+let mylist = [2, 3, 4, 5, 6]+inspect(drop(mylist, 2)) -- outputs : [4, 5, 6]+getkey()+```++#### sum++Computes the sum of given items in the list.++Example:++```+let mylist = [2, 3, 4, 5, 6]+inspect(sum(mylist)) -- outputs : 20+getkey()+```++#### contains++Checks if the list contains a value.++Example:++```+let mylist = [2, 3, 4, 5, 6]+inspect(contains(mylist, 4)) -- outputs : true+inspect(contains(mylist, 40)) -- outputs : false+getkey()+```++#### filter++Calls the given callback on the items in the list, and remove those+for which the function returned false.++Example:++```+let mylist = [2, 3, 4, 5, 6]+inspect(filter(mylist, fn(x) mod(x, 2) == 0 endfn)) -- outputs [2, 4, 6]+getkey()+```++#### size++Returns the number of items in a list or a dictionary.++Example:++```+let mylist = [2, 3, 4, 5, 6]+inspect(size(mylist)) -- outputs  : 5+getkey()+```

@@ -0,0 +1,42 @@+### Math Functions+++#### sin++The trignometric sine function. Accepts an angle in degrees and return+it's sine value++#### cos++The trignometric cosine function. Accepts an angle in degrees and return+it's cosine value++#### tan++The trignometric tangent function. Accepts an angle in degrees and return+it's tan value++#### asin++The trignometric arc sine function. Returns an angle in degrees.++#### acos++The trignometric arc cosine function. Returns an angle in degrees.++#### atan++The trignometric arc tangent function. Returns an angle in degrees.++#### mod++The modulus function.++#### random++`random(a1, a2)` returns a random number `x` such that `a1 <= x <= a2`++#### round++Rounds the argument to the nearest integer.+

@@ -0,0 +1,44 @@+### Miscellaneous Functions++#### print++Accept many values and prints them in order, without an ending newline.++Example:++```+printn(1, ", SPADE") -- output: "1, SPADE"+```++#### println++Accept many values and prints them in order, ending in a newline.++Example:++```+println(100)+println(1, "SPADE")+```++#### not++Boolean not operation.++#### getkey++Waits for the user to press a key, and returns the pressed key as a string value.++#### inputline++Prints a prompt, and reads a string from keyboard.++#### wait++Waits for the number of seconds specified in the argument.++Example:++```+wait(0.5)  -- Waits for half second.+```

@@ -0,0 +1,9 @@+### Serialization Functions++#### jsonencode++Returns JSON encoded representation of the argument in bytes.++#### jsondecode++Decodes the JSON encoded bytes into the corresponding value.

@@ -0,0 +1,44 @@+### Sound Functions++#### makesound++Prepares a sound sample using a callback. The callback should accept+an integer value, and return a sample value.++The samples should be a floating point value between -1 and 1.++The sampling frequency is 44100 Hz.++#### maketone++Prepares a sound sample of the frequency given in the argument.+++#### loadsound++Loads a sound from the WAV file at path provided in the argument.++#### playsound++Plays the sample prepared by `loadsound` or `maketone` or `makesound`+at the given channel. There are 8 available channels.++Example:++```+graphics()+let s = maketone(255) -- Make a tone of frequency 255+playsound(s, 0) -- Play it on channel 0+waitforkey()+```++#### setvolume++Sets the sound volume of the channel specified by the first argument.+The volume is specified in the second argument, as a value from 0 to 128.++#### setvolumelr++Sets the sound volume of the channel specified by the first argument.+The left, right volumes are specified using the second and thrird arguments, as a value from 0 to 128.+

@@ -0,0 +1,9 @@+### String Functions++#### decodeutf8++Accepts a byte value representing a UTF-8 encoded string and return the string.++#### encodeutf8++Accepts a string argument and returns the bytes that represent its UTF-8 encoding.

@@ -0,0 +1,5 @@+### Time Functions++#### timestamp++Gets the number of nanosecond after 1970-01-01.

@@ -0,0 +1,76 @@+### Graphics and Animation++Use the #link: graphics# or #link: graphicswindow# functions to open a+graphics window and start drawing things on screen.++The origin is located at the top, left corner.++Objects are drawn in the currently draw color. Use #link: setcolor# function+to change the draw color.++Color is represented by its red, green and blue components. Each can range from+0 to 255.++##### Accelerated mode++If acceleration is enabled, output of the drawing commands are not rendered+until #link: drawscreen# is called.++##### Clearing screen++Use #link: clearscreen# function to fill the screen with the current draw color.++##### Working with screens of different resolutions++Since displays vary widely in their sizes and resolutions, dimensions that+look good on one display might look too small, or too large in a different+display resolution.++To fix this, use #link: setlogicalsize# function to correctly scale rendered+objects to look similar in different displays.++##### Keyboard input handling++The #link: getkeypresses# function can be used to get all the keys that have been pressed+since that last call of this function. This function returns a list that contains+the keycode of the keys. The keycodes can be compared using the values in #link: keycodes#+dictionary.++Example:++```+graphicswindow(500, 500)+wait(5)+-- Wait while user presses some keys+let keyspressed = getkeypresses()++if contains(keyspressed, keycodes.b) then+  -- If user pressed 'b' then set color to red+  setcolor(255, 0, 0)+else+ -- or else set color to green+  setcolor(0, 255, 0)+endif+circle(100, 100, 50)+drawscreen()+waitforkey()+```++This method is not very good to detect simultaneous key presses. For that, use+#link: getkeystate# function to capture keyboard state at a point. Then use+#link: inkeystate# function to check if a certain key was pressed at the point+of capture.++Example:++```+graphics()+loop+  let ks = getkeystate()+  -- Capture keyboard state at this point.+  -- Check if both up and left arrows are pressed in the captured state+  if (inkeystate(ks, scancodes.up) and inkeystate(ks, scancodes.left)) then+    break+  endif+endloop+```

@@ -0,0 +1,23 @@+### IDE Reference++##### Menu++Menus are activated using Alt key combinations. 'Alt + f' opens file menu, 'Alt + r' opens run menu etc.+Pressing Esc key closes open menus.++##### Windows++Besides the editor window, there is the log window and the watch window. Log window displays error+ and debug information. Contents of the log window can be cleared by the "Clear log" menu item.++The watch window appears when stepping through the program, and displays the contents of the current+functions scope.++##### Debugging++A program can be started in step mode by pressing 'F8' or selecting the step menu item. By pressing+the 'F8' key it is possible to step through the program, expression by expression. The currently evaluated+line is indicated by a '>' in the left margin, and the currently evaluated expression is indicated by+underlining it.++A program can call the `debug()` function at any point to break into the debugger.

@@ -0,0 +1,290 @@+## Language Reference++### Variables++Variables are initialized using `let` statement. For example++```+let a = 10+```++### Conditionals++#### if-then++This is used to conditionally execute parts of a program. For example++```+if age > 10 then+    println("Greater than 10")+endif+```++#### if-then-else++This is used to provide an alternative if the condition does not hold.++```+if age > 10+  then+    println("Greater than 10")+  else+    println("Less than or equal to 10")+endif+```++#### if-then-elseif-else++This is like if-else statemebt but can be used to provide many alternative branches.++```+if age > 10+  then+    println("Greater than 10")+  elseif age > 5 then+    println("Greater than 5")+  elseif age > 2 then+    println("Greater than 2")+  else+    println("Less than or equal to 2")+endif+```++### Loops++Loops are using to execute a sequence of statements repeatedly. Following+looping constructs are available.++#### for statement++This loop can be used to execute some group of statements repeatedly,+while incrementing a variable at each iteration.++Example:++```+for i = 1 to 100+  println(i)+endfor+```++The `break` statement can be used to break out of the loop.++#### while statement++This loop execute a group of statements repeatedly as long as the specified+condition hold.++Example:++```+let i = 10+while i < 0+  println(i)+  let i = i + 1+endwhile+```++The `break` statement can be used to break out of the loop.++#### loop statement++This is an unconditional looping statement.+The only way to exit from the loop is by using a `break` statement.++Example:++```+let l = 0+loop+  println(l)+  let l = l + 1+  if l > 10 then break endif+endloop+getkey()+```++### Functions/Procedures++Functions are declared using the `proc` keyword. For example++```+proc multiply(a, b)+  return a * b+endproc++println(multiply(5, 2))+```++### Expressions++Expressions are things that can be evaluated to a value. Following types+of expressions are available in the language.+++#### Literals++The language support the following literals.++Integers -> `1500`+Boolean -> `true`, `false`+Floating -> `12.34`+Bytes -> `0x21`+String -> `"SPADE"`+List -> `[12, 34, 56]`+Dictionary -> `{name : "John", age: 34}`+Anonymous function -> `fn(x) x * 2 endfn`++#### Variables++These refer to a variable, and evaluate to the same value that is held+by the variable.++#### If-then-else++These provide conditional evaluation, for example.++```+let x = if x == 0 then 1 else x+```++#### Binary operators++The following binary operators are available.++##### Numeric operators++`+` : addition operator+`-` : substraction operator+`*` : multiplication operator+`/` : division operator++##### Boolean operators++`<`   : less than+`>`   : greater then+`<=`  : less then or equal+`>=`  : greater than or equal+`==`  : equality check+`!==` : non-equality check+`and` : boolean AND+`or`  : boolean OR++The boolean 'not' operation is provided as a function #link: not#.++#### Function calls++Evaluates to the value returned by the function, for example,++```+proc multiply(a, b)+  return a * b+endproc++let a = multiply(5,2)+```++#### Index access++An index in a list expression can be accessed using the index accessor.+For example,++```+let list = [1,2,3,4]+print(list[2]) -- prints 2.+```++NOTE: List indexes starts from 1.++Index accessor can be attached to any expression, for example a function+returning a list. For example,++```+proc myFunc()+ return [1,2,3]+endproc+print(myFunc()[2]) -- prints 2.+```++#### Key access++An key in a dictionary expression can be accessed using the key accessor.+For example,++```+let person = { name: "John", age : 39 }+print(person.name) -- prints "John"+print(person.age) -- prints 39+```++Key accessor can be attached to any expression, for example a function+returning a dictionary. For example,++```+proc myFunc()+ return { name: "John", age : 39 }+endproc+print(myFunc().name) -- prints "John"+```++### Builtin data types++#### Numbers++Numbers are either represented as integers (which can be as big as required)+or double precision floating point values.++Mathematical operations convert from integer to floating point values as required.++```+let age = 45+let price = 0.23+```++#### Strings++Strings represent a sequence of unicode code points.++```+let name = "SPADE"+```++#### Bytes++Bytes represent some sequence of bytes.++```+let somebytes = 0xFFAB+```++#### Lists++Lists can hold a sequence of values.++```+let mylist = [ "SPADE", 10]++```++Item at an index `x` in list `l` can be accessed using notation `l[x]`.+Indexes start at `1`, so to access the first item in a list use `l[1]`.++See #link: List Functions#++#### Dictionary++Dictionaries are containers that can hold content at a string key.+For example, the data for a person can be held in a dictionary.++```+let person = { name: "John", age: 45}+```++indvidual items can be accessed using the key access notation. For example+to print the name of the person, we can do something like the following.++See #link: Dictionary Functions#++```+println(person.name)+```

@@ -0,0 +1,58 @@+# S.P.A.D.E Help and Documentation++Use arrow keys to move the cursor over links, and press enter to open+the page, press Esc to go back to the previous help page.++Press F1 to close and go back to code window.++For searching a topic, just start typing.++## Table of contents++IDE Reference+  #link: Menu#+  #link: Windows#+  #link: Debugging#+Language Reference+  #link: Variables#+  #link: Expressions#+    #link: Literals#+    #link: Variables#+    #link: Conditionals#+    #link: Binary operators#+      #link: Numeric operators#+      #link: Boolean operators#+    #link: Function calls#+    #link: Index access#+    #link: Key access#+  #link: Conditionals#+    #link: if-then#+    #link: if-then-else#+    #link: if-then-elseif-else#+  #link: Loops#+    #link: for statement#+    #link: while statement#+    #link: loop statement#+  #link: Functions/Procedures#+  #link: Builtin data types#+#link: Graphics and Animation#+  #link: Accelerated mode#+  #link: Clearing screen#+  #link: Working with screens of different resolutions#+  #link: Keyboard input handling#+Function References+  Graphics, Sound and Keyboard+    #link: Graphics Functions#+    #link: Sound Functions#+    #link: Keyboard Functions#+  #link: Concurrency Functions#+  #link: String Functions#+  #link: List Functions#+  #link: Dictionary Functions#+  #link: File Functions#+  #link: Serialization Functions#+  #link: Math Functions#+  #link: Time Functions#+  #link: Error Handling Functions#+  #link: Debugging Functions#+  #link: Miscellaneous Functions#

@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack  name:           spade-version:        0.1.0.0+version:        0.1.0.1 synopsis:       A simple programming and debugging environment. description:    A simple weakly typed, dynamic, interpreted programming langauge and terminal IDE. category:       language, interpreter, ide@@ -17,6 +17,25 @@ extra-source-files:     README.md     ChangeLog.md+    docs/graphics-and-animation.md+    docs/ide.md+    docs/language-reference.md+    docs/toc.md+    docs/functions/concurrency.md+    docs/functions/container.md+    docs/functions/debugging.md+    docs/functions/dictionary.md+    docs/functions/error-handling.md+    docs/functions/file.md+    docs/functions/graphics.md+    docs/functions/keyboard.md+    docs/functions/list.md+    docs/functions/math.md+    docs/functions/misc.md+    docs/functions/serializing.md+    docs/functions/sound.md+    docs/functions/string.md+    docs/functions/time.md  library   exposed-modules:

@@ -5,8 +5,3 @@  docContent :: [(FilePath, BS.ByteString)] docContent = $(embedDir "docs")---- helpTokens :: TH.Q TH.Exp--- helpTokens = TH.runIO $ do---   tokens <- parseHelp (decodeUtf8 docContent)---   TH.lift tokens