mago-codex 1.15.2

PHP type system representation, comparison logic, and codebase metadata for static analysis.
Documentation 
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

//! A collection of shared, static, and lazily-initialized `TAtomic` types.
//!
//! This module provides canonical, reusable instances for common PHP types.
//! Using these constants avoids repeated allocations for frequently used types.

use std::sync::Arc;
use std::sync::LazyLock;

use mago_atom::empty_atom;

use crate::ttype::atomic::TAtomic;
use crate::ttype::atomic::array::TArray;
use crate::ttype::atomic::array::keyed::TKeyedArray;
use crate::ttype::atomic::callable::TCallable;
use crate::ttype::atomic::callable::TCallableSignature;
use crate::ttype::atomic::iterable::TIterable;
use crate::ttype::atomic::mixed::TMixed;
use crate::ttype::atomic::object::TObject;
use crate::ttype::atomic::resource::TResource;
use crate::ttype::atomic::scalar::TScalar;
use crate::ttype::atomic::scalar::int::TInteger;
use crate::ttype::atomic::scalar::string::TString;
use crate::ttype::atomic::scalar::string::TStringLiteral;
use crate::ttype::get_arraykey;
use crate::ttype::get_mixed;

use super::atomic::scalar::string::TStringCasing;

/// A static `TAtomic` representing the integer literal `1`.
pub const ONE_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::literal_int(1));
/// A static `TAtomic` representing the integer literal `0`.
pub const ZERO_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::literal_int(0));
/// A static `TAtomic` representing the integer literal `-1`.
pub const MINUS_ONE_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::literal_int(-1));
/// A static `TAtomic` representing the general `int` type.
pub const INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::int());
/// A static `TAtomic` representing a positive integer (`positive-int` or `int<1, max>`).
pub const POSITIVE_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::Integer(TInteger::positive()));
/// A static `TAtomic` representing a non-positive integer (`non-positive-int` or `int<min, 0>`).
pub const NON_POSITIVE_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::Integer(TInteger::non_positive()));
/// A static `TAtomic` representing a negative integer (`negative-int` or `int<min, -1>`).
pub const NEGATIVE_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::Integer(TInteger::negative()));
/// A static `TAtomic` representing a non-negative integer (`non-negative-int` or `int<0, max>`).
pub const NON_NEGATIVE_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::Integer(TInteger::non_negative()));
/// A static `TAtomic` representing a `literal-int` where the value is unknown.
pub const UNSPECIFIED_LITERAL_INT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::Integer(TInteger::UnspecifiedLiteral));
/// A static `TAtomic` for the general `string` type.
pub const STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, false, false, TStringCasing::Unspecified)));
/// A static `TAtomic` for a `lowercase-string`.
pub const LOWERCASE_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, false, false, TStringCasing::Lowercase)));
/// A static `TAtomic` for a `uppercase-string`.
pub const UPPERCASE_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, false, false, TStringCasing::Uppercase)));
/// A static `TAtomic` for a `non-empty-string`.
pub const NON_EMPTY_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, false, true, TStringCasing::Unspecified)));
/// A static `TAtomic` for a `non-empty-lowercase-string`.
pub const NON_EMPTY_LOWERCASE_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, false, true, TStringCasing::Lowercase)));
/// A static `TAtomic` for a `non-empty-uppercase-string`.
pub const NON_EMPTY_UPPERCASE_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, false, true, TStringCasing::Uppercase)));
/// A static `TAtomic` for a `truthy-string`.
pub const TRUTHY_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, true, false, TStringCasing::Unspecified)));
/// A static `TAtomic` for a `truthy-lowercase-string`.
pub const TRUTHY_LOWERCASE_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, true, false, TStringCasing::Lowercase)));
/// A static `TAtomic` for a `truthy-uppercase-string`.
pub const TRUTHY_UPPERCASE_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, false, true, false, TStringCasing::Uppercase)));
/// A static `TAtomic` for a `numeric-string`.
pub const NUMERIC_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, true, false, false, TStringCasing::Unspecified)));
/// A static `TAtomic` for a `numeric-string` that is also `truthy`.
pub const NUMERIC_TRUTHY_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::String(TString::new(None, true, true, false, TStringCasing::Unspecified)));
/// A static `TAtomic` representing the `class-string` type.
pub const CLASS_STRING_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::class_string());
/// A static `TAtomic` representing the `interface-string` type.
pub const INTERFACE_STRING_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::interface_string());
/// A static `TAtomic` representing the `enum-string` type.
pub const ENUM_STRING_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::enum_string());
/// A static `TAtomic` representing the `trait-string` type.
pub const TRAIT_STRING_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::trait_string());
/// A static `TAtomic` representing the `float` type.
pub const FLOAT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::float());
/// A static `TAtomic` representing the `literal-float` type (unspecified literal).
pub const UNSPECIFIED_LITERAL_FLOAT_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::unspecified_literal_float());
/// A static `TAtomic` representing the `mixed` type.
pub const MIXED_ATOMIC: &TAtomic = &TAtomic::Mixed(TMixed::new());
/// A static `TAtomic` representing a `mixed` type that originates from an `isset()` check inside a loop.
pub const ISSET_FROM_LOOP_MIXED_ATOMIC: &TAtomic = &TAtomic::Mixed(TMixed::isset_from_loop());
/// A static `TAtomic` representing the `never` type, which indicates an impossible state.
pub const NEVER_ATOMIC: &TAtomic = &TAtomic::Never;
/// A static `TAtomic` representing any value that is not `null`.
pub const NON_NULL_ATOMIC: &TAtomic = &TAtomic::Mixed(TMixed::non_null());
/// A static `TAtomic` representing any "falsy" value (e.g., `false`, `0`, `""`, `[]`).
pub const FALSY_MIXED_ATOMIC: &TAtomic = &TAtomic::Mixed(TMixed::falsy());
/// A static `TAtomic` representing any "truthy" value.
pub const TRUTHY_MIXED_ATOMIC: &TAtomic = &TAtomic::Mixed(TMixed::truthy());
/// A static `TAtomic` representing the `resource` type.
pub const RESOURCE_ATOMIC: &TAtomic = &TAtomic::Resource(TResource::new(None));
/// A static `TAtomic` representing an open `resource`.
pub const OPEN_RESOURCE_ATOMIC: &TAtomic = &TAtomic::Resource(TResource::open());
/// A static `TAtomic` representing a closed `resource`.
pub const CLOSED_RESOURCE_ATOMIC: &TAtomic = &TAtomic::Resource(TResource::closed());
/// A static `TAtomic` used as a temporary placeholder during type reconciliation.
pub const PLACEHOLDER_ATOMIC: &TAtomic = &TAtomic::Placeholder;
/// A static `TAtomic` representing the `void` type.
pub const VOID_ATOMIC: &TAtomic = &TAtomic::Void;
/// A static `TAtomic` representing the `null` type.
pub const NULL_ATOMIC: &TAtomic = &TAtomic::Null;
/// A static `TAtomic` representing the `array-key` type (`int|string`).
pub const ARRAYKEY_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::ArrayKey);
/// A static `TAtomic` representing the `bool` type.
pub const BOOL_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::bool());
/// A static `TAtomic` representing the literal `false` type.
pub const FALSE_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::r#false());
/// A static `TAtomic` representing the literal `true` type.
pub const TRUE_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::r#true());
/// A static `TAtomic` representing the general `object` type.
pub const OBJECT_ATOMIC: &TAtomic = &TAtomic::Object(TObject::Any);
/// A static `TAtomic` representing the `numeric` type (`int|float|numeric-string`).
pub const NUMERIC_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::Numeric);
/// A static `TAtomic` representing an empty string literal (`""`).
pub static EMPTY_STRING_ATOMIC: LazyLock<TAtomic> = LazyLock::new(|| {
    TAtomic::Scalar(TScalar::String(TString {
        literal: Some(TStringLiteral::Value(empty_atom())),
        is_numeric: false,
        is_truthy: false,
        is_non_empty: false,
        casing: TStringCasing::Unspecified,
    }))
});
/// A static `TAtomic` representing a `literal-string` where the value is unknown.
pub const UNSPECIFIED_LITERAL_STRING_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::unspecified_literal_string(false));
/// A static `TAtomic` representing a non-empty `literal-string` where the value is unknown.
pub const NON_EMPTY_UNSPECIFIED_LITERAL_STRING_ATOMIC: &TAtomic =
    &TAtomic::Scalar(TScalar::unspecified_literal_string(true));
/// A static `TAtomic` representing the `scalar` type (`int|float|string|bool`).
pub const SCALAR_ATOMIC: &TAtomic = &TAtomic::Scalar(TScalar::Generic);

/// A lazily-initialized static `TAtomic` for a mixed iterable (`iterable<mixed, mixed>`).
pub static MIXED_ITERABLE_ATOMIC: LazyLock<TAtomic> = LazyLock::new(|| {
    TAtomic::Iterable(TIterable {
        key_type: Arc::new(get_mixed()),
        value_type: Arc::new(get_mixed()),
        intersection_types: None,
    })
});

/// A lazily-initialized static `TAtomic` for an empty array (`array<never, never>`).
pub static EMPTY_KEYED_ARRAY_ATOMIC: LazyLock<TAtomic> =
    LazyLock::new(|| TAtomic::Array(TArray::Keyed(TKeyedArray::new())));
/// A lazily-initialized static `TAtomic` for a mixed array (`array<array-key, mixed>`).
pub static MIXED_KEYED_ARRAY_ATOMIC: LazyLock<TAtomic> = LazyLock::new(|| {
    TAtomic::Array(TArray::Keyed(TKeyedArray::new_with_parameters(Arc::new(get_arraykey()), Arc::new(get_mixed()))))
});
/// A lazily-initialized static `TAtomic` for a mixed callable (`callable`).
pub static MIXED_CALLABLE_ATOMIC: LazyLock<TAtomic> =
    LazyLock::new(|| TAtomic::Callable(TCallable::Signature(TCallableSignature::mixed(false))));
/// A lazily-initialized static `TAtomic` for a mixed closure (`Closure`).
pub static MIXED_CLOSURE_ATOMIC: LazyLock<TAtomic> =
    LazyLock::new(|| TAtomic::Callable(TCallable::Signature(TCallableSignature::mixed(true))));

/// A static slice of atomics representing the union type `int|float`.
pub const INT_FLOAT_ATOMIC_SLICE: &[TAtomic] = &[TAtomic::Scalar(TScalar::int()), TAtomic::Scalar(TScalar::float())];
/// A static slice of atomics representing the union type `int|string`.
pub const INT_STRING_ATOMIC_SLICE: &[TAtomic] = &[TAtomic::Scalar(TScalar::int()), TAtomic::Scalar(TScalar::string())];
/// A static slice of atomics representing the union type `null|scalar`.
pub const NULL_SCALAR_ATOMIC_SLICE: &[TAtomic] = &[TAtomic::Null, TAtomic::Scalar(TScalar::Generic)];
/// A static slice of atomics representing the union type `null|string`.
pub const NULL_STRING_ATOMIC_SLICE: &[TAtomic] = &[TAtomic::Null, TAtomic::Scalar(TScalar::string())];
/// A static slice of atomics representing the union type `null|int`.
pub const NULL_INT_ATOMIC_SLICE: &[TAtomic] = &[TAtomic::Null, TAtomic::Scalar(TScalar::int())];
/// A static slice of atomics representing the union type `null|float`.
pub const NULL_FLOAT_ATOMIC_SLICE: &[TAtomic] = &[TAtomic::Null, TAtomic::Scalar(TScalar::float())];
/// A static slice of atomics representing the union type `null|object`.
pub const NULL_OBJECT_ATOMIC_SLICE: &[TAtomic] = &[TAtomic::Null, TAtomic::Object(TObject::Any)];

/// A static slice of atomics representing the union type `-1|0|1`, commonly
/// returned by comparison operations like the spaceship operator (`<=>`).
pub const SIGNUM_RESULT_SLICE: &[TAtomic] = &[
    TAtomic::Scalar(TScalar::literal_int(-1)),
    TAtomic::Scalar(TScalar::literal_int(0)),
    TAtomic::Scalar(TScalar::literal_int(1)),
];