annotate manual.txt @ 347:ff7ea11b4b60

Add length method to executable bytearrays
author Michael Pavone <pavone@retrodev.com>
date Fri, 10 Apr 2015 00:48:12 -0700
parents 966a09d226e3
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
133
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
1 Intro
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
2 -----
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
3
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
4 TP is an ahead of time compiled, dynamically typed (though there are plans for an optional type checker) language heavily inspired by Smalltalk. The main goal of the language is to be a suitable target for a structured editor on touch-screen devices and tablets in particular. The prototype of the editor is not really complete enough to be useful at this time.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
5
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
6 Assignment
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
7 ----------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
8
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
9 Assignment is done with the <- operator. Inside a lambda, it is used to assign a value to a variable. Inside an object definition it is used to either assign an initial value to a property or a lambda to be used as the definition of the method. Assignments are currently the only construct that are not expressions and as a result they cannot be used in an expression construct. This may change in the future.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
10
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
11
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
12 Symbols
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
13 -------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
14
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
15 Symbols in TP must start with a letter, underscore, bang, question mark or at symbol. Numbers and colons can be used in symbol names as long as they are not the first character. Colons allow a function or method name to be split into multiple parts with the arguments interspersed between them. This is covered in more detail in the second on function and method calls.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
16
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
17 Lambdas
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
18 -------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
19
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
20 Lambdas are enclosed in curly braces. If present, the argument list is preceded by a colon. Individual argument names are separated by spaces and may also be preceded by a colon. These internal colons provide a hint to the user (and eventually the structured editor) about how to best intersperse function name parts and arguments. The body of a lambda is made up of zero or more assignments or expressions. The result of evaluating the final expression of a lambda is used as the result.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
21
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
22 Examples:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
23 {} //Empty lambda with no arguments
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
24 :foo bar {} //Empty lambda with two arguments: foo and bar
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
25 :foo :bar {} //Same as before with a placement hint
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
26 :foo {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
27 foo
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
28 } //A lambda that simply returns its only argument
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
29
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
30 Objects
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
31 -------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
32
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
33 TP has no named object types. All objects are created via object literals. An object literal is started with a hash followed by an open curly bracket character and is terminated with a close curly bracket character. Properties and methods are defined with assignments. A property is really just syntactic sugar for a getter method and a setter method. The getter method has a name that is identical to the name of the property. The setter method has a bang appended to the end of the property name. Setter methods return the object being modified.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
34
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
35 A method is created when a lambda is assigned to a name inside of an object definition. This assignment must be done with a literal lambda. Assigning a lambda to a variable and then using that variable inside an object definition will generate a property that is initialized to that value. The first argument to a method is named self and refers to the object the method was called on. If self is not explicitly named as the first argument, it will be added implicitly.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
36
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
37 Examples:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
38 #{} //Object with no methods
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
39 #{
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
40 foo <- 42
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
41 bar <- baz
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
42 } //Object with two properties
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
43 #{
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
44 baz <- 42
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
45 foo <- :bar {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
46 2 * bar + (self baz)
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
47 }
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
48 }//object with method with an implicit self parameter
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
49 #{
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
50 baz <- 42
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
51 foo <- :self bar {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
52 2 * bar + (self baz)
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
53 }
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
54 }//identical object with an explicit self parameter on the foo method
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
55 _foo <- :bar { 2 * bar }
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
56 #{
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
57 foo <- _foo
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
58 }//object with a property named foo initialized to contain a lambda
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
59
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
60 Operators
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
61 ---------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
62
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
63 TP has the following binary operators. Operators are listed in order of precedence with operators of the same precedence listed on the same line.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
64 * / % //multiplication, division, modulus
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
65 + - . xor and or //addition, subtraction, concatenation, bitwise operations
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
66 <= >= < > = != //comparison
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
67 && || //logical
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
68
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
69 Operators can be the target of an assignment in an object definition. This allows operators to be defined for user types.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
70
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
71 Function and method calls
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
72 -------------------------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
73
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
74 There are three syntaxes for function and method calls. There is the unary method syntax, the regular method syntax and the function call syntax. Despite their names, there is no semantic difference between these three syntaxes and they can be used for both function calls and method calls. The one limitation is that the unary method syntax can only be used with methods/functions that take a single argument, including the self argument.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
75
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
76 The unary syntax consists of the first parameter followed by the function or method name. The two are separated by a space. Example:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
77
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
78 object methodName
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
79
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
80 The regular method syntax adds a colon to the method or function name. Additional arguments follow the colon and are separated by spaces. Example:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
81
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
82 firstParam methodName: secondParam thirdParam
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
83
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
84 The function call syntax is similar, but has the first argument following the method or function name. This syntax is generally the only way to call a function with no arguments. Examples:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
85
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
86 methodName: firstParam secondParam thirdParam
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
87 funcWithNoArgs:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
88
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
89 Symbols can contain internal colons and when used as a function or method name, the symbol can be split into several pieces at those colons. Example:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
90
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
91 //call foo:withBar:andQux with the arguments: baz, dive and quixotic
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
92 foo: baz withBar: dive andQux: quixotic
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
93
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
94 Flow Control
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
95 ------------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
96
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
97 TP has no explicit flow control structures. Instead, the flow control structures are implemented as methods that take lambdas as arguments. The methods if and if:else are implemented on the boolean objects and provide for conditional execution. while:do is implemented on lambda objects and provides a basic while loop. foreach is implemented on sequence types to provide a mechanism for easily looping over an array. Examples:
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
98
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
99 if: foo = bar {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
100 //do something when foo is equal to bar
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
101 }
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
102
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
103 if: foo = bar {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
104 //do something when foo is equal to bar
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
105 } else: {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
106 //do something else when foo is not equal to bar
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
107 }
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
108
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
109 while: { foo = bar } do: {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
110 foo bazinate
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
111 }
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
112
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
113 //print each string in the array
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
114 foreach: #["foo" "bar" "baz" "qux"] :index value {
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
115 print: (value . "\n")
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
116 }
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
117
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
118 Scope
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
119 -----
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
120
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
121 Variables are lexically scoped. Objects also participate in scoping. This allows access to properties and methods in the current object and objects in parent scopes without an explicit reference to the relevant object. Modules exist at the root of the scope tree. The name true, refers to the module in modules/true.tp unless it has been shadowed with an assignment.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
122
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
123 Module
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
124 ------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
125
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
126 A TP source file contains exactly one module. A module is simply an object. The top level of a TP source file should be an object literal or a lambda with no arguments that returns an object literal.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
127
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
128 Importing
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
129 ---------
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
130
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
131 Methods from one object can be imported into another object. This is essentially just synatctic sugar for delegation. A reference to the imported object is created in the target object and calls to the imported methods are forwarded to that object.
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
132
966a09d226e3 Added basic language manual
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
133 Imports are currently not really implemented in the C backend at this moment, but I may be able to add partial support in time for the contest.