Skip to content

Commit 01afd29

Browse files
author
Kirill Nesmeyanov
committed
Add constants page
1 parent 41ad492 commit 01afd29

File tree

12 files changed

+186
-59
lines changed

12 files changed

+186
-59
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/.idea

‎Writerside/tl.tree‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
<toc-element topic="logical-types.md"/>
1616
<toc-element topic="generic-types.md" toc-title="Generics"/>
1717
<toc-element topic="literal-types.md" toc-title="Literals"/>
18-
<toc-element topic="const-types.md" toc-title="Constants" hidden="true"/>
18+
<toc-element topic="const-types.md" toc-title="Constants"/>
1919
<toc-element topic="shape-types.md" toc-title="Shapes"/>
2020
<toc-element topic="callable-types.md" toc-title="Callables"/>
2121
<toc-element topic="conditional-types.md" toc-title="Conditions" hidden="true"/>

‎Writerside/topics/language/basic-types.md‎

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,20 @@
22

33
<show-structure for="chapter" depth="2"/>
44

5-
The parser does not impose restrictions on type naming. The type name must begin with the
6-
characters `[a-zA-Z\x80-\xff]` (any letter) and `_` (underscore) and can contain any characters
7-
within the limit `[a-zA-Z0-9\x80-\xff]` (any letter), as well as the characters `_` (underscore) and `-` (dash).
5+
The parser does not impose restrictions on type naming. The type name must begin
6+
with the characters `[a-zA-Z\x80-\xff]` (any letter) and `_` (underscore) and
7+
can contain any characters within the limit `[a-zA-Z0-9\x80-\xff]` (any letter),
8+
as well as the characters `_` (underscore) and `-` (dash).
89

