Commit 14788f27d05097373b35d12031e2787e88c1a2d2

added language introduction documentation
doc/introduction_guide.md
(103 / 0)
  
1Stackd Programming Language Guide
2==========
3
41. Defining Words
5----------
6
7To define a new word (similar to functions or procedures in applicative languages),
8there are different ways to do so.
9For normal words (not generic method implementations), use the colon syntax:
10
11 : <wordname> <stackeffect>
12 <body> ;
13
14The stackeffect declaration has no implications on the actual usage of the word. It
15is simply used for documentation - and in case of generic words, to find the apropriate
16generic method implementation.
17
18A short example is the `sq` word, which squares a number:
19
20 : sq ( x -- x*x )
21 dup * ;
22
23Here, `sq` takes one argument from the data stack (called `x` in the stackeffect declaration),
24`dup`licates it, meaning, that the value is twice on the stack, and multiplies them (`*`), putting
25the square back onto the stack.
26Here's a simple diagramm to illustrate this process when calling `sq`. Everything within brackets resembles the values
27on the stack with the most right value being the top of stack element:
28
29Example call: `5 sq ;`
30
31 Literal/Word Stackvalues Comment
32 ---------------------------------------------------
33 5 [ 5 ] (before calling sq)
34 dup [ 5 5 ] (in sq)
35 * [ 25 ] (in sq)
36
37For more examples take a look at the code within the files in the core/ or examples/ directories.
38
39
402. Defining Tuples
41----------
42
43With Tuples one can define custom data types and operations on them (via generic words). They contain
44so called slots, which are data fields. In contrast to most object-oriented programming languages,
45the operations on these datatypes are not part of the type definition, but kept indepedently (as, for
46example generic methods in CLOS - the Common Lisp Object System, are).
47
48Syntax:
49 tuple: <tuplename> <slotnames> ;
50
51Example:
52 tuple: person name age sex ;
53
54To create a new instance of a tuple:
55 person new ;
56
57Which will create a new instance of the `person` tuple, with all the slots undefined.
58A common idiom is to define a custom constructor word for a tuple, that can take some arguments
59to initialize the slots, if needed. By convention, these constructor words are named like the
60tuple, surrounded by `<` and `>`, e.g.: `<person>`.
61
62When not differently stated, accessor words (getters and setters) for all slots will be defined.
63Getter accessors have the following naming scheme:
64 slotname>>
65Whereas setter accessors are named like this:
66 >>slotname
67
68For our `person` tuple, the following accessors will be defined automatically by the Stackd runtime:
69 : name>> ( person -- name ) ;
70 : >>name ( person name -- person ) ;
71 : age>> ( person -- age ) ;
72 : >>age ( person age -- person ) ;
73 : sex>> ( person -- sex ) ;
74 : >>sex ( person sex -- person ) ;
75
76Note, that all setters keep the person instance on the stack, when finished, whereas getter accessors
77don't. This is meant to make instance initialization easier and makes more sense, since you usually
78want to keep on doing something with the tuple instance, after altering a slot value.
79
80Here's a complete overview of our `person` tuple example:
81
82 tuple: person name age sex ;
83
84 : <person> ( -- person )
85 person new ;
86
87 ! example word with using a person instance:
88 : say-hello ( person -- )
89 "hello, " print-
90 name>> print-
91 ", how are you today?" print ;
92
93 ! example usage:
94 ! this will create a new instance of person,
95 ! and call say-hello, which will then output:
96 ! "hello, Christopher Bertels, how are you today?"
97 <person>
98 >>name "Christopher Bertels"
99 >>age 22
100 >>sex "male"
101 say-hello ;
102
103# _more coming soon_ #