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

manual: minor improvements (#17677)

Browse source 
* manual: minor improvements

* Update doc/manual.rst

Co-authored-by: konsumlamm <44230978+konsumlamm@users.noreply.github.com>
This commit is contained in:
Andreas Rumpf 2021-04-08 17:46:51 +02:00 • committed by GitHub
commit 4d3f9d3536
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

94
doc/manual.rst
View file

@ -222,7 +222,7 @@ comment:
`Documentation comments`:idx: are comments that start with two `##`. `Documentation comments`:idx: are comments that start with two `##`.
Documentation comments are tokens; they are only allowed at certain places in Documentation comments are tokens; they are only allowed at certain places in
the input file as they belong to the syntax tree! the input file as they belong to the syntax tree.
Multiline comments Multiline comments
@ -315,8 +315,8 @@ it was not case-sensitive and underscores were ignored and there was not even a
distinction between `foo` and `Foo`. distinction between `foo` and `Foo`.
Stropping Keywords as identifiers
--------- -----------------------
If a keyword is enclosed in backticks it loses its keyword property and becomes an ordinary identifier. If a keyword is enclosed in backticks it loses its keyword property and becomes an ordinary identifier.
@ -326,12 +326,12 @@ Examples
var `var` = "Hello Stropping" var `var` = "Hello Stropping"
.. code-block:: nim .. code-block:: nim
type Type = object type Obj = object
`int`: int `type`: int
let `object` = Type(`int`: 9) let `object` = Obj(`type`: 9)
assert `object` is Type assert `object` is Obj
assert `object`.`int` == 9 assert `object`.`type` == 9
var `var` = 42 var `var` = 42
let `let` = 8 let `let` = 8
@ -442,7 +442,7 @@ Terminal symbols in the grammar: `GENERALIZED_STR_LIT`,
The construct `identifier"string literal"` (without whitespace between the The construct `identifier"string literal"` (without whitespace between the
identifier and the opening quotation mark) is a identifier and the opening quotation mark) is a
generalized raw string literal. It is a shortcut for the construct generalized raw string literal. It is a shortcut for the construct
`identifier(r"string literal")`, so it denotes a procedure call with a `identifier(r"string literal")`, so it denotes a routine call with a
raw string literal as its only argument. Generalized raw string literals raw string literal as its only argument. Generalized raw string literals
are especially convenient for embedding mini languages directly into Nim are especially convenient for embedding mini languages directly into Nim
(for example regular expressions). (for example regular expressions).
@ -457,8 +457,8 @@ Character literals
Character literals are enclosed in single quotes `''` and can contain the Character literals are enclosed in single quotes `''` and can contain the
same escape sequences as strings - with one exception: the platform same escape sequences as strings - with one exception: the platform
dependent `newline`:idx: (``\p``) dependent `newline`:idx: (``\p``)
is not allowed as it may be wider than one character (often it is the pair is not allowed as it may be wider than one character (it can be the pair
CR/LF for example). Here are the valid `escape sequences`:idx: for character CR/LF). Here are the valid `escape sequences`:idx: for character
literals: literals:
================== =================================================== ================== ===================================================
@ -482,19 +482,21 @@ literals:
exactly two hex digits are allowed exactly two hex digits are allowed
================== =================================================== ================== ===================================================
A character is not a Unicode character but a single byte. The reason for this A character is not a Unicode character but a single byte.
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 Rationale: It enables the efficient support of `array[char, int]` or
this. Another reason is that Nim can thus support `array[char, int]` or `set[char]`.
`set[char]` efficiently as many algorithms rely on this feature. The `Rune`
type is used for Unicode characters, it can represent any Unicode character. The `Rune` type can represent any Unicode character.
`Rune` is declared in the `unicode module <unicode.html>`_. `Rune` is declared in the `unicode module <unicode.html>`_.
A character literal that does not end in ``'`` is interpreted as ``'`` if there A character literal that does not end in ``'`` is interpreted as ``'`` if there
is a preceeding backtick token. There must be no whitespace between the preceeding is a preceeding backtick token. There must be no whitespace between the preceeding
backtick token and the character literal. This special rule ensures that a declaration backtick token and the character literal. This special case ensures that a declaration
like ``proc `'customLiteral`(s: string)`` is valid. See also like ``proc `'customLiteral`(s: string)`` is valid. ``proc `'customLiteral`(s: string)``
`Custom Numeric Literals <#custom-numeric-literals>`_. is the same as ``proc `'\''customLiteral`(s: string)``.
See also `Custom Numeric Literals <#custom-numeric-literals>`_.
Numeric Literals Numeric Literals
@ -908,37 +910,37 @@ constant expressions that may be surprising to those coming from other
statically typed languages. For example, the following code echoes the beginning statically typed languages. For example, the following code echoes the beginning
of the Fibonacci series **at compile-time**. (This is a demonstration of of the Fibonacci series **at compile-time**. (This is a demonstration of
flexibility in defining constants, not a recommended style for solving this flexibility in defining constants, not a recommended style for solving this
problem!) problem.)
.. code-block:: nim .. code-block:: nim
:test: "nim c $1" :test: "nim c $1"
import std/strformat import std/strformat
var fib_n {.compileTime.}: int var fibN {.compileTime.}: int
var fib_prev {.compileTime.}: int var fibPrev {.compileTime.}: int
var fib_prev_prev {.compileTime.}: int var fibPrevPrev {.compileTime.}: int
proc next_fib(): int = proc nextFib(): int =
result = if fib_n < 2: result = if fibN < 2:
fib_n fibN
else: else:
fib_prev_prev + fib_prev fibPrevPrev + fibPrev
inc(fib_n) inc(fibN)
fib_prev_prev = fib_prev fibPrevPrev = fibPrev
fib_prev = result fibPrev = result
const f0 = next_fib() const f0 = nextFib()
const f1 = next_fib() const f1 = nextFib()
const display_fib = block: const displayFib = block:
const f2 = next_fib() const f2 = nextFib()
var result = fmt"Fibonacci sequence: {f0}, {f1}, {f2}" var result = fmt"Fibonacci sequence: {f0}, {f1}, {f2}"
for i in 3..12: for i in 3..12:
add(result, fmt", {next_fib()}") add(result, fmt", {nextFib()}")
result result
static: static:
echo display_fib echo displayFib
Restrictions on Compile-Time Execution Restrictions on Compile-Time Execution
@ -1013,7 +1015,9 @@ intXX
Literals of these types have the suffix 'iXX. Literals of these types have the suffix 'iXX.
`uint` `uint`
the generic `unsigned integer`:idx: type; its size is platform-dependent and has the same size as a pointer. An integer literal with the type suffix `'u` is of this type. the generic `unsigned integer`:idx: type; its size is platform-dependent and
has the same size as a pointer. An integer literal with the type
suffix `'u` is of this type.
uintXX uintXX
additional unsigned integer types of XX bits use this naming scheme additional unsigned integer types of XX bits use this naming scheme
@ -1199,12 +1203,8 @@ Character type
-------------- --------------
The character type is named `char` in Nim. Its size is one byte. The character type is named `char` in Nim. Its size is one byte.
Thus it cannot represent a UTF-8 character, but a part of it. Thus it cannot represent a 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 especially The `Rune` type is used for Unicode characters, it can represent any Unicode
designed for this.
Another reason is that Nim can support `array[char, int]` or
`set[char]` efficiently as many algorithms rely on this feature. The
`Rune` type is used for Unicode characters, it can represent any Unicode
character. `Rune` is declared in the `unicode module <unicode.html>`_. character. `Rune` is declared in the `unicode module <unicode.html>`_.
@ -1232,7 +1232,7 @@ Now the following holds::
# Also allowed: # Also allowed:
ord(Direction.west) == 3 ord(Direction.west) == 3
Thus, north < east < south < west. The comparison operators can be used The implied order is: north < east < south < west. The comparison operators can be used
with enumeration types. Instead of `north` etc, the enum value can also with enumeration types. Instead of `north` etc, the enum value can also
be qualified with the enum type that it resides in, `Direction.north`. be qualified with the enum type that it resides in, `Direction.north`.
@ -1248,7 +1248,7 @@ An explicit ordered enum can have *holes*:
TokenType = enum TokenType = enum
a = 2, b = 4, c = 89 # holes are valid a = 2, b = 4, c = 89 # holes are valid
However, it is then not ordinal anymore, so it is not possible to use these However, it is then not ordinal anymore, so it is impossible to use these
enums as an index type for arrays. The procedures `inc`, `dec`, `succ` enums as an index type for arrays. The procedures `inc`, `dec`, `succ`
and `pred` are not available for them either. and `pred` are not available for them either.
@ -7885,4 +7885,4 @@ Threads and exceptions
The interaction between threads and exceptions is simple: A *handled* exception The interaction between threads and exceptions is simple: A *handled* exception
in one thread cannot affect any other thread. However, an *unhandled* exception in one thread cannot affect any other thread. However, an *unhandled* exception
in one thread terminates the whole *process*! in one thread terminates the whole *process*.