Merge pull request #2065 from hyphz/master

Add tutorials (Factor, Wolfram Language)

2 files changed, 319 insertions, 0 deletions

diff --git a/factor.html b/factor.html
new file mode 100644
index 00000000..a0726420
--- /dev/null
+++ b/factor.html
@@ -0,0 +1,182 @@
+---
+language: factor
+contributors:
+    - ["hyphz", "http://github.com/hyphz/"]
+filename: learnfactor.factor
+---
+
+Factor is a modern stack-based language, based on Forth, created by Slava Pestov.
+
+Code in this file can be typed into Factor, but not directly imported because the vocabulary and import header would make the beginning thoroughly confusing.
+
+```
+! This is a comment
+
+! Like Forth, all programming is done by manipulating the stack.
+! Stating a literal value pushes it onto the stack.
+5 2 3 56 76 23 65    ! No output, but stack is printed out in interactive mode
+
+! Those numbers get added to the stack, from left to right.
+! .s prints out the stack non-destructively.
+.s     ! 5 2 3 56 76 23 65
+
+! Arithmetic works by manipulating data on the stack.
+5 4 +    ! No output
+
+! `.` pops the top result from the stack and prints it.
+.    ! 9 
+
+! More examples of arithmetic:
+6 7 * .        ! 42 
+1360 23 - .    ! 1337 
+12 12 / .      ! 1 
+13 2 mod .     ! 1 
+
+99 neg .       ! -99 
+-99 abs .      ! 99 
+52 23 max .    ! 52 
+52 23 min .    ! 23 
+
+! A number of words are provided to manipulate the stack, collectively known as shuffle words.
+
+3 dup -          ! duplicate the top item (1st now equals 2nd): 3 - 3
+2 5 swap /       ! swap the top with the second element:        5 / 2
+4 0 drop 2 /     ! remove the top item (dont print to screen):  4 / 2
+1 2 3 nip .s     ! remove the second item (similar to drop):    1 3
+1 2 clear .s     ! wipe out the entire stack
+1 2 3 4 over .s  ! duplicate the second item to the top: 1 2 3 4 3 
+1 2 3 4 2 pick .s ! duplicate the third item to the top: 1 2 3 4 2 3
+
+! Creating Words 
+! The `:` word sets Factor into compile mode until it sees the `;` word.
+: square ( n -- n ) dup * ;    ! No output
+5 square .                     ! 25 
+
+! We can view what a word does too.
+! \ suppresses evaluation of a word and pushes its identifier on the stack instead.
+\ square see    ! : square ( n -- n ) dup * ;
+
+! After the name of the word to create, the declaration between brackets gives the stack effect.
+! We can use whatever names we like inside the declaration:
+: weirdsquare ( camel -- llama ) dup * ;
+
+! Provided their count matches the word's stack effect:
+: doubledup ( a -- b ) dup dup ; ! Error: Stack effect declaration is wrong
+: doubledup ( a -- a a a ) dup dup ; ! Ok
+: weirddoubledup ( i -- am a fish ) dup dup ; ! Also Ok
+
+! Where Factor differs from Forth is in the use of quotations.
+! A quotation is a block of code that is pushed on the stack as a value.
+! [ starts quotation mode; ] ends it.
+[ 2 + ]       ! Quotation that adds 2 is left on the stack
+4 swap call . ! 6
+
+! And thus, higher order words. TONS of higher order words.
+2 3 [ 2 + ] dip .s      ! Pop top stack value, run quotation, push it back: 4 3
+3 4 [ + ] keep .s       ! Copy top stack value, run quotation, push the copy: 7 4
+1 [ 2 + ] [ 3 + ] bi .s ! Run each quotation on the top value, push both results: 3 4
+4 3 1 [ + ] [ + ] bi .s ! Quotations in a bi can pull values from deeper on the stack: 4 5 ( 1+3 1+4 )
+1 2 [ 2 + ] bi@ .s      ! Run the quotation on first and second values
+2 [ + ] curry           ! Inject the given value at the start of the quotation: [ 2 + ] is left on the stack
+
+! Conditionals
+! Any value is true except the built-in value f.
+! A built-in value t does exist, but its use isn't essential.
+! Conditionals are higher order words as with the combinators above.
+
+5 [ "Five is true" . ] when                     ! Five is true
+0 [ "Zero is true" . ] when                     ! Zero is true
+f [ "F is true" . ] when                        ! No output
+f [ "F is false" . ] unless                     ! F is false
+2 [ "Two is true" . ] [ "Two is false" . ] if   ! Two is true 
+
+! By default the conditionals consume the value under test, but starred variants 
+! leave it alone if it's true:
+
+5 [ . ] when*      ! 5
+f [ . ] when*      ! No output, empty stack, f is consumed because it's false
+
+
+! Loops
+! You've guessed it.. these are higher order words too.
+
+5 [ . ] each-integer               ! 0 1 2 3 4 
+4 3 2 1 0 5 [ + . ] each-integer   ! 0 2 4 6 8
+5 [ "Hello" . ] times              ! Hello Hello Hello Hello Hello
+
+! Here's a list:
+{ 2 4 6 8 }                        ! Goes on the stack as one item
+
+! Loop through the list:
+{ 2 4 6 8 } [ 1 + . ] each          ! Prints 3 5 7 9
+{ 2 4 6 8 } [ 1 + ] map             ! Leaves { 3 5 7 9 } on stack
+
+! Loop reducing or building lists:
+{ 1 2 3 4 5 } [ 2 mod 0 = ] filter  ! Keeps only list members for which quotation yields true: { 2 4 }  
+{ 2 4 6 8 } 0 [ + ] reduce .        ! Like "fold" in functional languages: prints 20 (0+2+4+6+8)
+{ 2 4 6 8 } 0 [ + ] accumulate . .  ! Like reduce but keeps the intermediate values in a list: prints { 0 2 6 12 } then 20 
+1 5 [ 2 * dup ] replicate .         ! Loops the quotation 5 times and collects the results in a list: { 2 4 8 16 32 }
+1 [ dup 100 < ] [ 2 * dup ] produce ! Loops the second quotation until the first returns false and collects the results: { 2 4 8 16 32 64 128 }
+
+! If all else fails, a general purpose while loop:
+1 [ dup 10 < ] [ "Hello" . 1 + ] while  ! Prints "Hello" 10 times
+                                        ! Yes, it's hard to read
+                                        ! That's what all those variant loops are for
+
+! Variables
+! Usually Factor programs are expected to keep all data on the stack.
+! Using named variables makes refactoring harder (and it's called Factor for a reason)
+! Global variables, if you must:
+
+SYMBOL: name            ! Creates name as an identifying word
+"Bob" name set-global   ! No output
+name get-global .       ! "Bob"                     
+
+! Named local variables are considered an extension but are available
+! In a quotation..
+[| m n                  ! Quotation captures top two stack values into m and n
+ | m n + ]              ! Read them
+
+! Or in a word..
+:: lword ( -- )           ! Note double colon to invoke lexical variable extension
+   2 :> c                 ! Declares immutable variable c to hold 2
+   c . ;                  ! Print it out
+
+! In a word declared this way,  the input side of the stack declaration 
+! becomes meaningful and gives the variable names stack values are captured into
+:: double ( a -- result ) a 2 * ;
+
+! Variables are declared mutable by ending their name with a shriek
+:: mword2 ( a! -- x y )   ! Capture top of stack in mutable variable a
+   a                      ! Push a
+   a 2 * a!               ! Multiply a by 2 and store result back in a
+   a ;                    ! Push new value of a 
+5 mword2                  ! Stack: 5 10
+
+! Lists and Sequences
+! We saw above how to push a list onto the stack
+
+0 { 1 2 3 4 } nth         ! Access a particular member of a list: 1
+10 { 1 2 3 4 } nth        ! Error: sequence index out of bounds
+1 { 1 2 3 4 } ?nth        ! Same as nth if index is in bounds: 2
+10 { 1 2 3 4 } ?nth       ! No error if out of bounds: f
+
+{ "at" "the" "beginning" } "Append" prefix    ! { "Append" "at" "the" "beginning" }
+{ "Append" "at" "the" } "end" suffix          ! { "Append" "at" "the" "end" }
+"in" 1 { "Insert" "the" "middle" } insert-nth ! { "Insert" "in" "the" "middle" }
+"Concat" "enate" append                       ! "Concatenate" - strings are sequences too
+"Concatenate" "Reverse " prepend              ! "Reverse Concatenate"
+{ "Concatenate " "seq " "of " "seqs" } concat ! "Concatenate seq of seqs"
+{ "Connect" "subseqs" "with" "separators" } " " join  ! "Connect subseqs with separators" 
+
+! And if you want to get meta, quotations are sequences and can be dismantled..
+0 [ 2 + ] nth                              ! 2
+1 [ 2 + ] nth                              ! +
+[ 2 + ] \ - suffix                         ! Quotation [ 2 + - ]
+
+
+```
+
+##Ready For More?
+
+* [Factor Documentation](http://docs.factorcode.org/content/article-help.home.html)
diff --git a/wolfram.md b/wolfram.md
new file mode 100644
index 00000000..4514006d
--- /dev/null
+++ b/wolfram.md
@@ -0,0 +1,137 @@
+---
+language: wolfram
+contributors:
+    - ["hyphz", "http://github.com/hyphz/"]
+filename: learnwolfram.nb
+---
+
+The Wolfram Language is the underlying language originally used in Mathematica, but now available for use in multiple contexts.
+
+Wolfram Language has several interfaces:
+* The command line kernel interface on Raspberry Pi (just called _The Wolfram Language_) which runs interactively and can't produce graphical input.
+* _Mathematica_ which is a rich text/maths editor with interactive Wolfram built in: pressing shift+Return on a "code cell" creates an output cell with the result, which is not dynamic
+* _Wolfram Workbench_ which is Eclipse interfaced to the Wolfram Language backend
+
+The code in this example can be typed in to any interface and edited with Wolfram Workbench. Loading directly into Mathematica may be awkward because the file contains no cell formatting information (which would make the file a huge mess to read as text) - it can be viewed/edited but may require some setting up.
+
+```
+(* This is a comment *)
+
+(* In Mathematica instead of using these comments you can create a text cell
+   and annotate your code with nicely typeset text and images *)
+
+(* Typing an expression returns the result *)
+2*2              (* 4 *)
+5+8              (* 13 *)
+
+(* Function Call *)
+(* Note, function names (and everything else) are case sensitive *)
+Sin[Pi/2]        (* 1 *)
+
+(* Alternate Syntaxes for Function Call with one parameter *)
+Sin@(Pi/2)       (* 1 *)
+(Pi/2) // Sin    (* 1 *)
+
+(* Every syntax in WL has some equivalent as a function call *)
+Times[2, 2]      (* 4 *)
+Plus[5, 8]       (* 13 *)
+
+(* Using a variable for the first time defines it and makes it global *)
+x = 5            (* 5 *)
+x == 5           (* True, C-style assignment and equality testing *)
+x                (* 5 *)
+x = x + 5        (* 10 *)
+x                (* 10 *)
+Set[x, 20]       (* I wasn't kidding when I said EVERYTHING has a function equivalent *)
+x                (* 20 *)
+
+(* Because WL is based on a computer algebra system, *)
+(* using undefined variables is fine, they just obstruct evaluation *)
+cow + 5          (* 5 + cow, cow is undefined so can't evaluate further *)
+cow + 5 + 10     (* 15 + cow, it'll evaluate what it can *)
+%                (* 15 + cow, % fetches the last return *)
+% - cow          (* 15, undefined variable cow cancelled out *)
+moo = cow + 5    (* Beware, moo now holds an expression, not a number! *)
+
+(* Defining a function *)
+Double[x_] := x * 2    (* Note := to prevent immediate evaluation of the RHS
+                          And _ after x to indicate no pattern matching constraints *)
+Double[10]             (* 20 *)
+Double[Sin[Pi/2]]      (* 2 *)
+Double @ Sin @ (Pi/2)  (* 2, @-syntax avoids queues of close brackets *)
+(Pi/2) // Sin // Double(* 2, //-syntax lists functions in execution order *)
+
+(* For imperative-style programming use ; to separate statements *)
+(* Discards any output from LHS and runs RHS *)
+MyFirst[] := (Print@"Hello"; Print@"World")  (* Note outer parens are critical
+                                                ;'s precedence is lower than := *)
+MyFirst[]                                    (* Hello World *)
+
+(* C-Style For Loop *)
+PrintTo[x_] := For[y=0, y<x, y++, (Print[y])]  (* Start, test, incr, body *)
+PrintTo[5]                                     (* 0 1 2 3 4 *)
+
+(* While Loop *)
+x = 0; While[x < 2, (Print@x; x++)]     (* While loop with test and body *)
+
+(* If and conditionals *)
+x = 8; If[x==8, Print@"Yes", Print@"No"]   (* Condition, true case, else case *)
+Switch[x, 2, Print@"Two", 8, Print@"Yes"]  (* Value match style switch *)
+Which[x==2, Print@"No", x==8, Print@"Yes"] (* Elif style switch *)
+
+(* Variables other than parameters are global by default, even inside functions *)
+y = 10             (* 10, global variable y *)
+PrintTo[5]         (* 0 1 2 3 4 *)
+y                  (* 5, global y clobbered by loop counter inside PrintTo *)
+x = 20             (* 20, global variable x *)
+PrintTo[5]         (* 0 1 2 3 4 *)
+x                  (* 20, x in PrintTo is a parameter and automatically local *)
+
+(* Local variables are declared using the Module metafunction *)
+(* Version with local variable *)
+BetterPrintTo[x_] := Module[{y}, (For[y=0, y<x, y++, (Print@y)])]
+y = 20             (* Global variable y *)
+BetterPrintTo[5]   (* 0 1 2 3 4 *)
+y                  (* 20, that's better *)
+
+(* Module actually lets us declare any scope we like *)
+Module[{count}, count=0;        (* Declare scope of this variable count *)
+  (IncCount[] := ++count);      (* These functions are inside that scope *)
+  (DecCount[] := --count)]
+count              (* count - global variable count is not defined *)
+IncCount[]         (* 1, using the count variable inside the scope *)
+IncCount[]         (* 2, incCount updates it *)
+DecCount[]         (* 1, so does decCount *)
+count              (* count - still no global variable by that name *)
+
+(* Lists *)
+myList = {1, 2, 3, 4}     (* {1, 2, 3, 4} *)
+myList[[1]]               (* 1 - note list indexes start at 1, not 0 *)
+Map[Double, myList]       (* {2, 4, 6, 8} - functional style list map function *)
+Double /@ myList          (* {2, 4, 6, 8} - Abbreviated syntax for above *)
+Scan[Print, myList]       (* 1 2 3 4 - imperative style loop over list *)
+Fold[Plus, 0, myList]     (* 10 (0+1+2+3+4) *)
+FoldList[Plus, 0, myList] (* {0, 1, 3, 6, 10} - fold storing intermediate results *)
+Append[myList, 5]         (* {1, 2, 3, 4, 5} - note myList is not updated *)
+Prepend[myList, 5]        (* {5, 1, 2, 3, 4} - add "myList = " if you want it to be *)
+Join[myList, {3, 4}]      (* {1, 2, 3, 4, 3, 4} *)
+myList[[2]] = 5          (* {1, 5, 3, 4} - this does update myList *)
+
+(* Associations, aka Dictionaries/Hashes *)
+myHash = <|"Green" -> 2, "Red" -> 1|>   (* Create an association *)
+myHash[["Green"]]                       (* 2, use it *)
+myHash[["Green"]] := 5                  (* 5, update it *)
+myHash[["Puce"]] := 3.5                 (* 3.5, extend it *)
+KeyDropFrom[myHash, "Green"]            (* Wipes out key Green *)
+Keys[myHash]                            (* {Red} *)
+Values[myHash]                          (* {1} *)
+
+(* And you can't do any demo of Wolfram without showing this off *)
+Manipulate[y^2, {y, 0, 20}] (* Return a reactive user interface that displays y^2
+                               and allows y to be adjusted between 0-20 with a slider.
+                               Only works on graphical frontends *)
+```
+
+##Ready For More?
+
+* [Wolfram Language Documentation Center](http://reference.wolfram.com/language/)