Markdown indented code blocks (#20473)
* Implement Markdown indented code blocks
Additional indentation of 4 spaces makes a block an "indented code block"
(monospaced text without syntax highlighting).
Also `::` RST syntax for code blocks is disabled.
So instead of
```rst
see::
Some code
```
the code block should be written as
```markdown
see:
Some code
```
* Migrate RST literal blocks :: to Markdown's ones
This commit is contained in:
Andrey Makarov
GitHub
parent
594e93a66b
commit
6505bd347d
33 changed files with 697 additions and 603 deletions
146
doc/manual.md
146
doc/manual.md
|
|
@ -47,16 +47,16 @@ is not ambiguous.
|
|||
|
||||
Non-terminals start with a lowercase letter, abstract terminal symbols are in
|
||||
UPPERCASE. Verbatim terminal symbols (including keywords) are quoted
|
||||
with `'`. An example::
|
||||
with `'`. An example:
|
||||
|
||||
ifStmt = 'if' expr ':' stmts ('elif' expr ':' stmts)* ('else' stmts)?
|
||||
ifStmt = 'if' expr ':' stmts ('elif' expr ':' stmts)* ('else' stmts)?
|
||||
|
||||
The binary `^*` operator is used as a shorthand for 0 or more occurrences
|
||||
separated by its second argument; likewise `^+` means 1 or more
|
||||
occurrences: `a ^+ b` is short for `a (b a)*`
|
||||
and `a ^* b` is short for `(a (b a)*)?`. Example::
|
||||
and `a ^* b` is short for `(a (b a)*)?`. Example:
|
||||
|
||||
arrayConstructor = '[' expr ^* ',' ']'
|
||||
arrayConstructor = '[' expr ^* ',' ']'
|
||||
|
||||
Other parts of Nim, like scoping rules or runtime semantics, are
|
||||
described informally.
|
||||
|
|
@ -190,16 +190,16 @@ is another pseudo terminal that describes the *action* of popping a value
|
|||
from the stack, `IND{>}` then implies to push onto the stack.
|
||||
|
||||
With this notation we can now easily define the core of the grammar: A block of
|
||||
statements (simplified example)::
|
||||
statements (simplified example):
|
||||
|
||||
ifStmt = 'if' expr ':' stmt
|
||||
(IND{=} 'elif' expr ':' stmt)*
|
||||
(IND{=} 'else' ':' stmt)?
|
||||
ifStmt = 'if' expr ':' stmt
|
||||
(IND{=} 'elif' expr ':' stmt)*
|
||||
(IND{=} 'else' ':' stmt)?
|
||||
|
||||
simpleStmt = ifStmt / ...
|
||||
simpleStmt = ifStmt / ...
|
||||
|
||||
stmt = IND{>} stmt ^+ IND{=} DED # list of statements
|
||||
/ simpleStmt # or a simple statement
|
||||
stmt = IND{>} stmt ^+ IND{=} DED # list of statements
|
||||
/ simpleStmt # or a simple statement
|
||||
|
||||
|
||||
|
||||
|
|
@ -409,9 +409,9 @@ ending of the string literal is defined by the pattern `"""[^"]`, so this:
|
|||
""""long string within quotes""""
|
||||
```
|
||||
|
||||
Produces::
|
||||
Produces:
|
||||
|
||||
"long string within quotes"
|
||||
"long string within quotes"
|
||||
|
||||
|
||||
Raw string literals
|
||||
|
|
@ -434,9 +434,9 @@ To produce a single `"` within a raw string literal, it has to be doubled:
|
|||
r"a""b"
|
||||
```
|
||||
|
||||
Produces::
|
||||
Produces:
|
||||
|
||||
a"b
|
||||
a"b
|
||||
|
||||
`r""""` is not possible with this notation, because the three leading
|
||||
quotes introduce a triple quoted string literal. `r"""` is the same
|
||||
|
|
@ -513,46 +513,46 @@ See also [custom numeric literals].
|
|||
Numeric literals
|
||||
----------------
|
||||
|
||||
Numeric literals have the form::
|
||||
Numeric literals have the form:
|
||||
|
||||
hexdigit = digit | 'A'..'F' | 'a'..'f'
|
||||
octdigit = '0'..'7'
|
||||
bindigit = '0'..'1'
|
||||
unary_minus = '-' # See the section about unary minus
|
||||
HEX_LIT = unary_minus? '0' ('x' | 'X' ) hexdigit ( ['_'] hexdigit )*
|
||||
DEC_LIT = unary_minus? digit ( ['_'] digit )*
|
||||
OCT_LIT = unary_minus? '0' 'o' octdigit ( ['_'] octdigit )*
|
||||
BIN_LIT = unary_minus? '0' ('b' | 'B' ) bindigit ( ['_'] bindigit )*
|
||||
hexdigit = digit | 'A'..'F' | 'a'..'f'
|
||||
octdigit = '0'..'7'
|
||||
bindigit = '0'..'1'
|
||||
unary_minus = '-' # See the section about unary minus
|
||||
HEX_LIT = unary_minus? '0' ('x' | 'X' ) hexdigit ( ['_'] hexdigit )*
|
||||
DEC_LIT = unary_minus? digit ( ['_'] digit )*
|
||||
OCT_LIT = unary_minus? '0' 'o' octdigit ( ['_'] octdigit )*
|
||||
BIN_LIT = unary_minus? '0' ('b' | 'B' ) bindigit ( ['_'] bindigit )*
|
||||
|
||||
INT_LIT = HEX_LIT
|
||||
| DEC_LIT
|
||||
| OCT_LIT
|
||||
| BIN_LIT
|
||||
INT_LIT = HEX_LIT
|
||||
| DEC_LIT
|
||||
| OCT_LIT
|
||||
| BIN_LIT
|
||||
|
||||
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'
|
||||
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'
|
||||
|
||||
UINT_LIT = INT_LIT ['\''] ('u' | 'U')
|
||||
UINT8_LIT = INT_LIT ['\''] ('u' | 'U') '8'
|
||||
UINT16_LIT = INT_LIT ['\''] ('u' | 'U') '16'
|
||||
UINT32_LIT = INT_LIT ['\''] ('u' | 'U') '32'
|
||||
UINT64_LIT = INT_LIT ['\''] ('u' | 'U') '64'
|
||||
UINT_LIT = INT_LIT ['\''] ('u' | 'U')
|
||||
UINT8_LIT = INT_LIT ['\''] ('u' | 'U') '8'
|
||||
UINT16_LIT = INT_LIT ['\''] ('u' | 'U') '16'
|
||||
UINT32_LIT = INT_LIT ['\''] ('u' | 'U') '32'
|
||||
UINT64_LIT = INT_LIT ['\''] ('u' | 'U') '64'
|
||||
|
||||
exponent = ('e' | 'E' ) ['+' | '-'] digit ( ['_'] digit )*
|
||||
FLOAT_LIT = unary_minus? digit (['_'] digit)* (('.' digit (['_'] digit)* [exponent]) |exponent)
|
||||
FLOAT32_SUFFIX = ('f' | 'F') ['32']
|
||||
FLOAT32_LIT = HEX_LIT '\'' FLOAT32_SUFFIX
|
||||
| (FLOAT_LIT | DEC_LIT | OCT_LIT | BIN_LIT) ['\''] FLOAT32_SUFFIX
|
||||
FLOAT64_SUFFIX = ( ('f' | 'F') '64' ) | 'd' | 'D'
|
||||
FLOAT64_LIT = HEX_LIT '\'' FLOAT64_SUFFIX
|
||||
| (FLOAT_LIT | DEC_LIT | OCT_LIT | BIN_LIT) ['\''] FLOAT64_SUFFIX
|
||||
exponent = ('e' | 'E' ) ['+' | '-'] digit ( ['_'] digit )*
|
||||
FLOAT_LIT = unary_minus? digit (['_'] digit)* (('.' digit (['_'] digit)* [exponent]) |exponent)
|
||||
FLOAT32_SUFFIX = ('f' | 'F') ['32']
|
||||
FLOAT32_LIT = HEX_LIT '\'' FLOAT32_SUFFIX
|
||||
| (FLOAT_LIT | DEC_LIT | OCT_LIT | BIN_LIT) ['\''] FLOAT32_SUFFIX
|
||||
FLOAT64_SUFFIX = ( ('f' | 'F') '64' ) | 'd' | 'D'
|
||||
FLOAT64_LIT = HEX_LIT '\'' FLOAT64_SUFFIX
|
||||
| (FLOAT_LIT | DEC_LIT | OCT_LIT | BIN_LIT) ['\''] FLOAT64_SUFFIX
|
||||
|
||||
CUSTOM_NUMERIC_LIT = (FLOAT_LIT | INT_LIT) '\'' CUSTOM_NUMERIC_SUFFIX
|
||||
CUSTOM_NUMERIC_LIT = (FLOAT_LIT | INT_LIT) '\'' CUSTOM_NUMERIC_SUFFIX
|
||||
|
||||
# CUSTOM_NUMERIC_SUFFIX is any Nim identifier that is not
|
||||
# a pre-defined type suffix.
|
||||
# CUSTOM_NUMERIC_SUFFIX is any Nim identifier that is not
|
||||
# a pre-defined type suffix.
|
||||
|
||||
|
||||
As can be seen in the productions, numeric literals can contain underscores
|
||||
|
|
@ -674,7 +674,7 @@ Operators
|
|||
---------
|
||||
|
||||
Nim allows user defined operators. An operator is any combination of the
|
||||
following characters::
|
||||
following characters:
|
||||
|
||||
= + - * / < >
|
||||
@ $ ~ & % |
|
||||
|
|
@ -698,10 +698,10 @@ as `a(not b)`, not as `(a) not (b)`.
|
|||
Unicode Operators
|
||||
-----------------
|
||||
|
||||
These Unicode operators are also parsed as operators::
|
||||
These Unicode operators are also parsed as operators:
|
||||
|
||||
∙ ∘ × ★ ⊗ ⊘ ⊙ ⊛ ⊠ ⊡ ∩ ∧ ⊓ # same priority as * (multiplication)
|
||||
± ⊕ ⊖ ⊞ ⊟ ∪ ∨ ⊔ # same priority as + (addition)
|
||||
∙ ∘ × ★ ⊗ ⊘ ⊙ ⊛ ⊠ ⊡ ∩ ∧ ⊓ # same priority as * (multiplication)
|
||||
± ⊕ ⊖ ⊞ ⊟ ∪ ∨ ⊔ # same priority as + (addition)
|
||||
|
||||
|
||||
Unicode operators can be combined with non-Unicode operator
|
||||
|
|
@ -714,7 +714,7 @@ No Unicode normalization step is performed.
|
|||
Other tokens
|
||||
------------
|
||||
|
||||
The following strings denote other tokens::
|
||||
The following strings denote other tokens:
|
||||
|
||||
` ( ) { } [ ] , ; [. .] {. .} (. .) [:
|
||||
|
||||
|
|
@ -1207,9 +1207,11 @@ The boolean type is named `bool`:idx: in Nim 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::
|
||||
This condition holds:
|
||||
|
||||
```nim
|
||||
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
|
||||
|
|
@ -1248,8 +1250,9 @@ specified. The values are ordered. Example:
|
|||
```
|
||||
|
||||
|
||||
Now the following holds::
|
||||
Now the following holds:
|
||||
|
||||
```nim
|
||||
ord(north) == 0
|
||||
ord(east) == 1
|
||||
ord(south) == 2
|
||||
|
|
@ -1257,6 +1260,7 @@ Now the following holds::
|
|||
|
||||
# Also allowed:
|
||||
ord(Direction.west) == 3
|
||||
```
|
||||
|
||||
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
|
||||
|
|
@ -2568,8 +2572,9 @@ literal match and that is better than a generic match etc. In the following,
|
|||
for the routine `p`.
|
||||
|
||||
A routine `p` matches better than a routine `q` if the following
|
||||
algorithm returns true::
|
||||
algorithm returns true:
|
||||
|
||||
```nim
|
||||
for each matching category m in ["exact match", "literal match",
|
||||
"generic match", "subtype match",
|
||||
"integral match", "conversion match"]:
|
||||
|
|
@ -2579,6 +2584,7 @@ algorithm returns true::
|
|||
else:
|
||||
return false
|
||||
return "ambiguous"
|
||||
```
|
||||
|
||||
|
||||
Some examples:
|
||||
|
|
@ -4061,19 +4067,19 @@ Nonoverloadable builtins
|
|||
------------------------
|
||||
|
||||
The following built-in procs cannot be overloaded for reasons of implementation
|
||||
simplicity (they require specialized semantic checking)::
|
||||
simplicity (they require specialized semantic checking):
|
||||
|
||||
declared, defined, definedInScope, compiles, sizeof,
|
||||
is, shallowCopy, getAst, astToStr, spawn, procCall
|
||||
declared, defined, definedInScope, compiles, sizeof,
|
||||
is, shallowCopy, getAst, astToStr, spawn, procCall
|
||||
|
||||
Thus, they act more like keywords than like ordinary identifiers; unlike a
|
||||
keyword however, a redefinition may `shadow`:idx: the definition in
|
||||
the [system](system.html) module.
|
||||
From this list the following should not be written in dot
|
||||
notation `x.f` since `x` cannot be type-checked before it gets passed
|
||||
to `f`::
|
||||
to `f`:
|
||||
|
||||
declared, defined, definedInScope, compiles, getAst, astToStr
|
||||
declared, defined, definedInScope, compiles, getAst, astToStr
|
||||
|
||||
|
||||
Var parameters
|
||||
|
|
@ -8291,16 +8297,16 @@ The `dynlib` import mechanism supports a versioning scheme:
|
|||
importc, dynlib: "libtcl(|8.5|8.4|8.3).so.(1|0)".}
|
||||
```
|
||||
|
||||
At runtime, the dynamic library is searched for (in this order)::
|
||||
At runtime, the dynamic library is searched for (in this order):
|
||||
|
||||
libtcl.so.1
|
||||
libtcl.so.0
|
||||
libtcl8.5.so.1
|
||||
libtcl8.5.so.0
|
||||
libtcl8.4.so.1
|
||||
libtcl8.4.so.0
|
||||
libtcl8.3.so.1
|
||||
libtcl8.3.so.0
|
||||
libtcl.so.1
|
||||
libtcl.so.0
|
||||
libtcl8.5.so.1
|
||||
libtcl8.5.so.0
|
||||
libtcl8.4.so.1
|
||||
libtcl8.4.so.0
|
||||
libtcl8.3.so.1
|
||||
libtcl8.3.so.0
|
||||
|
||||
The `dynlib` pragma supports not only constant strings as an argument but also
|
||||
string expressions in general:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue