jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Finished this terminology update.

Browse source
This commit is contained in:
deansher 2019-01-29 19:43:01 -05:00
commit 7295468516
1 changed files with 48 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

88
doc/manual.rst
View file

@ -46,8 +46,8 @@ and ``a ^* b`` is short for ``(a (b a)*)?``. Example::
arrayConstructor = '[' expr ^* ',' ']' arrayConstructor = '[' expr ^* ',' ']'
Other parts of Nim - like scoping rules or execution semantics are only Other parts of Nim, like scoping rules or execution semantics, are
described in the, more easily comprehensible, informal manner for now. described informally.
@ -76,17 +76,19 @@ the context.
A Nim `program`:idx: consists of one or more text `source files`:idx: containing A Nim `program`:idx: consists of one or more text `source files`:idx: containing
Nim code. It is processed by a Nim `compiler`:idx: into an `executable`:idx:. Nim code. It is processed by a Nim `compiler`:idx: into an `executable`:idx:.
The nature of this executable depends on the compiler implementation; it may, The nature of this executable depends on the compiler implementation; it may,
for example, be a native binary or JavaScript source code. In addition to the for example, be a native binary or JavaScript source code.
code that is compiled into the executable and executed at `runtime`:idx:,
a Nim program can contain Nim code that will be executed at `compile time`:idx:. In a typical Nim program, most of the code is compiled into the executable for
This can include constant expressions, macro definitions, and Nim procedures execution at `runtime`:idx:. However, some of the code may be executed at
used by macro definitions. Most of the Nim language is supported at `compile time`:idx:. This can include constant expressions, macro definitions,
compile time, but there are some restrictions -- see `Restrictions on and Nim procedures used by macro definitions. Most of the Nim language is
Compile-Time Execution <restrictions-on-compile-time-execution>`_ for details. supported at compile time, but there are some restrictions -- see `Restrictions
on Compile-Time Execution <#restrictions-on-compileminustime-execution>`_ for
details.
The compiler parses Nim source code into an internal data structure called the The compiler parses Nim source code into an internal data structure called the
`abstract syntax tree`:idx: (`AST`:idx). Then, before executing the code or `abstract syntax tree`:idx: (`AST`:idx:). Then, before executing the code or
processing it into the executable, it transforms the AST through `semantic compiling it into the executable, it transforms the AST through `semantic
analysis`:idx:. This adds semantic information such as expression types, analysis`:idx:. This adds semantic information such as expression types,
identifier meanings, and in some cases expression values. An error detected identifier meanings, and in some cases expression values. An error detected
during semantic analysis is called a `static error`:idx:. Errors described in during semantic analysis is called a `static error`:idx:. Errors described in
@ -128,11 +130,9 @@ analysis and compile-time code execution.
It is mostly accurate to picture semantic analysis proceeding top to bottom and It is mostly accurate to picture semantic analysis proceeding top to bottom and
left to right in the source code, with compile-time code execution interleaved left to right in the source code, with compile-time code execution interleaved
when necessary to compute values that are required for subsequent semantic when necessary to compute values that are required for subsequent semantic
analysis. We saw just above that this interleaving is necessary for handling analysis. We will see much later in this document that macro invocation not only
constant expressions. We will see much later in this document that macro requires this interleaving, but also creates a situation where semantic analyis
invocation not only requires this interleaving, but also creates a situation does not entirely proceed top to bottom and left to right.
where semantic analyis does not entirely proceed top to bottom and left to
right.
Lexical Analysis Lexical Analysis
@ -709,8 +709,8 @@ Rationale: Consistency with overloaded assignment or assignment-like operations,
Constants and Constant Expressions Constants and Constant Expressions
================================== ==================================
A `constant`:idx: is a symbol that is bound to the value of a `constant A `constant`:idx: is a symbol that is bound to the value of a constant
expression`. This is an expression whose value can be computed during expression. This is an expression whose value can be computed during
semantic analysis of the code in which it appears. However, constant semantic analysis of the code in which it appears. However, constant
expressions are not limited to the capabilities of semantic analysis; they expressions are not limited to the capabilities of semantic analysis; they
can use all Nim language features that are supported for can use all Nim language features that are supported for
@ -718,9 +718,9 @@ compile-time execution. Compile-time execution is interleaved with semantic
analysis as necessary. A constant's value cannot change after it is first analysis as necessary. A constant's value cannot change after it is first
computed. computed.
Constant expressions can only depend on the following values and operations Constant expressions are restricted to depend only on the following categories
that are either built into the language or available during compilation of of values and operations, because these are either built into the language or
the constant expression: declared and evaluated before semantic analysis of the constant expression:
* literals * literals
* built-in operators * built-in operators
@ -730,8 +730,12 @@ the constant expression:
possibly modifying compile-time variables possibly modifying compile-time variables
A constant expression can contain code blocks that may internally use all Nim A constant expression can contain code blocks that may internally use all Nim
features supported at compile time (as detailed in the next section below), features supported at compile time (as detailed in the next section below).
but that cannot refer to any external values beyond those listed above. Within such a code block, it is possible to declare variables and then later
read and update them, or declare variables and pass them to procedures that
modify them. However, the code in such a block must still adhere to the
retrictions listed above for referencing values and operations outside the
block.
The ability to access and modify compile-time variables adds flexibility to The ability to access and modify compile-time variables adds flexibility to
constant expressions that may be surprising to those coming from other constant expressions that may be surprising to those coming from other
@ -774,7 +778,7 @@ problem!)
Restrictions on Compile-Time Execution Restrictions on Compile-Time Execution
====================================== ======================================
Nim code that will be executed at compile-time cannot use the following Nim code that will be executed at compile time cannot use the following
language features: language features:
* methods * methods
@ -910,8 +914,8 @@ For further details, see `Convertible relation
Subrange types Subrange types
-------------- --------------
A subrange type is a range of values from an ordinal or floating point type (the base A subrange type is a range of values from an ordinal or floating point type (the base
type). To define a subrange type, one must specify it's limiting values: the type). To define a subrange type, one must specify its limiting values -- the
lowest and highest value of the type: lowest and highest value of the type. For example:
.. code-block:: nim .. code-block:: nim
type type
@ -1543,8 +1547,8 @@ contexts (``var/ref/ptr IncompleteObject``) in general since the compiler does
not yet know the size of the object. To complete an incomplete object not yet know the size of the object. To complete an incomplete object
the ``package`` pragma has to be used. ``package`` implies ``byref``. the ``package`` pragma has to be used. ``package`` implies ``byref``.
As long as a type ``T`` is incomplete ``sizeof(T)`` or "execution-time type As long as a type ``T`` is incomplete, neither ``sizeof(T)`` nor execution-time
information" for ``T`` is not available. type information for ``T`` is available.
Example: Example:
@ -2363,6 +2367,10 @@ In a call ``p(args)`` the routine ``p`` that matches best is selected. If
multiple routines match equally well, the ambiguity is reported during multiple routines match equally well, the ambiguity is reported during
semantic analysis. semantic analysis.
Every arg in args needs to match. There are multiple different categories how an
argument can match. Let ``f`` be the formal parameter's type and ``a`` the type
of the argument.
1. Exact match: ``a`` and ``f`` are of the same type. 1. Exact match: ``a`` and ``f`` are of the same type.
2. Literal match: ``a`` is an integer literal of value ``v`` 2. Literal match: ``a`` is an integer literal of value ``v``
and ``f`` is a signed or unsigned integer type and ``v`` is in ``f``'s and ``f`` is a signed or unsigned integer type and ``v`` is in ``f``'s
@ -2764,7 +2772,7 @@ Even some code that has side effects is permitted in a static block:
There are limitations on what Nim code can be executed at compile time; There are limitations on what Nim code can be executed at compile time;
see `Restrictions on Compile-Time Execution see `Restrictions on Compile-Time Execution
<#restrictions-on-compile-time-execution>`_ for details. <#restrictions-on-compileminustime-execution>`_ for details.
It's a static error if the compiler cannot execute the block at compile It's a static error if the compiler cannot execute the block at compile
time. time.
@ -3767,7 +3775,7 @@ Invocation of a multi-method cannot be ambiguous: collide 2 is preferred over
collide 1 because the resolution works from left to right. collide 1 because the resolution works from left to right.
In the example ``Unit, Thing`` is preferred over ``Thing, Unit``. In the example ``Unit, Thing`` is preferred over ``Thing, Unit``.
**Note**: Compile time execution is not (yet) supported for methods. **Note**: Compile-time execution is not (yet) supported for methods.
Inhibit dynamic method resolution via procCall Inhibit dynamic method resolution via procCall
@ -5443,7 +5451,7 @@ chance to convert it into a sequence.
Macros Macros
====== ======
A macro is a special function that is executed at compile-time. A macro is a special function that is executed at compile time.
Normally the input for a macro is an abstract syntax Normally the input for a macro is an abstract syntax
tree (AST) of the code that is passed to it. The macro can then do tree (AST) of the code that is passed to it. The macro can then do
transformations on it and return the transformed AST. The transformations on it and return the transformed AST. The
@ -5452,8 +5460,8 @@ invocation would have been replaced by its result in the source
code. This can be used to implement `domain specific code. This can be used to implement `domain specific
languages`:idx:. languages`:idx:.
Macro invocation leads to a case where semantic analyis does **not** entirely Macro invocation is a case where semantic analyis does **not** entirely proceed
proceed top to bottom and left to right. The compiler must top to bottom and left to right. The compiler must
* perform semantic analysis through the end of the macro invocation, * perform semantic analysis through the end of the macro invocation,
* execute the macro body, * execute the macro body,
@ -6869,7 +6877,7 @@ pragma block can be used:
compileTime pragma compileTime pragma
------------------ ------------------
The ``compileTime`` pragma is used to mark a proc or variable to be used only The ``compileTime`` pragma is used to mark a proc or variable to be used only
during compile-time execution. No code will be generated for it. Compile time during compile-time execution. No code will be generated for it. Compile-time
procs are useful as helpers for macros. Since version 0.12.0 of the language, a procs are useful as helpers for macros. Since version 0.12.0 of the language, a
proc that uses ``system.NimNode`` within its parameter types is implicitly proc that uses ``system.NimNode`` within its parameter types is implicitly
declared ``compileTime``: declared ``compileTime``:
@ -8331,11 +8339,11 @@ Example:
echo formatFloat(pi(5000)) echo formatFloat(pi(5000))
The parallel statement is the preferred mechanism to introduce parallelism The parallel statement is the preferred mechanism to introduce parallelism in a
in a Nim program. A subset of the Nim language is valid within a Nim program. A subset of the Nim language is valid within a ``parallel``
``parallel`` section. This subset is checked to be free of data races during section. This subset is checked during semantic analysis to be free of data
semantic analysis. A sophisticated `disjoint checker`:idx: ensures that no data races. A sophisticated `disjoint checker`:idx: ensures that no data races are
races are possible even though shared memory is extensively supported! possible even though shared memory is extensively supported!
The subset is in fact the full language with the following The subset is in fact the full language with the following
restrictions / changes: restrictions / changes:
@ -8368,7 +8376,7 @@ pragmas:
2) Every access of a guarded memory location needs to happen in an 2) Every access of a guarded memory location needs to happen in an
appropriate `locks`:idx: statement. appropriate `locks`:idx: statement.
3) Locks and routines can be annotated with `lock levels`:idx: to allow 3) Locks and routines can be annotated with `lock levels`:idx: to allow
potential deadlocks to be detected during static analysis. potential deadlocks to be detected during semantic analysis.
Guards and the locks section Guards and the locks section