Skip to content

ludus::tooling::shader_language

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/diagnostic.hpp

Enumerations

DiagnosticCode

enum class DiagnosticCode : foundation::uint16
Stable LUSL diagnostic code, displayed as LUSL followed by four digits (LUSL0201).
Values never change meaning once released; retired codes are not reused. Codes 1-99 are language rules shared by every stage, 100-199 are lexical and 200-299 are preprocessor diagnostics. docs/modules/tooling/shader-language.md lists every code.

Related types: foundation::uint16

LogicalNot

LogicalNot = 1
Unary ! does not exist in LUSL; compare with == false, or with == 0 in #if.

InvalidRequest

InvalidRequest = 2
The request is malformed: a path, the root file, a configuration value or a snapshot limit.

InvalidUtf8

InvalidUtf8 = 101
A file is not well-formed UTF-8.

InvalidCharacter

InvalidCharacter = 102
A byte that cannot start a token, such as @, $, a backtick or non-ASCII text outside a comment or string.

UnterminatedComment

UnterminatedComment = 103
A /* comment has no closing */.

UnterminatedString

UnterminatedString = 104
A string literal has no closing quote on its line.

InvalidEscape

InvalidEscape = 105
A string literal contains an escape other than \\, \", \n, \r or \t.

CharacterLiteral

CharacterLiteral = 106
A character literal such as 'a'; LUSL has no character type.

FileTokenLimit

FileTokenLimit = 107
A file or configuration value lexes to more than MAX_FILE_TOKENS tokens.

UnknownDirective

UnknownDirective = 201
A directive name that LUSL does not define.

MalformedDirective

MalformedDirective = 202
A directive is missing a required part or has extra tokens.

IncludeNotFound

IncludeNotFound = 203
No snapshot file matches an #include path.

IncludeNotHeader

IncludeNotHeader = 204
An #include names a file that is not a .luslh header.

InvalidIncludePath

InvalidIncludePath = 205
An #include path is absolute, contains a backslash or empty component, or leaves the snapshot root.

RecursiveInclude

RecursiveInclude = 206
A file includes itself, directly or indirectly, without #pragma once.

IncludeDepthLimit

IncludeDepthLimit = 207
#include nesting exceeds MAX_INCLUDE_DEPTH.

MacroRedefined

MacroRedefined = 208
A macro is redefined with a different kind, parameter list or body.

ConfigurationModified

ConfigurationModified = 209
A configuration value is redefined or undefined by #define or #undef.

ReservedMacroName

ReservedMacroName = 210
defined cannot be a macro name.

VariadicMacro

VariadicMacro = 211
A function-like macro declares ...; LUSL macros are not variadic.

DuplicateMacroParameter

DuplicateMacroParameter = 212
A function-like macro repeats a parameter name.

StringifyNotParameter

StringifyNotParameter = 213
# in a function-like macro body is not followed by a parameter.

PasteAtEdge

PasteAtEdge = 214
## begins or ends a macro body.

InvalidPaste

InvalidPaste = 215
## joins two tokens whose combined spelling is not exactly one token.

MacroArgumentCount

MacroArgumentCount = 216
A function-like macro invocation has the wrong number of arguments.

UnterminatedMacroInvocation

UnterminatedMacroInvocation = 217
A function-like macro invocation reaches the end of its file without a closing ).

DirectiveInMacroArguments

DirectiveInMacroArguments = 218
A directive line appears inside the arguments of a function-like macro invocation.

UndefinedIdentifierInCondition

UndefinedIdentifierInCondition = 219
An identifier remains in an #if or #elif expression after macro expansion. C treats it as zero; LUSL rejects it so misspelled names are caught.

UnknownMacroName

UnknownMacroName = 220
defined, #ifdef or #ifndef tests a name that is neither a configuration value nor a macro defined or undefined earlier in the translation unit.

InvalidCondition

InvalidCondition = 221
An #if or #elif expression is not a valid integer constant expression.

ConditionDivisionByZero

ConditionDivisionByZero = 222
An evaluated #if or #elif operand divides by zero.

ConditionOverflow

ConditionOverflow = 223
An evaluated #if or #elif operation overflows int64 or shifts out of range.

UnterminatedConditional

UnterminatedConditional = 224
An #if group has no #endif before the end of the file that opened it.

UnmatchedConditional

UnmatchedConditional = 225
#elif, #else or #endif has no matching #if, or follows #else.

ErrorDirective

ErrorDirective = 226
An #error directive was reached; its text is the message.

UnknownPragma

UnknownPragma = 227
A #pragma other than #pragma once.

LineDirective

LineDirective = 228
#line is reserved for generated code.

ConditionalDepthLimit

ConditionalDepthLimit = 229
#if nesting exceeds MAX_CONDITIONAL_DEPTH, or expression nesting exceeds MAX_CONDITION_NESTING.

MacroExpansionLimit

MacroExpansionLimit = 230
Macro expansion exceeds MAX_MACRO_EXPANSIONS, MAX_MACRO_EXPANSION_DEPTH or MAX_SYNTHESIZED_BYTES.

OutputTokenLimit

OutputTokenLimit = 231
The preprocessed translation unit exceeds MAX_OUTPUT_TOKENS.

MacroLimit

MacroLimit = 232
More than MAX_MACROS distinct macro names, or more than MAX_MACRO_PARAMETERS parameters.

DefinedFromExpansion

DefinedFromExpansion = 233
defined appears in an #if expression as a result of macro expansion.

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/diagnostic.hpp

Severity

enum class Severity : foundation::uint8
How a diagnostic affects the result.

Related types: foundation::uint8

Error

Error
The request fails; no output is published.

Warning

Warning
Reported only; the request may still succeed.

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/diagnostic.hpp

Status

enum class Status : foundation::uint8
Outcome of a front-end stage.

Related types: foundation::uint8

Ready

Ready
The stage succeeded; its output is complete. Warnings may be present.

Failed

Failed
The source has errors; the diagnostics say which. No output tokens are published.

InvalidRequest

InvalidRequest
The request itself is malformed; a DiagnosticCode::InvalidRequest diagnostic says why.

OutOfMemory

OutOfMemory
Allocation failed. Diagnostics may be incomplete.

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/preprocessor.hpp

TokenKind

enum class TokenKind : foundation::uint8
Lexical category of a token.

Related types: foundation::uint8

Identifier

Identifier
[A-Za-z_][A-Za-z0-9_]*. Keywords are identifiers until the parser classifies them.

Number

Number
A C preprocessing number: a digit, or . and a digit, followed by digits, letters, _, . and exponent signs (e+, E-, p+, P-). Its value is checked by later stages.

String

String
A double-quoted string literal, including its quotes and escapes.

Punctuator

Punctuator
An operator or separator; Token::Symbol says which.

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/token.hpp

Punctuator

enum class Punctuator : foundation::uint8
Operator or separator spelled by a Punctuator token. Lexing takes the longest match.

Related types: foundation::uint8

None

None
The token is not a punctuator.

LeftBrace

LeftBrace
{

RightBrace

RightBrace
}

LeftBracket

LeftBracket
[

RightBracket

RightBracket
]

LeftParenthesis

LeftParenthesis
(

RightParenthesis

RightParenthesis
)

Semicolon

Semicolon
;

Comma

Comma
,

Period

Period
.

Ellipsis

Ellipsis
...

Colon

Colon
:

ColonColon

ColonColon
::

Question

Question
?

Equal

Equal
=

EqualEqual

EqualEqual
==

Exclamation

Exclamation
!, which only exists to report DiagnosticCode::LogicalNot

ExclamationEqual

ExclamationEqual
!=

Less

Less
<

LessEqual

LessEqual
<=

Greater

Greater
>

GreaterEqual

GreaterEqual
>=

Plus

Plus
+

Minus

Minus
-

Star

Star
*

Slash

Slash
/

Percent

Percent
%

Ampersand

Ampersand
&

Pipe

Pipe
|

Caret

Caret
^

Tilde

Tilde
~

LessLess

LessLess
<<

GreaterGreater

GreaterGreater
>>

AmpersandAmpersand

AmpersandAmpersand
&&

PipePipe

PipePipe
||

PlusEqual

PlusEqual
+=

MinusEqual

MinusEqual
-=

StarEqual

StarEqual
*=

SlashEqual

SlashEqual
/=

PercentEqual

PercentEqual
%=

AmpersandEqual

AmpersandEqual
&=

PipeEqual

PipeEqual
|=

CaretEqual

CaretEqual
^=

LessLessEqual

LessLessEqual
<<=

GreaterGreaterEqual

GreaterGreaterEqual
>>=

PlusPlus

PlusPlus
++

MinusMinus

MinusMinus
--

Arrow

Arrow
->

Hash

Hash
#

HashHash

HashHash
##

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/token.hpp

Aliases

DiagnosticMessage

using ludus::tooling::shader_language::DiagnosticMessage = foundation::StaticString<MAX_DIAGNOSTIC_MESSAGE_BYTES>
Bounded diagnostic text; MAX_DIAGNOSTIC_MESSAGE_BYTES bytes at most.

Related types: foundation::StaticString · MAX_DIAGNOSTIC_MESSAGE_BYTES

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/diagnostic.hpp

Constants and variables

CONFIGURATION_SOURCE

constexpr foundation::uint16 ludus::tooling::shader_language::CONFIGURATION_SOURCE = 0xfffe
SourceLocation::FileIndex of text supplied as a configuration value instead of a file.

Related types: foundation::uint16

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/diagnostic.hpp

NO_SOURCE

constexpr foundation::uint16 ludus::tooling::shader_language::NO_SOURCE = 0xffff
SourceLocation::FileIndex of a location that does not exist.

Related types: foundation::uint16

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/diagnostic.hpp

MAX_FILE_TOKENS

