forked from nim-lang/Nim
/
manual.txt
executable file
·2802 lines (2084 loc) · 95.9 KB
/
manual.txt
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
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=============
Nimrod Manual
=============
:Author: Andreas Rumpf
:Version: |nimrodversion|
.. contents::
"Complexity" seems to be a lot like "energy": you can transfer it from the end
user to one/some of the other players, but the total amount seems to remain
pretty much constant for a given task. -- Ran
About this document
===================
**Note**: This document is a draft! Several of Nimrod's features need more
precise wording. This manual will evolve into a proper specification some
day.
This document describes the lexis, the syntax, and the semantics of Nimrod.
The language constructs are explained using an extended BNF, in
which ``(a)*`` means 0 or more ``a``'s, ``a+`` means 1 or more ``a``'s, and
``(a)?`` means an optional *a*; an alternative spelling for optional parts is
``[a]``. The ``|`` symbol is used to mark alternatives
and has the lowest precedence. Parentheses may be used to group elements.
Non-terminals start with a lowercase letter, abstract terminal symbols are in
UPPERCASE. Verbatim terminal symbols (including keywords) are quoted
with ``'``. An example::
ifStmt ::= 'if' expr ':' stmts ('elif' expr ':' stmts)* ['else' stmts]
Other parts of Nimrod - like scoping rules or runtime semantics are only
described in an informal manner. The reason is that formal semantics are
difficult to write and understand. However, there is only one Nimrod
implementation, so one may consider it as the formal specification;
especially since the compiler's code is pretty clean (well, some parts of it).
Definitions
===========
A Nimrod program specifies a computation that acts on a memory consisting of
components called `locations`:idx:. A variable is basically a name for a
location. Each variable and location is of a certain `type`:idx:. The
variable's type is called `static type`:idx:, the location's type is called
`dynamic type`:idx:. If the static type is not the same as the dynamic type,
it is a super-type or subtype of the dynamic type.
An `identifier`:idx: is a symbol declared as a name for a variable, type,
procedure, etc. The region of the program over which a declaration applies is
called the `scope`:idx: of the declaration. Scopes can be nested. The meaning
of an identifier is determined by the smallest enclosing scope in which the
identifier is declared.
An expression specifies a computation that produces a value or location.
Expressions that produce locations are called `l-values`:idx:. An l-value
can denote either a location or the value the location contains, depending on
the context. Expressions whose values can be determined statically are called
`constant expressions`:idx:; they are never l-values.
A `static error`:idx: is an error that the implementation detects before
program execution. Unless explicitly classified, an error is a static error.
A `checked runtime error`:idx: is an error that the implementation detects
and reports at runtime. The method for reporting such errors is via *raising
exceptions*. However, the implementation provides a means to disable these
runtime checks. See the section pragmas_ for details.
An `unchecked runtime error`:idx: is an error that is not guaranteed to be
detected, and can cause the subsequent behavior of the computation to
be arbitrary. Unchecked runtime errors cannot occur if only `safe`:idx:
language features are used.
Lexical Analysis
================
Encoding
--------
All Nimrod source files are in the UTF-8 encoding (or its ASCII subset). Other
encodings are not supported. Any of the standard platform line termination
sequences can be used - the Unix form using ASCII LF (linefeed), the Windows
form using the ASCII sequence CR LF (return followed by linefeed), or the old
Macintosh form using the ASCII CR (return) character. All of these forms can be
used equally, regardless of platform.
Indentation
-----------
Nimrod's standard grammar describes an `indentation sensitive`:idx: language.
This means that all the control structures are recognized by indentation.
Indentation consists only of spaces; tabulators are not allowed.
The terminals ``IND`` (indentation), ``DED`` (dedentation) and ``SAD``
(same indentation) are generated by the scanner, denoting an indentation.
These terminals are only generated for lines that are not empty.
The parser and the scanner communicate over a stack which indentation terminal
should be generated: the stack consists of integers counting the spaces. The
stack is initialized with a zero on its top. The scanner reads from the stack:
If the current indentation token consists of more spaces than the entry at the
top of the stack, a ``IND`` token is generated, else if it consists of the same
number of spaces, a ``SAD`` token is generated. If it consists of fewer spaces,
a ``DED`` token is generated for any item on the stack that is greater than the
current. These items are later popped from the stack by the parser. At the end
of the file, a ``DED`` token is generated for each number remaining on the
stack that is larger than zero.
Because the grammar contains some optional ``IND`` tokens, the scanner cannot
push new indentation levels. This has to be done by the parser. The symbol
``indPush`` indicates that an ``IND`` token is expected; the current number of
leading spaces is pushed onto the stack by the parser. The symbol ``indPop``
denotes that the parser pops an item from the indentation stack. No token is
consumed by ``indPop``.
Comments
--------
`Comments`:idx: start anywhere outside a string or character literal with the
hash character ``#``.
Comments consist of a concatenation of `comment pieces`:idx:. A comment piece
starts with ``#`` and runs until the end of the line. The end of line characters
belong to the piece. If the next line only consists of a comment piece which is
aligned to the preceding one, it does not start a new comment:
.. code-block:: nimrod
i = 0 # This is a single comment over multiple lines belonging to the
# assignment statement. The scanner merges these two pieces.
# This is a new comment belonging to the current block, but to no particular
# statement.
i = i + 1 # This a new comment that is NOT
echo(i) # continued here, because this comment refers to the echo statement
Comments are tokens; they are only allowed at certain places in the input file
as they belong to the syntax tree! This feature enables perfect source-to-source
transformations (such as pretty-printing) and superior documentation generators.
A nice side-effect is that the human reader of the code always knows exactly
which code snippet the comment refers to.
Identifiers & Keywords
----------------------
`Identifiers`:idx: in Nimrod can be any string of letters, digits
and underscores, beginning with a letter. Two immediate following
underscores ``__`` are not allowed::
letter ::= 'A'..'Z' | 'a'..'z' | '\x80'..'\xff'
digit ::= '0'..'9'
IDENTIFIER ::= letter ( ['_'] (letter | digit) )*
The following `keywords`:idx: are reserved and cannot be used as identifiers:
.. code-block:: nimrod
:file: keywords.txt
Some keywords are unused; they are reserved for future developments of the
language.
Nimrod is a `style-insensitive`:idx: language. This means that it is not
case-sensitive and even underscores are ignored:
**type** is a reserved word, and so is **TYPE** or **T_Y_P_E**. The idea behind
this is that this allows programmers to use their own preferred spelling style
and libraries written by different programmers cannot use incompatible
conventions. A Nimrod-aware editor or IDE can show the identifiers as
preferred. Another advantage is that it frees the programmer from remembering
the exact spelling of an identifier.
String literals
---------------
`String literals`:idx: can be delimited by matching double quotes, and can
contain the following `escape sequences`:idx:\ :
================== ===================================================
Escape sequence Meaning
================== ===================================================
``\n`` `newline`:idx:
``\r``, ``\c`` `carriage return`:idx:
``\l`` `line feed`:idx:
``\f`` `form feed`:idx:
``\t`` `tabulator`:idx:
``\v`` `vertical tabulator`:idx:
``\\`` `backslash`:idx:
``\"`` `quotation mark`:idx:
``\'`` `apostrophe`:idx:
``\d+`` `character with decimal value d`:idx:;
all decimal digits directly
following are used for the character
``\a`` `alert`:idx:
``\b`` `backspace`:idx:
``\e`` `escape`:idx: `[ESC]`:idx:
``\xHH`` `character with hex value HH`:idx:;
exactly two hex digits are allowed
================== ===================================================
Strings in Nimrod may contain any 8-bit value, except embedded zeros.
Triple quoted string literals
-----------------------------
String literals can also be delimited by three double quotes
``"""`` ... ``"""``.
Literals in this form may run for several lines, may contain ``"`` and do not
interpret any escape sequences.
For convenience, when the opening ``"""`` is immediately followed by a newline,
the newline is not included in the string. The ending of the string literal is
defined by the pattern ``"""[^"]``, so this:
.. code-block:: nimrod
""""long string within quotes""""
Produces::
"long string within quotes"
Raw string literals
-------------------
There are also `raw string literals` that are preceded with the letter ``r``
(or ``R``) and are delimited by matching double quotes (just like ordinary
string literals) and do not interpret the escape sequences. This is especially
convenient for regular expressions or Windows paths:
.. code-block:: nimrod
var f = openFile(r"C:\texts\text.txt") # a raw string, so ``\t`` is no tab
To produce a single ``"`` within a raw string literal, it has to be doubled:
.. code-block:: nimrod
r"a""b"
Produces::
a"b
``r""""`` is not possible with this notation, because the three leading
quotes introduce a triple quoted string literal.
Generalized raw string literals
-------------------------------
The construct ``identifier"string literal"`` (without whitespace between the
identifier and the opening quotation mark) is a
`generalized raw string literal`:idx:. It is a shortcut for the construct
``identifier(r"string literal")``, so it denotes a procedure call with a
raw string literal as its only argument. Generalized raw string literals
are especially convenient for embedding mini languages directly into Nimrod
(for example regular expressions).
The construct ``identifier"""string literal"""`` exists too. It is a shortcut
for ``identifier("""string literal""")``.
Character literals
------------------
Character literals are enclosed in single quotes ``''`` and can contain the
same escape sequences as strings - with one exception: ``\n`` is not allowed
as it may be wider than one character (often it is the pair CR/LF for example).
A character is not an Unicode character but a single byte. The reason for this
is efficiency: for the overwhelming majority of use-cases, the resulting
programs will still handle UTF-8 properly as UTF-8 was specially designed for
this.
Another reason is that Nimrod can thus support ``array[char, int]`` or
``set[char]`` efficiently as many algorithms rely on this feature.
Numerical constants
-------------------
`Numerical constants`:idx: are of a single type and have the form::
hexdigit ::= digit | 'A'..'F' | 'a'..'f'
octdigit ::= '0'..'7'
bindigit ::= '0'..'1'
INT_LIT ::= digit ( ['_'] digit )*
| '0' ('x' | 'X' ) hexdigit ( ['_'] hexdigit )*
| '0o' octdigit ( ['_'] octdigit )*
| '0' ('b' | 'B' ) bindigit ( ['_'] bindigit )*
INT8_LIT ::= INT_LIT '\'' ('i' | 'I' ) '8'
INT16_LIT ::= INT_LIT '\'' ('i' | 'I' ) '16'
INT32_LIT ::= INT_LIT '\'' ('i' | 'I' ) '32'
INT64_LIT ::= INT_LIT '\'' ('i' | 'I' ) '64'
exponent ::= ('e' | 'E' ) ['+' | '-'] digit ( ['_'] digit )*
FLOAT_LIT ::= digit (['_'] digit)* ('.' (['_'] digit)* [exponent] |exponent)
FLOAT32_LIT ::= ( FLOAT_LIT | INT_LIT ) '\'' ('f' | 'F') '32'
FLOAT64_LIT ::= ( FLOAT_LIT | INT_LIT ) '\'' ('f' | 'F') '64'
As can be seen in the productions, numerical constants can contain underscores
for readability. Integer and floating point literals may be given in decimal (no
prefix), binary (prefix ``0b``), octal (prefix ``0o``) and hexadecimal
(prefix ``0x``) notation.
There exists a literal for each numerical type that is
defined. The suffix starting with an apostrophe ('\'') is called a
`type suffix`:idx:. Literals without a type suffix are of the type ``int``,
unless the literal contains a dot or ``E|e`` in which case it is of
type ``float``.
The type suffixes are:
================= =========================
Type Suffix Resulting type of literal
================= =========================
``'i8`` int8
``'i16`` int16
``'i32`` int32
``'i64`` int64
``'f32`` float32
``'f64`` float64
================= =========================
Floating point literals may also be in binary, octal or hexadecimal
notation:
``0B0_10001110100_0000101001000111101011101111111011000101001101001001'f64``
is approximately 1.72826e35 according to the IEEE floating point standard.
Other tokens
------------
The following strings denote other tokens::
( ) { } [ ] , ; [. .] {. .} (. .)
: = ^ .. `
`..`:tok: takes precedence over other tokens that contain a dot: `{..}`:tok: are
the three tokens `{`:tok:, `..`:tok:, `}`:tok: and not the two tokens
`{.`:tok:, `.}`:tok:.
In Nimrod one can define his own operators. An `operator`:idx: is any
combination of the following characters that is not listed above::
+ - * / < >
= @ $ ~ & %
! ? ^ . | \
These keywords are also operators:
``and or not xor shl shr div mod in notin is isnot``.
Syntax
======
This section lists Nimrod's standard syntax in ENBF. How the parser receives
indentation tokens is already described in the `Lexical Analysis`_ section.
Nimrod allows user-definable operators.
Binary operators have 8 different levels of precedence. For user-defined
operators, the precedence depends on the first character the operator consists
of. All binary operators are left-associative.
================ ============================================== ================== ===============
Precedence level Operators First characters Terminal symbol
================ ============================================== ================== ===============
7 (highest) ``$`` OP7
6 ``* / div mod shl shr %`` ``* % \ /`` OP6
5 ``+ -`` ``+ ~ |`` OP5
4 ``&`` ``&`` OP4
3 ``== <= < >= > != in not_in is isnot`` ``= < > !`` OP3
2 ``and`` OP2
1 ``or xor`` OP1
0 (lowest) ``? @ ^ ` : .`` OP0
================ ============================================== ================== ===============
The grammar's start symbol is ``module``.
.. include:: grammar.txt
:literal:
Semantics
=========
Constants
---------
`Constants`:idx: are symbols which are bound to a value. The constant's value
cannot change. The compiler must be able to evaluate the expression in a
constant declaration at compile time.
Nimrod contains a sophisticated compile-time evaluator, so procedures which
have no side-effect can be used in constant expressions too:
.. code-block:: nimrod
import strutils
const
constEval = contains("abc", 'b') # computed at compile time!
Types
-----
All expressions have a `type`:idx: which is known at compile time. Nimrod
is statically typed. One can declare new types, which is in essence defining
an identifier that can be used to denote this custom type.
These are the major type classes:
* ordinal types (consist of integer, bool, character, enumeration
(and subranges thereof) types)
* floating point types
* string type
* structured types
* reference (pointer) type
* procedural type
* generic type
Ordinal types
~~~~~~~~~~~~~
`Ordinal types`:idx: have the following characteristics:
- Ordinal types are countable and ordered. This property allows
the operation of functions as ``Inc``, ``Ord``, ``Dec`` on ordinal types to
be defined.
- Ordinal values have a smallest possible value. Trying to count further
down than the smallest value gives a checked runtime or static error.
- Ordinal values have a largest possible value. Trying to count further
than the largest value gives a checked runtime or static error.
Integers, bool, characters and enumeration types (and subranges of these
types) belong to ordinal types.
Pre-defined integer types
~~~~~~~~~~~~~~~~~~~~~~~~~
These integer types are pre-defined:
``int``
the generic signed integer type; its size is platform dependent
(the compiler chooses the processor's fastest integer type).
This type should be used in general. An integer literal that has no type
suffix is of this type.
intXX
additional signed integer types of XX bits use this naming scheme
(example: int16 is a 16 bit wide integer).
The current implementation supports ``int8``, ``int16``, ``int32``, ``int64``.
Literals of these types have the suffix 'iXX.
There are no `unsigned integer`:idx: types, only `unsigned operations`:idx:
that treat their arguments as unsigned. Unsigned operations all wrap around;
they cannot lead to over- or underflow errors. Unsigned operations use the
``%`` suffix as convention:
====================== ======================================================
operation meaning
====================== ======================================================
``a +% b`` unsigned integer addition
``a -% b`` unsigned integer subtraction
``a *% b`` unsigned integer multiplication
``a /% b`` unsigned integer division
``a %% b`` unsigned integer modulo operation
``a <% b`` treat ``a`` and ``b`` as unsigned and compare
``a <=% b`` treat ``a`` and ``b`` as unsigned and compare
``ze(a)`` extends the bits of ``a`` with zeros until it has the
width of the ``int`` type
``toU8(a)`` treats ``a`` as unsigned and converts it to an
unsigned integer of 8 bits (but still the
``int8`` type)
``toU16(a)`` treats ``a`` as unsigned and converts it to an
unsigned integer of 16 bits (but still the
``int16`` type)
``toU32(a)`` treats ``a`` as unsigned and converts it to an
unsigned integer of 32 bits (but still the
``int32`` type)
====================== ======================================================
`Automatic type conversion`:idx: is performed in expressions where different
kinds of integer types are used: the smaller type is converted to the larger.
For further details, see `Convertible relation`_.
Pre-defined floating point types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following floating point types are pre-defined:
``float``
the generic floating point type; its size is platform dependent
(the compiler chooses the processor's fastest floating point type).
This type should be used in general.
floatXX
an implementation may define additional floating point types of XX bits using
this naming scheme (example: float64 is a 64 bit wide float). The current
implementation supports ``float32`` and ``float64``. Literals of these types
have the suffix 'fXX.
Automatic type conversion in expressions with different kinds
of floating point types is performed: See `Convertible relation`_ for further
details. Arithmetic performed on floating point types follows the IEEE
standard. Integer types are not converted to floating point types automatically
and vice versa.
The IEEE standard defines five types of floating-point exceptions:
* Invalid: operations with mathematically invalid operands,
for example 0.0/0.0, sqrt(-1.0), and log(-37.8).
* Division by zero: divisor is zero and dividend is a finite nonzero number,
for example 1.0/0.0.
* Overflow: operation produces a result that exceeds the range of the exponent,
for example MAXDOUBLE+0.0000000000001e308.
* Underflow: operation produces a result that is too small to be represented
as a normal number, for example, MINDOUBLE * MINDOUBLE.
* Inexact: operation produces a result that cannot be represented with infinite
precision, for example, 2.0 / 3.0, log(1.1) and 0.1 in input.
The IEEE exceptions are either ignored at runtime or mapped to the
Nimrod exceptions: `EFloatInvalidOp`:idx, `EFloatDivByZero`:idx:,
`EFloatOverflow`:idx:, `EFloatUnderflow`:idx:, and `EFloatInexact`:idx:\.
These exceptions inherit from the `EFloatingPoint`:idx: base class.
Nimrod provides the pragmas `NaNChecks`:idx and `InfChecks`:idx:\ to control
whether the IEEE exceptions are ignored or trap a Nimrod exception:
.. code-block:: nimrod
{.NanChecks: on, InfChecks: on.}
var a = 1.0
var b = 0.0
echo b / b # raises EFloatInvalidOp
echo a / b # raises EFloatOverflow
In the current implementation ``EFloatDivByZero`` and ``EFloatInexact`` are
never raised. ``EFloatOverflow`` is raised instead of ``EFloatDivByZero``.
There is also a `floatChecks`:idx: pragma that is a short-cut for the
combination of ``NaNChecks`` and ``InfChecks`` pragmas. ``floatChecks`` are
turned off as default.
The only operations that are affected by the ``floatChecks`` pragma are
the ``+``, ``-``, ``*``, ``/`` operators for floating point types.
Boolean type
~~~~~~~~~~~~
The `boolean`:idx: type is named ``bool`` in Nimrod and can be one of the two
pre-defined values ``true`` and ``false``. Conditions in while,
if, elif, when statements need to be of type bool.
This condition holds::
ord(false) == 0 and ord(true) == 1
The operators ``not, and, or, xor, <, <=, >, >=, !=, ==`` are defined
for the bool type. The ``and`` and ``or`` operators perform short-cut
evaluation. Example:
.. code-block:: nimrod
while p != nil and p.name != "xyz":
# p.name is not evaluated if p == nil
p = p.next
The size of the bool type is one byte.
Character type
~~~~~~~~~~~~~~
The `character type`:idx: is named ``char`` in Nimrod. Its size is one byte.
Thus it cannot represent an UTF-8 character, but a part of it.
The reason for this is efficiency: for the overwhelming majority of use-cases,
the resulting programs will still handle UTF-8 properly as UTF-8 was specially
designed for this.
Another reason is that Nimrod can support ``array[char, int]`` or
``set[char]`` efficiently as many algorithms rely on this feature. The
`TRune` type is used for Unicode characters, it can represent any Unicode
character. ``TRune`` is declared in the ``unicode`` module.
Enumeration types
~~~~~~~~~~~~~~~~~
`Enumeration`:idx: types define a new type whose values consist of the ones
specified. The values are ordered. Example:
.. code-block:: nimrod
type
TDirection = enum
north, east, south, west
Now the following holds::
ord(north) == 0
ord(east) == 1
ord(south) == 2
ord(west) == 3
Thus, north < east < south < west. The comparison operators can be used
with enumeration types.
For better interfacing to other programming languages, the fields of enum
types can be assigned an explicit ordinal value. However, the ordinal values
have to be in ascending order. A field whose ordinal value is not
explicitly given is assigned the value of the previous field + 1.
An explicit ordered enum can have *holes*:
.. code-block:: nimrod
type
TTokenType = enum
a = 2, b = 4, c = 89 # holes are valid
However, it is then not an ordinal anymore, so it is not possible to use these
enums as an index type for arrays. The procedures ``inc``, ``dec``, ``succ``
and ``pred`` are not available for them either.
Subrange types
~~~~~~~~~~~~~~
A `subrange`:idx: type is a range of values from an ordinal type (the base
type). To define a subrange type, one must specify it's limiting values: the
lowest and highest value of the type:
.. code-block:: nimrod
type
TSubrange = range[0..5]
``TSubrange`` is a subrange of an integer which can only hold the values 0
to 5. Assigning any other value to a variable of type ``TSubrange`` is a
checked runtime error (or static error if it can be statically
determined). Assignments from the base type to one of its subrange types
(and vice versa) are allowed.
A subrange type has the same size as its base type (``int`` in the example).
String type
~~~~~~~~~~~
All string literals are of the type `string`:idx:. A string in Nimrod is very
similar to a sequence of characters. However, strings in Nimrod are both
zero-terminated and have a length field. One can retrieve the length with the
builtin ``len`` procedure; the length never counts the terminating zero.
The assignment operator for strings always copies the string.
The ``&`` operator concatenates strings.
Strings are compared by their lexicographical order. All comparison operators
are available. Strings can be indexed like arrays (lower bound is 0). Unlike
arrays, they can be used in case statements:
.. code-block:: nimrod
case paramStr(i)
of "-v": incl(options, optVerbose)
of "-h", "-?": incl(options, optHelp)
else: write(stdout, "invalid command line option!\n")
Per convention, all strings are UTF-8 strings, but this is not enforced. For
example, when reading strings from binary files, they are merely a sequence of
bytes. The index operation ``s[i]`` means the i-th *char* of ``s``, not the
i-th *unichar*. The iterator ``runes`` from the ``unicode``
module can be used for iteration over all Unicode characters.
Structured types
~~~~~~~~~~~~~~~~
A variable of a `structured type`:idx: can hold multiple values at the same
time. Structured types can be nested to unlimited levels. Arrays, sequences,
tuples, objects and sets belong to the structured types.
Array and sequence types
~~~~~~~~~~~~~~~~~~~~~~~~
`Arrays`:idx: are a homogeneous type, meaning that each element in the array
has the same type. Arrays always have a fixed length which is specified at
compile time (except for open arrays). They can be indexed by any ordinal type.
A parameter ``A`` may be an *open array*, in which case it is indexed by
integers from 0 to ``len(A)-1``. An array expression may be constructed by the
array constructor ``[]``.
`Sequences`:idx: are similar to arrays but of dynamic length which may change
during runtime (like strings). A sequence ``S`` is always indexed by integers
from 0 to ``len(S)-1`` and its bounds are checked. Sequences can be
constructed by the array constructor ``[]`` in conjunction with the array to
sequence operator ``@``. Another way to allocate space for a sequence is to
call the built-in ``newSeq`` procedure.
A sequence may be passed to a parameter that is of type *open array*.
Example:
.. code-block:: nimrod
type
TIntArray = array[0..5, int] # an array that is indexed with 0..5
TIntSeq = seq[int] # a sequence of integers
var
x: TIntArray
y: TIntSeq
x = [1, 2, 3, 4, 5, 6] # [] is the array constructor
y = @[1, 2, 3, 4, 5, 6] # the @ turns the array into a sequence
The lower bound of an array or sequence may be received by the built-in proc
``low()``, the higher bound by ``high()``. The length may be
received by ``len()``. ``low()`` for a sequence or an open array always returns
0, as this is the first valid index.
One can append elements to a sequence with the ``add()`` proc or the ``&``
operator, and remove (and get) the last element of a sequence with the
``pop()`` proc.
The notation ``x[i]`` can be used to access the i-th element of ``x``.
Arrays are always bounds checked (at compile-time or at runtime). These
checks can be disabled via pragmas or invoking the compiler with the
``--boundChecks:off`` command line switch.
An open array is also a means to implement passing a variable number of
arguments to a procedure. The compiler converts the list of arguments
to an array automatically:
.. code-block:: nimrod
proc myWriteln(f: TFile, a: openarray[string]) =
for s in items(a):
write(f, s)
write(f, "\n")
myWriteln(stdout, "abc", "def", "xyz")
# is transformed by the compiler to:
myWriteln(stdout, ["abc", "def", "xyz"])
This transformation is only done if the openarray parameter is the
last parameter in the procedure header. The current implementation does not
support nested open arrays.
Tuples and object types
~~~~~~~~~~~~~~~~~~~~~~~
A variable of a `tuple`:idx: or `object`:idx: type is a heterogeneous storage
container.
A tuple or object defines various named *fields* of a type. A tuple also
defines an *order* of the fields. Tuples are meant for heterogeneous storage
types with no overhead and few abstraction possibilities. The constructor ``()``
can be used to construct tuples. The order of the fields in the constructor
must match the order of the tuple's definition. Different tuple-types are
*equivalent* if they specify the same fields of the same type in the same
order.
The assignment operator for tuples copies each component.
The default assignment operator for objects copies each component. Overloading
of the assignment operator for objects is not possible, but this may change in
future versions of the compiler.
.. code-block:: nimrod
type
TPerson = tuple[name: string, age: int] # type representing a person
# a person consists of a name
# and an age
var
person: TPerson
person = (name: "Peter", age: 30)
# the same, but less readable:
person = ("Peter", 30)
The implementation aligns the fields for best access performance. The alignment
is compatible with the way the C compiler does it.
Objects provide many features that tuples do not. Object provide inheritance
and information hiding. Objects have access to their type at runtime, so that
the ``is`` operator can be used to determine the object's type.
.. code-block:: nimrod
type
TPerson = object
name*: string # the * means that `name` is accessible from other modules
age: int # no * means that the field is hidden
TStudent = object of TPerson # a student is a person
id: int # with an id field
var
student: TStudent
person: TPerson
assert(student is TStudent) # is true
Object fields that should be visible from outside the defining module, have to
be marked by ``*``. In contrast to tuples, different object types are
never *equivalent*.
Object variants
~~~~~~~~~~~~~~~
Often an object hierarchy is overkill in certain situations where simple
`variant`:idx: types are needed.
An example:
.. code-block:: nimrod
# This is an example how an abstract syntax tree could be modelled in Nimrod
type
TNodeKind = enum # the different node types
nkInt, # a leaf with an integer value
nkFloat, # a leaf with a float value
nkString, # a leaf with a string value
nkAdd, # an addition
nkSub, # a subtraction
nkIf # an if statement
PNode = ref TNode
TNode = object
case kind: TNodeKind # the ``kind`` field is the discriminator
of nkInt: intVal: int
of nkFloat: floatVal: float
of nkString: strVal: string
of nkAdd, nkSub:
leftOp, rightOp: PNode
of nkIf:
condition, thenPart, elsePart: PNode
var
n: PNode
new(n) # creates a new node
n.kind = nkFloat
n.floatVal = 0.0 # valid, because ``n.kind==nkFloat``, so that it fits
# the following statement raises an `EInvalidField` exception, because
# n.kind's value does not fit:
n.strVal = ""
As can been seen from the example, an advantage to an object hierarchy is that
no casting between different object types is needed. Yet, access to invalid
object fields raises an exception.
Set type
~~~~~~~~
The `set type`:idx: models the mathematical notion of a set. The set's
basetype can only be an ordinal type. The reason is that sets are implemented
as high performance bit vectors.
Sets can be constructed via the set constructor: ``{}`` is the empty set. The
empty set is type compatible with any special set type. The constructor
can also be used to include elements (and ranges of elements) in the set:
.. code-block:: nimrod
{'a'..'z', '0'..'9'} # This constructs a set that contains the
# letters from 'a' to 'z' and the digits
# from '0' to '9'
These operations are supported by sets:
================== ========================================================
operation meaning
================== ========================================================
``A + B`` union of two sets
``A * B`` intersection of two sets
``A - B`` difference of two sets (A without B's elements)
``A == B`` set equality
``A <= B`` subset relation (A is subset of B or equal to B)
``A < B`` strong subset relation (A is a real subset of B)
``e in A`` set membership (A contains element e)
``A -+- B`` symmetric set difference (= (A - B) + (B - A))
``card(A)`` the cardinality of A (number of elements in A)
``incl(A, elem)`` same as A = A + {elem}
``excl(A, elem)`` same as A = A - {elem}
================== ========================================================
Reference and pointer types
~~~~~~~~~~~~~~~~~~~~~~~~~~~
References (similar to `pointers`:idx: in other programming languages) are a
way to introduce many-to-one relationships. This means different references can
point to and modify the same location in memory.
Nimrod distinguishes between `traced`:idx: and `untraced`:idx: references.
Untraced references are also called *pointers*. Traced references point to
objects of a garbage collected heap, untraced references point to
manually allocated objects or to objects somewhere else in memory. Thus
untraced references are *unsafe*. However for certain low-level operations
(accessing the hardware) untraced references are unavoidable.
Traced references are declared with the **ref** keyword, untraced references
are declared with the **ptr** keyword.
The ``^`` operator can be used to derefer a reference, the ``addr`` procedure
returns the address of an item. An address is always an untraced reference.
Thus the usage of ``addr`` is an *unsafe* feature.
The ``.`` (access a tuple/object field operator)
and ``[]`` (array/string/sequence index operator) operators perform implicit
dereferencing operations for reference types:
.. code-block:: nimrod
type
PNode = ref TNode
TNode = object
le, ri: PNode
data: int
var
n: PNode
new(n)
n.data = 9 # no need to write n^ .data
To allocate a new traced object, the built-in procedure ``new`` has to be used.
To deal with untraced memory, the procedures ``alloc``, ``dealloc`` and
``realloc`` can be used. The documentation of the system module contains
further information.
If a reference points to *nothing*, it has the value ``nil``.
Special care has to be taken if an untraced object contains traced objects like
traced references, strings or sequences: in order to free everything properly,
the built-in procedure ``GCunref`` has to be called before freeing the
untraced memory manually!
.. XXX finalizers for traced objects
Procedural type
~~~~~~~~~~~~~~~
A `procedural type`:idx: is internally a pointer to a procedure. ``nil`` is
an allowed value for variables of a procedural type. Nimrod uses procedural
types to achieve `functional`:idx: programming techniques.
Example:
.. code-block:: nimrod
type
TCallback = proc (x: int) {.cdecl.}
proc printItem(x: Int) = ...
proc forEach(c: TCallback) =
...
forEach(printItem) # this will NOT work because calling conventions differ
A subtle issue with procedural types is that the calling convention of the
procedure influences the type compatibility: procedural types are only
compatible if they have the same calling convention.
Nimrod supports these `calling conventions`:idx:, which are all incompatible to
each other:
`stdcall`:idx:
This the stdcall convention as specified by Microsoft. The generated C
procedure is declared with the ``__stdcall`` keyword.
`cdecl`:idx:
The cdecl convention means that a procedure shall use the same convention
as the C compiler. Under windows the generated C procedure is declared with
the ``__cdecl`` keyword.
`safecall`:idx:
This is the safecall convention as specified by Microsoft. The generated C
procedure is declared with the ``__safecall`` keyword. The word *safe*
refers to the fact that all hardware registers shall be pushed to the
hardware stack.
`inline`:idx:
The inline convention means the the caller should not call the procedure,
but inline its code directly. Note that Nimrod does not inline, but leaves
this to the C compiler. Thus it generates ``__inline`` procedures. This is
only a hint for the compiler: it may completely ignore it and
it may inline procedures that are not marked as ``inline``.
`fastcall`:idx:
Fastcall means different things to different C compilers. One gets whatever
the C ``__fastcall`` means.
`nimcall`:idx:
Nimcall is the default convention used for Nimrod procedures. It is the
same as ``fastcall``, but only for C compilers that support ``fastcall``.
`closure`:idx:
indicates that the procedure expects a context, a closure that needs
to be passed to the procedure. The calling convention ``nimcall`` is
compatible to ``closure``.