9-
> For our purposes here, a **letter** is `a-z`, `A-Z`, and the bytes from 128 through 255 (`0x80-0xff`).
10+
> For our purposes here, a **letter** is `a-z`, `A-Z`, and the bytes from 128
11+
> through 255 (`0x80-0xff`).
1012
1113
In this case, the only difference from [the PHP grammar](https://www.php.net/manual/en/language.variables.basics.php)
1214
is that a **dash** (`-`) symbol is allowed in the middle of the name.
1315

14-
In addition, it is worth noting that the case-insensitive names `true`, `false` and `null` are registered
15-
PHP literals, so their use as a custom type name is **unacceptable**.
16+
In addition, it is worth noting that the case-insensitive names `true`, `false`
17+
and `null` are registered PHP literals, so their use as a custom type name
18+
is **unacceptable**.
1619

1720
<tabs>
1821
<tab title="Examples">
@@ -23,14 +26,14 @@ PHP literals, so their use as a custom type name is **unacceptable**.
2326
> ```
2427
> {style="note"}
2528
26-
> Dashes (`-`) in <tooltip term="Identifier">Identifier</tooltip>
27-
> are also acceptable.
29+
> Dashes (`-`) in <tooltip term="Identifier">Identifier</tooltip> are also
30+
> acceptable.
2831
> ```typescript
2932
> example-type
3033
> ```
3134
> {style="note"}
3235
33-
> The reserved keyword (`true`) is allowed as part of the <tooltip
36+
> The reserved keyword (`true`) is allowed as part of the <tooltip
3437
> term="Identifier">Identifier</tooltip>.
3538
> ```typescript
3639
> true-type
@@ -40,10 +43,9 @@ PHP literals, so their use as a custom type name is **unacceptable**.
4043
</tab>
4144
<tab title="Counterexamples">
4245
43-
> The standalone keywords (`true`) is NOT available as an <tooltip
44-
> term="Identifier">Identifier</tooltip> regardless of case and is
45-
> parsed as a literal value rather than an <tooltip
46-
> term="Identifier">Identifier</tooltip>.
46+
> The standalone keywords (`true`) is NOT available as an <tooltip
47+
> term="Identifier">Identifier</tooltip> regardless of case and is parsed as a
48+
> literal value rather than an <tooltip term="Identifier">Identifier</tooltip>.
4749
> ```typescript
4850
> TrUe
4951
>
@@ -55,8 +57,8 @@ PHP literals, so their use as a custom type name is **unacceptable**.
5557
> ```
5658
> {style="warning"}
5759
58-
> <tooltip term="Identifier">Identifiers</tooltip> cannot begin with
59-
digits (`0-9`) or a dash (`-`) symbol.
60+
> <tooltip term="Identifier">Identifiers</tooltip> cannot begin with digits
61+
> (`0-9`) or a dash (`-`) symbol.
6062
> ```typescript
6163
> 42type
6264
>
@@ -70,12 +72,12 @@ digits (`0-9`) or a dash (`-`) symbol.
7072
## Namespace
7173
7274
Each name can contain a namespace symbol (`\` — backslash), which is
73-
[similar to that in PHP](https://www.php.net/manual/en/language.namespaces.rationale.php). The separator can be located either in
74-
the middle or at the beginning of any <tooltip
75-
term="Identifier">Identifier</tooltip>. End position is not allowed.
75+
[similar to that in PHP](https://www.php.net/manual/en/language.namespaces.rationale.php). The separator can be located either in the middle
76+
or at the beginning of any <tooltip term="Identifier">Identifier</tooltip>. End
77+
position is not allowed.
7678
77-
The namespace delimiter can be used in conjunction with keywords such
78-
as `true`, `false`, or `null` to explicitly indicate a type reference.
79+
The namespace delimiter can be used in conjunction with keywords such as `true`,
80+
`false`, or `null` to explicitly indicate a type reference.
7981
8082
<tabs>
8183
<tab title="Examples">

‎Writerside/topics/language/callable-types.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Each callable MAY have a list of parameters and/or a return type definition.
2727
### Named Parameters
2828
2929
The name after the type of the parameter defines the parameter that
30-
[allows passing by name](https://www.php.net/manual/en/functions.arguments.php#functions.named-arguments).&#x20;
30+
[allows passing by name](https://www.php.net/manual/en/functions.arguments.php#functions.named-arguments).
3131
3232
The name must appear after the parameter type and begin with a "`$`" sign.
3333
Just like in the PHP language.

‎Writerside/topics/language/const-types.md‎

Lines changed: 131 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,135 @@
11
# Constant Types
22

3-
<warning>
4-
WIP: Documentation is not complete
5-
</warning>
6-
73
<show-structure for="chapter" depth="2"/>
84

9-
Constants are identifiers containing specific readonly values. There are two types
10-
of constants:
11-
- Global (including those located in a namespace).
12-
```typescript
13-
Path\To\CONSTANT_NAME
14-
```
15-
- Constants of a class.
16-
```typescript
17-
Path\To\ClassName::CONSTANT_NAME
18-
```
5+
Unlike [identifiers (type names)](basic-types.md), constants cannot contain
6+
the dash (`-`) character. However, the grammar of the [type name](basic-types.md)
7+
and the constant *are identical*, so this conflict of semantics will have to be
8+
resolved independently during the implementation of a custom solution that uses
9+
the TypeLang grammar.
10+
11+
[Namespaces](basic-types.md#namespace) specifying a reference to a constant are
12+
also allowed.
13+
14+
> With this in mind, note that any constant is interpreted as a
15+
> [named type](basic-types.md).
16+
17+
Given the complete identity of the grammar of constants with
18+
[named type](basic-types.md), they cannot contain case-insensitive names
19+
`true`, `false` and `null` of literals.
20+
21+
<tabs>
22+
<tab title="Examples">
23+
24+
> Example of global constant (or type name)
25+
> ```typescript
26+
> JSON_THROW_ON_ERROR
27+
> ```
28+
> {style="note"}
29+
30+
> Example of namespaced constant (or type name)
31+
> ```typescript
32+
> pcov\version
33+
> ```
34+
> {style="note"}
35+
36+
</tab>
37+
<tab title="Counterexamples">
38+
39+
> The standalone keywords (`true`) is NOT available as an <tooltip
40+
> term="Identifier">Identifier</tooltip> regardless of case and is parsed as a
41+
> literal value rather than an <tooltip term="Identifier">Identifier</tooltip>.
42+
> ```typescript
43+
> TrUe
44+
>
45+
> // TypeLang\Parser\Node\Literal\BoolLiteralNode {
46+
> // +offset: 0
47+
> // +raw: "TrUe"
48+
> // +value: true
49+
> // }
50+
> ```
51+
> {style="warning"}
52+
53+
</tab>
54+
</tabs>
55+
56+
## Class Constants
57+
58+
Class constants begin with any [type name](basic-types.md), then contain
59+
a double colon (`::`) character, and then the constant name.
60+
61+
<tabs>
62+
<tab title="Examples">
63+
64+
> Reference to a class constant in the global namespace.
65+
> ```typescript
66+
> ClassName::CONSTANT_NAME
67+
> ```
68+
> {style="note"}
69+
70+
> Reference a constant in a class that is located in some namespace.
71+
> ```typescript
72+
> Path\To\ClassName::ANOTHER_CONSTANT_NAME
73+
> ```
74+
> {style="note"}
75+
76+
</tab>
77+
<tab title="Counterexamples">
78+
79+
> A constant in a class must be an <tooltip term="Identifier">
80+
> Identifier</tooltip> and cannot contain its own namespace.
81+
> ```typescript
82+
> ClassName::SOME\ANY
83+
> ```
84+
> {style="warning"}
85+
86+
</tab>
87+
</tabs>
88+
89+
## Constant Masks
90+
91+
A reference to a certain set of constants can be defined using a mask. The
92+
use of masks is identical to regular constants, but must be terminated with
93+
an asterisk (`*`).
94+
95+
Prefixes on class constants can be omitted, so type will mean any class constant.
96+
97+
98+
<tabs>
99+
<tab title="Examples">
100+
101+
> Reference to any constant with the `JSON_*` prefix.
102+
> ```typescript
103+
> JSON_*
104+
> ```
105+
> {style="note"}
106+
107+
> Reference to any class constant with the `PREFIX_` prefix.
108+
> ```typescript
109+
> Path\To\ClassName::PREFIX_*
110+
> ```
111+
> {style="note"}
112+
113+
> Reference to any class constant
114+
> ```typescript
115+
> Path\To\ClassName::*
116+
> ```
117+
> {style="note"}
118+
119+
</tab>
120+
<tab title="Counterexamples">
121+
122+
> It is not allowed to omit prefixes from global constants.
123+
> ```typescript
124+
> *
125+
> ```
126+
> {style="warning"}
127+
128+
> The asterisk (`*`) must be the final character.
129+
> ```typescript
130+
> Path\To\ClassName::PREFIX_*_SUFFIX
131+
> ```
132+
> {style="warning"}
133+
134+
</tab>
135+
</tabs>

‎Writerside/topics/language/generic-types.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@ comma (`,`).
1717
> If the PHP language supported generic types, then the declaration
1818
> (in pseudo-language) of the type:
1919
>
20-
> * `interface Traversable<TKey of array-key, TValue of mixed>` would contain **parameters**
20+
> * `interface Traversable<TKey of array-key, TValue of mixed>` would contain
21+
> **parameters**
2122
>
2223
> and the reference to the type:
2324
>
@@ -68,15 +69,16 @@ comma (`,`).
6869
6970
## Call-Site Hints
7071
71-
Each generic argument allows you to define an additional hint, which can
72-
be used, for example, in static analyzers to indicate the
72+
Each generic argument allows you to define an additional hint, which can be
73+
used, for example, in static analyzers to indicate the
7374
[call-site variance](https://phpstan.org/blog/guide-to-call-site-generic-variance#call-site-variance).
7475
7576
7677
<tabs>
7778
<tab title="Examples">
7879
79-
> Any identifier (in this case "`covariant`") before the template argument`s type is acceptable.
80+
> Any identifier (in this case "`covariant`") before the template argument`s
81+
> type is acceptable.
8082
> ```typescript
8183
> HashMap<array-key, covariant Request>
8284
> ```

‎Writerside/topics/language/literal-types.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,8 @@ insertion of special sequences.
5151
5252
### Escape Sequences
5353
54-
All control sequences are similar to the PHP language: [https://www.php.net/manual/en/language.types.string.php](https://www.php.net/manual/en/language.types.string.php)
54+
All control sequences are similar to the PHP language:
55+
[https://www.php.net/manual/en/language.types.string.php](https://www.php.net/manual/en/language.types.string.php)
5556
5657
* `\n` — Line break (`0x0A` code)
5758
* `\r` — Carriage return (`0x0D` code)
@@ -80,8 +81,8 @@ All control sequences are similar to the PHP language: [https://www.php.net/manu
8081
8182
### Hexadecimal Sequences
8283
83-
The sequence of characters matching the regular expression `[0-9A-Fa-f]{1,2}` is
84-
a character in hexadecimal notation (e.g. `"\x41" === "A"`)
84+
The sequence of characters matching the regular expression `[0-9A-Fa-f]{1,2}`
85+
is a character in hexadecimal notation (e.g. `"\x41" === "A"`).
8586
8687
> `"Hello World"` string equivalent in hexadecimal sequences format.
8788
> ```typescript
@@ -233,8 +234,9 @@ numbers between `0` and `7` and must match the regular expression
233234
234235
### Hexadecimal
235236
236-
Every hexadecimal number is prefixed with `0x` or `0X` and can only contain the
237-
numbers between `0` and `F` and must match the regular expression `0x[0-9a-fA-F]+`.
237+
Every hexadecimal number is prefixed with `0x` or `0X` and can only contain
238+
the numbers between `0` and `F` and must match the regular expression
239+
`0x[0-9a-fA-F]+`.
238240
239241
<tabs>
240242
<tab title="Examples">
@@ -330,9 +332,9 @@ trailing number may be omitted. Negative values are prefixed with a minus (`-`.
330332
331333
### Scientific Notation
332334
333-
Scientific notation is a way of expressing numbers that are too large or too small to be
334-
conveniently written in decimal form, since to do so would require writing out an
335-
inconveniently long string of digits.
335+
Scientific notation is a way of expressing numbers that are too large or too
336+
small to be conveniently written in decimal form, since to do so would require
337+
writing out an inconveniently long string of digits.
336338
337339
<tabs>
338340
<tab title="Examples">

‎Writerside/topics/language/logical-types.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
<show-structure for="chapter" depth="2"/>
44

5-
The TypeLang, [like PHP](https://www.php.net/manual/en/language.types.type-system.php#language.types.type-system.composite), supports two types of composite (logical)
6-
types: Union and Intersection. The ability to specify a _nullable_ type using a
5+
The TypeLang, [like PHP](https://www.php.net/manual/en/language.types.type-system.php#language.types.type-system.composite), supports two types of composite (logical) types:
6+
Union and Intersection. The ability to specify a _nullable_ type using a
77
separate expression is also supported.
88

99
### Union Type
@@ -28,7 +28,8 @@ contain any other type definition.
2828
2929
### Nullable Type
3030
31-
Nullable type is a shortened alias for union type `T | null` and is written as `?T.`
31+
Nullable type is a shortened alias for union type `T | null`
32+
and is written as `?T.`
3233
3334
<tabs>
3435
<tab title="Examples">

‎Writerside/topics/language/shape-types.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ Each **composite** type can be rigidly described by a structural type called a
66
"shape". A shape within the PHP language can be applied to any array or object
77
and contain either implicit or explicit keys.
88

9-
> Support for other types of **keys**, such as const mask (`Class::CONST_*)` is not
10-
> currently available.
9+
> Support for other types of **keys**, such as const mask (`Class::CONST_*)`
10+
> is not currently available.
1111
{style="warning"}
1212

1313
<tabs>
@@ -83,9 +83,9 @@ array{
8383

8484
### Typed Shapes
8585

86-
In addition, such shapes can describe template arguments (types) for values or for keys and values,
87-
which are described after the ellipsis (`...`) char and contain
88-
syntax [similar to generics](generic-types.md).
86+
In addition, such shapes can describe template arguments (types) for values
87+
or for keys and values, which are described after the ellipsis (`...`) char
88+
and contain syntax [similar to generics](generic-types.md).
8989

9090
<compare first-title="Without Arguments" second-title="With Arguments">
9191

‎Writerside/topics/parser/visitors/stream-dumper-visitor.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
<show-structure for="chapter" depth="2"/>
44

5-
To easily debug the structure and output of the AST, you can use the `StreamDumperVisitor` visitor.
5+
To easily debug the structure and output of the AST, you can use the
6+
`StreamDumperVisitor` visitor.
67

78
```php
89
use TypeLang\Parser\Traverser;

0 commit comments

Comments
 (0)