constexpr foundation::usize ludus::tooling::shader_language::MAX_FILE_TOKENS = foundation::usize{1} << 20
Most tokens lexed from one file or configuration value.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_OUTPUT_TOKENS

constexpr foundation::usize ludus::tooling::shader_language::MAX_OUTPUT_TOKENS = foundation::usize{1} << 20
Most tokens in one preprocessed translation unit.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_INCLUDE_DEPTH

constexpr foundation::usize ludus::tooling::shader_language::MAX_INCLUDE_DEPTH = 32
Deepest #include nesting; the root file is depth one.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_CONDITIONAL_DEPTH

constexpr foundation::usize ludus::tooling::shader_language::MAX_CONDITIONAL_DEPTH = 64
Deepest nesting of #if groups in one translation unit.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_CONDITION_NESTING

constexpr foundation::usize ludus::tooling::shader_language::MAX_CONDITION_NESTING = 64
Deepest parenthesis and operator nesting inside one #if or #elif expression.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_MACROS

constexpr foundation::usize ludus::tooling::shader_language::MAX_MACROS = 4096
Most distinct macro names, defined or undefined, including configuration values.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_MACRO_PARAMETERS

constexpr foundation::usize ludus::tooling::shader_language::MAX_MACRO_PARAMETERS = 32
Most parameters of one function-like macro.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_MACRO_EXPANSION_DEPTH

constexpr foundation::usize ludus::tooling::shader_language::MAX_MACRO_EXPANSION_DEPTH = 32
Deepest nesting of macro-argument expansion, such as F(G(H(x))).

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_MACRO_EXPANSIONS

constexpr foundation::usize ludus::tooling::shader_language::MAX_MACRO_EXPANSIONS = foundation::usize{1} << 18
Most macro expansions performed while preprocessing one translation unit.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_SYNTHESIZED_BYTES

constexpr foundation::usize ludus::tooling::shader_language::MAX_SYNTHESIZED_BYTES = foundation::usize{1} << 20
Most bytes of token spellings created by #, ## and configuration values.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_CONFIGURATION_VALUES

constexpr foundation::usize ludus::tooling::shader_language::MAX_CONFIGURATION_VALUES = 256
Most configuration values in one request.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_CONFIGURATION_TEXT_BYTES

constexpr foundation::usize ludus::tooling::shader_language::MAX_CONFIGURATION_TEXT_BYTES = 1024
Longest configuration value name or value text, in bytes.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_DIAGNOSTICS

constexpr foundation::usize ludus::tooling::shader_language::MAX_DIAGNOSTICS = 256
Most diagnostics retained for one request; later ones are counted as dropped.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

MAX_DIAGNOSTIC_MESSAGE_BYTES

constexpr foundation::usize ludus::tooling::shader_language::MAX_DIAGNOSTIC_MESSAGE_BYTES = 256
Longest retained diagnostic message, in bytes; longer messages are clipped.

Related types: foundation::usize

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/limits.hpp

NO_EXPANSION

constexpr foundation::uint32 ludus::tooling::shader_language::NO_EXPANSION = 0xffffffffU
Token::ExpansionIndex of a token that does not come from a macro expansion.

Related types: foundation::uint32

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/token.hpp

Functions

GetDiagnosticCodeName

std::string_view ludus::tooling::shader_language::GetDiagnosticCodeName(DiagnosticCode code) noexcept
Return the stable kebab-case name of a code, such as unknown-directive.

Returns

An empty view for a value outside the enumerators.

Related types: DiagnosticCode

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/diagnostic.hpp

Preprocess

Status ludus::tooling::shader_language::Preprocess(const PreprocessRequest &request, PreprocessResult &outResult) noexcept
Preprocess the root file of a snapshot.
Supports #include "path" of .luslh headers, #pragma once, object-like and function-like #define with # and ##, #undef, #if, #ifdef, #ifndef, #elif, #else, #endif, defined and #error. It departs from C where docs/modules/tooling/shader-language.md says so: an undefined identifier in a condition and an unknown name tested by defined are errors, unary ! does not exist, macros are not variadic and #line is reserved.
The function is deterministic: equal requests produce equal results on every host. It is reentrant and keeps no state between calls.
ParameterDescription
request
Snapshot, root file and configuration values; borrowed for the call.
outResult
Receives the result; any previous contents are replaced.

Returns

The same value as outResult.Outcome.

Related types: Status · PreprocessRequest · PreprocessResult

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/preprocessor.hpp

GetTokenSpelling

std::string_view ludus::tooling::shader_language::GetTokenSpelling(const PreprocessRequest &request, const PreprocessResult &result, const Token &token) noexcept
Return the spelling of a token from a successful Preprocess.
ParameterDescription
request
The request that produced result; its file texts must still be alive.
result
The result that holds token.
token
A token of result.

Returns

The spelling, or an empty view when the token does not belong to this request and result.

Related types: PreprocessRequest · PreprocessResult · Token

Declared in modules/tooling/shader_language/include/ludus/tooling/shader_language/preprocessor.hpp