summaryrefslogtreecommitdiff
path: root/doc/lang.txt
blob: 1c09dd708323193619dd73948cb11acfcfcab975 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
                    The Myrddin Programming Language
                              Jul 2012
                            Ori Bernstein

1. OVERVIEW:

        Myrddin is designed to be a simple, low level programming
        language.  It is designed to provide the programmer with
        predictable behavior and a transparent compilation model,
        while at the same time providing the benefits of strong
        type checking, generics, type inference, and similar.
        Myrddin is not a language designed to explore the forefront
        of type theory, or compiler technology. It is not a language
        that is focused on guaranteeing perfect safety. It's focus
        is on being a practical, small, fairly well defined, and
        easy to understand language for work that needs to be close
        to the hardware.

        Myrddin is a computer language influenced strongly by C
        and ML, with ideas from Rust, Go, C++, and numerous other
        sources and resources.


2. LEXICAL CONVENTIONS:

    The language is composed of several classes of token. There
    are comments, identifiers, keywords, punctuation, and whitespace.
    
    Comments, begin with "/*" and end with "*/". They may nest.

        /* this is a comment /* with another inside */ */

    Identifiers begin with any alphabetic character or underscore,
    and continue with any number of alphanumeric characters or
    underscores. Currently the compiler places a limit of 1024
    bytes on the length of the identifier.

        some_id_234__

    Keywords are a special class of identifier that is reserved
    by the language and given a special meaning. The set of
    keywords in Myrddin are as follows:

        castto          match
        const           pkg
        default         protect
        elif            sizeof
        else            struct
        export          trait
        extern          true
        false           type
        for             union
        generic         use
        goto            var
        if              while


    At the current stage of development, not all of these keywords
    are implemented within the language.[1]

    Literals are a direct representation of a data object within the
    source of the program. There are several literals implemented
    within the Myrddin language. These are fully described in sectio

3. SYNTAX OVERVIEW:

    Myrddin syntax will likely have a familiar-but-strange taste
    to many people. Many of the concepts and constructions will be
    similar to those present in C, but different.

    3.1. Declarations:

        A declaration consists of a declaration class (ie, one
        of 'const', 'var', or 'generic'), followed by a declaration
        name, optionally followed by a type and assignment. One thing
        you may note is that unlike most other languages, there is no
        special function declaration syntax. Instead, a function is
        declared like any other value: By assigning its name to a
        constant or variable.

            const:      Declares a constant value, which may not be
                        modified at run time. Constants must have
                        initializers defined.
            var:        Declares a variable value. This value may be
                        assigned to, copied from, and 
            generic:    Declares a specializable value. This value
                        has the same restricitions as a const, but
                        taking its address is not defined. The type
                        parameters for a generic must be explicitly
                        named in the declaration in order for their
                        substitution to be allowed.

        In addition, there is one modifier allowed on declarations:
        'extern'. Extern declarations are used to declare symbols from
        another module which cannot be provided via the 'use' mechanism.
        Typical uses would be to expose a function written in assembly. They
        can also be used as a workaround for external dependencies.

        Examples:

            Declare a constant with a value 123. The type is not defined,
            and will be inferred.

                const x = 123
                
            Declares a variable with no value and no type defined. The 
            value can be assigned later (and must be assigned before use),
            and the type will be inferred.

                var y

            Declares a generic with type '@a', and assigns it the value
            'blah'. Every place that 'z' is used, it will be specialized,
            and the type parameter '@a' will be substituted.

                generic z : @a = blah

            Declares a function f with and without type inference. Both
            forms are equivalent. 'f' takes two parameters, both of type
            int, and returns their sum as an int

                const f = {a, b
                    var c : int = 42
                    -> a + b + c
                }

                const f : (a : int, b : int -> int) = {a : int, b : int -> int
                    var c : int  = 42
                    -> a + b + c
                }

    3.2. Literal Values

        Integers literals are a sequence of digits, beginning with a
        digit and possibly separated by underscores. They are of a
        generic type, and can be used where any numeric type is
        expected. They may be prefixed with "0x" to indicate that the
        following number is a hexadecimal value, or 0b to indicate a
        binary value. Decimal values are not prefixed, and octal values
        are not supported.

            eg: 0x123_fff, 0b1111, 1234

        Float literals are also a sequence of digits beginning with a
        digit and possibly separated by underscores. They are also of a
        generic type, and may be used whenever a floating point type is
        expected. Floating point literals are always in decimal, and
        as of this writing, exponential notation is not supported[2]

            eg: 123.456

        String literals represent a byte array describing a string in
        the compile time character set. Any byte values are allowed in
        a string literal. There are a number of escape sequences
        supported:
            \n          newline
            \r          carriage return
            \t          tab
            \b          backspace
            \"          double quote
            \'          single quote
            \v          vertical tab
            \\          single slash
            \0          nul character
            \xDD        single byte value, where DD are two hex digits.
        String literals begin with a ", and continue to the next
        unescaped ".

            eg: "foo\"bar"

        Character literals represent a single codepoint in the character
        set. A character starts with a single quote, contains a single
        codepoint worth of text, encoded either as an escape sequence
        or in the input character set for the compiler (generally UTF8).

            eg: 'א', '\n', '\u1234'[3]

        Boolean literals are either the keyword "true" or the keyword
        "false".

            eg: true, false

        Funciton literals describe a function. They begin with a '{',
        followed by a newline-terminated argument list, followed by a
        body and closing '}'. They will be described in more detail
        later in this manual.

            eg: {a : int, b
                    -> a + b
                }
        
        Sequence literals describe either an array or a structure
        literal. They begin with a '[', followed by an initializer
        sequence and closing ']'. For array literals, the initializer
        sequence is either an indexed initializer sequence[4], or an
        unindexed initializer sequence. For struct literals, the
        initializer sequence is always a named initializer sequence.

        An unindexed initializer sequence is simply a comma separated
        list of values. An indexed initializer sequence contains a
        '#number=value' comma separated sequence, which indicates the
        index of the array into which the value is inserted. A named
        initializer sequence contains a comma separated list of
        '.name=value' pairs.

            eg: [1,2,3], [#2=3, #1=2, #0=1], [.a = 42, .b="str"]

        A tuple literal is a parentheses separated list of values.
        A single element tuple contains a trailing comma.

            eg: (1,), (1,'b',"three")

    3.3. Control Constructs and Blocks:
    
            if          for
            while       match
            goto        

        The control statements in Myrddin are similar to those in many other
        popular languages, and with the exception of 'match', there should
        be no surprises to a user of any of the Algol derived languages.
        Where a truth value is required, any type with the builtin trait
        'tctest' can be used in all of these.

        Blocks are the "carriers of code" in Myrddin programs. They consist
        of series of expressions, typically ending with a ';;', although the
        function-level block ends at the function's '}', and in if
        statemments, an 'elif' may terminate a block. They can contain any
        number of declarations, expressions, control constructs, and empty
        lines. Every control statement example below will (and, in fact,
        must) have a block attached to the control statement.
        
        If statements branch one way or the other depending on the truth
        value of their argument. The truth statement is separated from the
        block body 

            if true
                std.put("The program always get here")
            elif elephant != mouse
                std.put("...eh.")
            else
                std.put("The program never gets here")
            ;;

        For statements begin with an initializer, followed by a test
        condition, followed by an increment action. For statements run the
        initializer once before the loop is run, the test each on each
        iteration through the loop before the body, and the increment on
        each iteration after the body. If the loop is broken out of early
        (for example, by a goto), the final increment will not be run. The
        syntax is as follows:

            for init; test; increment
                blockbody()
            ;;

        While loops are equivalent to for loops with empty initializers
        and increments. They run the test on every iteration of the loop,
        and 


    3.4. Data Types:

        The language defines a number of built in primitive types. These
        are not keywords, and in fact live in a separate namespace from
        the variable names. Yes, this does mean that you could, if you want,
        define a variable named 'int'.

        There are no implicit conversions within the language. All types
        must be explicitly cast if you want to convert, and the casts must
        be of compatible types, as will be described later.

            3.4.1. Primitive types:

                    void        
                    bool            char
                    int8            uint8
                    int16           uint16
                    int32           uint32
                    int64           uint64
                    int             uint
                    long            ulong
                    float32         float64

                These types are as you would expect. 'void' represents a
                lack of type, although for the sake of genericity, you can
                assign between void, return void, and so on. This allows
                generics to not have to somehow work around void being a
                toxic type.

                bool is a boolean type, and can only be used for assignment
                and comparison. 

                char is a 32 bit integer type, and is guaranteed to be able
                to hold exactly one codepoint. It can be assigned integer
                literals, tested against, compared, and all the other usual
                numeric types.

                The various [u]intXX types hold, as expected, signed and
                unsigned integers of the named sizes respectively.
                Similarly, floats hold floating point types with the
                indicated precision.

                    var x : int         declare x as an int
                    var y : float32     declare y as a 32 bit float


            3.4.2. Composite types:

                    pointer
                    slice           array

                Pointers are, as expected, values that hold the address of
                the pointed to value. They are declared by appending a '*'
                to the type. Pointer arithmetic is not allowed. They are
                declared by appending a '*' to the base type

                Arrays are a group of N values, where N is part of the type.
                Arrays of different sizes are incompatible. Arrays in
                Myrddin, unlike many other languages, are passed by value.
                They are declared by appending a '[SIZE]' to the base type.

                Slices are similar to arrays in many contemporary languages.
                They are reference types that store the length of their
                contents. They are declared by appending a '[,]' to the base
                type.
                    
                    foo*        type: pointer to foo
                    foo[123]    type: array of 123 foo
                    foo[,]      type: slice of foo

            3.4.3. Aggregate types:

                    tuple           struct
                    union

                Tuples are the traditional product type. They are declared
                by putting the comma separated list of types within square
                brackets.

                Structs are aggregations of types with named members. They
                are declared by putting the word 'struct' before a block of
                declaration cores (ie, declarations without the storage type
                specifier).

                Unions are the traditional sum type. They consist of a tag
                (a keyword prefixed with a '`' (backtick)) indicating their
                current contents, and a type to hold. They are declared by
                placing the keyword 'union' before a list of tag-type pairs.
                They may also omit the type, in which case, the tag is
                suficient to determine which option was selected.

                    [int, int, char]            a tuple of 2 ints and a char

                    struct                      a struct containing an int named
                        a : int                 'a', and a char named 'b'.
                        b : char                
                    ;;

                    union                       a union containing one of
                        `Thing int              int or char. The values are not
                        `Other float32          named, but they are tagged.
                    ;;


            3.4.4. Magic types:

                    tyvar           typaram
                    tyname

                A tyname is a named type, similar to a typedef in C, however
                it genuinely creates a new type, and not an alias. There are
                no implicit conversions, but a tyname will inherit all
                constraints of its underlying type.

                A typaram is a parametric type. It is used in generics as
                a placeholder for a type that will be substituted in later.
                It is an identifier prefixed with '@'. These are only valid
                within generic contexts, and may not appear elsewhere.

                A tyvar is an internal implementation detail that currently
                leaks out during type inference, and is a major cause of
                confusing error messages. It should not be in this manual,
                except that the current incarnation of the compiler will
                make you aware of it. It looks like '@$type', and is a
                variable that holds an incompletely inferred type.

                    type mine = int             creates a tyname named
                                                'mine', equivalent to int.


                    @foo                        creates a type parameter
                                                named '@foo'.

            3.4.5. :

    3.6. Packages and Uses:

            pkg     use

        A usefile imports a 

    3.7. Expressions:

4. TYPES:

5. EXAMPLES:
        
6. GRAMMAR:

7. FUTURE DIRECTIONS:

BUGS:

[1] TODO: trait, default, protect,
[2] TODO: exponential notation.
[3] TODO: \uDDDD escape sequences not yet recognized
[4] TODO: currently the only sequence literal implemented is the
          unindexed one