Crate nwnrs_nwscript

Expand description

§nwnrs-nwscript

nwnrs-nwscript is the workspace’s pure Rust NWScript frontend and compiler toolchain. It depends on nwnrs-types for shared IO and resource vocabulary, but owns the language pipeline itself.

§Scope

source loading and preprocessing
lexing, parsing, semantic analysis, and optimization
emission of NCS and NDB artifacts
NCS asm and disassembly through the upstream-style nwasm text layer
a lightweight NCS VM and test-runner layer for exercising compiled scripts
typed vocabulary for NWScript-related binary formats

§Internal Structure

source and preprocess: source loading and include handling
lexer, token, and parser: tokenization and syntax construction
ast, hir, sema, and ir: progressively richer semantic and lowered program forms
opt and codegen: optimization and NCS emission
ncs, ndb, and nwasm: binary artifact support plus text asm and disasm
vm: lightweight bytecode execution and action-command test harness
diag, langspec, and hash: diagnostics, builtin language specification, and NWScript-specific string hashing

§Public Surface by Stage

§Source loading and preprocessing

ScriptResolver
SourceBundle
SourceFile
SourceId
SourceMap
SourceLocation
SourceLoadOptions
SourceError
PreprocessedSource
PreprocessError
IncludeDirective
load_source_bundle
preprocess_source_bundle

§Lexing and parsing

Lexer
LexerError
Token
TokenKind
Keyword
MAX_TOKEN_LENGTH
ParseError
ParserError
ResolvedParseError
parse_bytes
parse_text
parse_tokens
parse_source
parse_source_bundle
lex_bytes
lex_text
lex_source

§Syntax-layer vocabulary

Script
TopLevelItem
Declaration
FunctionDecl
StructDecl
StructFieldDecl
Parameter
TypeSpec
TypeKind
Stmt
SimpleStmt
BlockStmt
IfStmt
ForStmt
WhileStmt
DoWhileStmt
SwitchStmt
CaseStmt
DefaultStmt
ReturnStmt
ExpressionStmt
Expr
ExprKind
UnaryOp
BinaryOp
AssignmentOp
VarDeclarator
MagicLiteral
NamedItem

§Semantic and lowered representations

SemanticModel
SemanticFunction
SemanticGlobal
SemanticStruct
SemanticField
SemanticParameter
SemanticType
SemanticOptions
SemanticError
HirModule
HirFunction
HirStmt
HirExpr
HirExprKind
HirStruct
HirField
HirGlobal
HirLocal
HirLocalId
HirLocalKind
HirValueRef
HirBlock
HirParameter
HirCallTarget
HirDeclarator
HirDeclareStmt
HirIfStmt
HirForStmt
HirDoWhileStmt
HirReturnStmt
HirSwitchStmt
HirLowerError
IrModule
IrFunction
IrBlock
IrBlockId
IrInstruction
IrTerminator
IrValueId
IrLocalId
IrGlobal
IrLowerError
analyze_script
analyze_script_with_options
lower_to_hir
lower_hir_to_ir

§Builtins and language specification

LangSpec
LangSpecError
BuiltinType
BuiltinFunction
BuiltinParameter
BuiltinConstant
BuiltinValue
DEFAULT_LANGSPEC_SCRIPT_NAME
NW_SCRIPT_SOURCE_RES_TYPE
load_langspec
parse_langspec
parse_langspec_bytes
parse_langspec_from_source_map

§Compile and optimization

CompileOptions
CompileArtifacts
CompileError
CodegenError
CompilerErrorCode
OptimizationLevel
compile_script
compile_script_with_source_map
compile_source_bundle
compile_hir_to_ncs

§Artifacts: `NCS`, `NDB`, and asm

NCS_HEADER
NCS_BINARY_HEADER_SIZE
NCS_OPERATION_BASE_SIZE
NcsHeader
NcsHeaderError
NcsInstruction
NcsOpcode
NcsAuxCode
NcsReadError
NcsAsmError
NcsAsmLine
NcsDisassemblyOptions
Ndb
NdbFile
NdbFunction
NdbLine
NdbStruct
NdbStructField
NdbType
NdbVariable
NdbError
decode_ncs_header
decode_ncs_instructions
encode_ncs_instructions
disassemble_ncs
render_disassembly_lines
render_ncs_disassembly
render_ncs_disassembly_with_ndb
assemble_ncs_bytes
assemble_ncs_text
read_ndb
parse_ndb_str
write_ndb

§Compiler sessions

CompilerSession
CompilerSessionError
CompilerSessionOptions

§Compiler driver

CompilerHost
CompilerHostError
CompilerDriverOptions
CompilerDriverError
CompileFileOutcome
compile_file_with_host
FileSystemScriptResolver
DirectoryCompilerHost
BatchCompileOptions
BatchCompileEntry
BatchCompileStatus
BatchCompileReport
BatchCompileError
compile_paths

§Graphviz

render_script_graphviz

§VM and test execution

Vm
VmRunOptions
VmScript
VmSituation
VmStepOutcome
VmTraceEvent
VmTraceHook
VmValue
VmObjectId
VmEngineStructureComparer
VmEngineStructureFactory
VmEngineStructureValue
VmFunctionInfo
VmCommandHandler
VmError
VmSourceLocation

For compiled scripts that include user-function calls, prefer the NDB-backed execution path (VmScript::from_bytes_with_ndb, Vm::run_bytes_with_ndb, or Vm::run_function_bytes) so the VM can recover callee stack layouts. The direct named-function runner also boots global initializers automatically for main() and StartingConditional() entry loaders. The debugger-oriented VM surface also supports single-step execution plus step_over, step_out, run_until_offset, run_until_function, and run_until_line when attached NDB metadata is available.

§Miscellaneous semantic helpers

Span
nwscript_string_hash
nwscript_string_hash_bytes

§Logical Edges

the crate intentionally exposes multiple representations instead of pretending parsing and compilation are one stage
LangSpec is part of normal compilation, not an optional afterthought
HIR and IR are real public control points
nwasm is both an artifact boundary and a debugging surface
source loading and include handling are operationally significant

§See also

nwnrs_types::resman, which provides the resource layer through which source and compiled script files are typically loaded
nwnrs_types::install, which resolves the install root and language root needed to locate nwscript.nss for compilation

§Why This Crate Exists

The point of nwnrs-types is to make the language subsystem inspectable and operable at every meaningful stage, from raw source bundle through lowered IR and into bytecode and debug artifacts.

Modules§

prelude: Common imports for consumers of this crate.

Structs§

BatchCompileEntry: One per-input result from a batch compile run.
BatchCompileOptions: Options controlling multi-file directory and file compilation.
BatchCompileReport: Summary of one batch compile run.
BlockStmt: One compound block.
BuiltinConstant: One builtin constant declaration.
BuiltinFunction: One builtin function declaration.
BuiltinParameter: One builtin function parameter.
CaseStmt: One case label.
CodegenError: One pure-Rust code generation failure.
CompileArtifacts: Compiler outputs produced in memory.
CompileOptions: One compilation request.
CompilerDriverOptions: Options controlling one callback-driven compiler invocation.
CompilerHostError: Errors returned while resolving or writing through a callback-driven compiler host.
CompilerSession: One reusable pure-Rust compiler session backed by a script resolver.
CompilerSessionOptions: Configuration for one reusable NWScript compiler session.
Declaration: One variable declaration statement.
DefaultStmt: One default label.
DirectoryCompilerHost: One directory-backed compiler host that reads source files from filesystem roots and writes outputs back to disk.
DoWhileStmt: One do ... while statement.
Expr: One expression in NWScript source.
ExpressionStmt: One expression statement.
FileSystemScriptResolver: One filesystem-backed source resolver that searches one or more root directories.
ForStmt: One for statement.
FunctionDecl: One parsed function declaration or definition.
HirBlock: One lowered block.
HirDeclarator: One lowered declared local.
HirDeclareStmt: One lowered declaration statement.
HirDoWhileStmt: One lowered do/while.
HirExpr: One lowered expression.
HirField: One lowered structure field.
HirForStmt: One lowered for.
HirFunction: One lowered function.
HirGlobal: One lowered global variable.
HirIfStmt: One lowered if.
HirLocal: One lowered local slot.
HirLocalId: One function-local identifier.
HirLowerError: One HIR lowering failure.
HirModule: One lowered HIR module ready for further compiler passes.
HirParameter: One lowered function parameter.
HirReturnStmt: One lowered return.
HirStruct: One lowered structure definition.
HirSwitchStmt: One lowered switch.
HirWhileStmt: One lowered while.
IfStmt: One if statement.
InMemoryScriptResolver: An in-memory script resolver used for tests and fixture loading.
IncludeDirective: One #include "..." directive.
IncludeEdge: One include relationship discovered while traversing source files.
IrBlock: One basic block.
IrBlockId: One block id.
IrFunction: One lowered function.
IrGlobal: One lowered global.
IrLocalId: One local slot id.
IrLowerError: One HIR-to-IR lowering failure.
IrModule: One lowered IR module ready for code generation.
IrValueId: One SSA-like transient value id.
LangSpec: Parsed builtin declarations from nwscript.nss.
Lexer: Lexes NWScript source using the upstream compiler’s token vocabulary.
LexerError: A lexical error returned while scanning NWScript source text.
MacroDefinition: One object-like #define captured during preprocessing.
NamedItem: One variable or field name plus span.
NcsAsmLine: One decoded disassembly line.
NcsDisassemblyOptions: Options controlling NCS disassembly rendering.
NcsHeader: Fixed metadata extracted from the leading bytes of an NCS file.
NcsInstruction: One decoded NCS instruction.
Ndb: Parsed contents of an NDB V1.0 file.
NdbFile: One file entry in an NDB file table.
NdbFunction: One function entry in an NDB file.
NdbLine: One line mapping entry in an NDB file.
NdbStruct: One struct entry in an NDB file.
NdbStructField: One struct field entry in an NDB file.
NdbVariable: One variable entry in an NDB file.
Parameter: One parsed parameter declaration.
ParserError: One parser error aligned to the upstream compiler’s diagnostic space.
PreprocessedSource: One preprocessed token stream plus the macros captured while producing it.
ReturnStmt: One return statement.
Script: One parsed NWScript translation unit.
SemanticError: One semantic-analysis error aligned to the upstream compiler’s diagnostic space.
SemanticField: One resolved structure field.
SemanticFunction: One resolved function signature.
SemanticGlobal: One resolved global variable.
SemanticModel: Semantic facts collected from one script.
SemanticOptions: Options controlling semantic analysis checks.
SemanticParameter: One resolved function parameter.
SemanticStruct: One resolved user-defined structure.
SimpleStmt: One statement carrying only a span.
SourceBundle: One loaded root script plus all transitively discovered include files.
SourceFile: One loaded source file plus its line-start table.
SourceId: Identifies one loaded NWScript source file within a compilation session.
SourceLoadOptions: Options controlling source loading and include traversal.
SourceLocation: A one-based line and column location inside a source file.
SourceMap: A collection of loaded source files indexed by both id and normalized name.
Span: A half-open byte span within one source file.
StructDecl: One user-defined structure declaration.
StructFieldDecl: One structure field declaration statement.
SwitchStmt: One switch statement.
Token: One token plus its source span and normalized payload.
TypeSpec: One parsed type specifier.
UnknownCompilerErrorCode: An error returned when a numeric compiler error code is not recognized.
UnknownNcsAuxCode: An error returned when converting an auxcode byte to NcsAuxCode.
UnknownNcsOpcode: An error returned when converting an opcode byte to NcsOpcode.
VarDeclarator: One declared variable, optionally with an initializer.
Vm: One command-dispatch table used to execute ACTION opcodes.
VmFunctionInfo: One debugger-visible function range derived from attached NDB metadata.
VmRunOptions: One set of optional execution controls for a VM run.
VmScript: One executable NCS script plus its VM runtime state.
VmSituation: One deferred NWScript action captured by STORESTATE.
VmSourceLocation: One debugger-visible source location derived from attached NDB metadata.
VmTraceEvent: One instruction-dispatch trace event emitted by the VM.
WhileStmt: One while statement.

Enums§

AssignmentOp: One assignment operator.
BatchCompileError: Errors returned before or outside individual compile attempts in batch mode.
BatchCompileStatus: One status emitted for a batch compile input.
BinaryOp: One binary operator.
BuiltinType: One builtin NWScript type defined by nwscript.nss.
BuiltinValue: One literal builtin value extracted from the language spec.
CompileError: One compilation failure across analysis, lowering, or code generation.
CompileFileOutcome: Result of one callback-driven compile request.
CompilerDriverError: Errors returned while executing one callback-driven compile request.
CompilerErrorCode: Stable compiler and VM error codes used by the upstream NWScript compiler.
CompilerSessionError: Errors returned while using one reusable compiler session.
ExprKind: One expression shape.
HirCallTarget: One resolved call target.
HirExprKind: One lowered expression kind.
HirLocalKind: One lowered local kind.
HirStmt: One lowered statement.
HirValueRef: One resolved value reference.
IrCallArgument: One lowered call argument.
IrInstruction: One stack-oriented IR instruction.
IrTerminator: One control-flow terminator.
Keyword: One NWScript keyword or builtin token recognized during lexing.
LangSpecError: Errors returned while bootstrapping the builtin language spec.
Literal: One literal expression.
MagicLiteral: One magic macro literal preserved in syntax.
NcsAsmError: Errors returned while rendering or parsing NCS asm text.
NcsAuxCode: One NWScript VM aux code.
NcsHeaderError: Errors returned while decoding the fixed NCS header.
NcsOpcode: One NWScript VM opcode.
NcsReadError: Errors returned while decoding a full NCS bytecode stream.
NdbError: Errors returned while parsing or writing NDB V1.0.
NdbType: A type abbreviation used in an NDB V1.0 file.
OptimizationLevel: Optimization levels accepted by the pure-Rust compiler pipeline.
ParseError: One parser failure.
PreprocessError: Errors returned while scanning include directives across multiple files.
ResolvedParseError: One parser failure after source resolution and preprocessing.
SemanticType: One resolved semantic type.
SourceError: Errors returned while resolving or loading source files.
Stmt: One statement in NWScript source.
TokenKind: One lexical token in NWScript source.
TopLevelItem: One top-level NWScript item.
TypeKind: One NWScript type kind recognized syntactically by the parser.
UnaryOp: One unary operator.
VmEngineStructureValue: One engine-structure payload carried by a stack value.
VmError: Errors returned while executing NCS bytecode.
VmStepOutcome: One result returned after executing exactly one instruction.
VmValue: One runtime stack value.

Constants§

DEFAULT_LANGSPEC_SCRIPT_NAME: Default logical script name for the builtin NWScript language definition.
DEFAULT_MAX_INCLUDE_DEPTH: The upstream default include-depth limit.
MAX_TOKEN_LENGTH: Maximum token payload length used by the upstream compiler.
NCS_AUXCODE_OFFSET: Byte offset of the auxcode field inside an instruction.
NCS_BINARY_HEADER_SIZE: Total size of the fixed binary header, including the encoded bytecode size.
NCS_EXTRA_DATA_OFFSET: Byte offset of the extra-data section inside an instruction.
NCS_HEADER: Text prefix of an NCS V1.0 bytecode stream.
NCS_OPCODE_OFFSET: Byte offset of the opcode field inside an instruction.
NCS_OPERATION_BASE_SIZE: Size of the opcode-plus-auxcode instruction prefix.
NW_SCRIPT_SOURCE_RES_TYPE: The built-in NWN resource type used for NWScript source files.

Traits§

CompilerHost: One callback-driven host for loading NWScript source and receiving compiler outputs.
ScriptResolver: Loads script source text by logical name and resource type.

Functions§

analyze_script: Performs semantic analysis on one parsed script.
analyze_script_with_options: Performs semantic analysis on one parsed script with explicit options.
assemble_ncs_bytes: Parses assembleable NCS asm text and encodes it into bytecode without the fixed NCS file header.
assemble_ncs_text: Parses assembleable NCS asm text into decoded instructions.
compile_file_with_host: Compiles one logical script through a callback-driven host.
compile_hir_to_ncs: Compiles one lowered HIR module to NCS.
compile_paths: Collects and compiles a set of script files and directories.
compile_script: Compiles one parsed script through semantic analysis, HIR lowering, and O0 NCS emission.
compile_script_with_source_map: Compiles one parsed script and emits NDB when a source map is available.
compile_source_bundle: Parses and compiles one already-loaded source bundle with NDB output.
decode_ncs_header: Decodes the fixed binary header of an NCS V1.0 file.
decode_ncs_instructions: Decodes a full NCS V1.0 bytecode stream into individual instructions.
disassemble_ncs: Decodes a full NCS stream into instruction-shaped disassembly lines.
encode_ncs_instructions: Encodes one NCS V1.0 instruction stream with the fixed binary header.
lex_bytes: Lexes a byte buffer associated with source_id.
lex_source: Lexes the contents of one source file.
lex_text: Lexes a string slice associated with source_id.
load_langspec: Loads nwscript.nss through a source resolver and parses the builtin declarations.
load_source_bundle: Loads a root script and recursively discovers its #include dependencies.
lower_hir_to_ir: Lowers HIR into the compiler IR used by later codegen work.
lower_to_hir: Lowers one semantically-valid script into typed HIR.
nwscript_string_hash: Returns the exact NWScript runtime hash for a UTF-8 string slice.
nwscript_string_hash_bytes: Returns the exact NWScript runtime hash for a cooked byte string.
parse_bytes: Lexes and parses a byte buffer associated with source_id.
parse_langspec: Parses builtin declarations from one already-loaded source file.
parse_langspec_bytes: Parses builtin declarations from one already-loaded byte buffer.
parse_langspec_from_source_map: Parses builtin declarations from root_id in source_map.
parse_ndb_str: Parses NDB V1.0 from a string slice.
parse_resolved_script: Resolves, preprocesses, and parses one named root script.
parse_source: Lexes and parses one source file.
parse_source_bundle: Parses one already-loaded source bundle after include traversal and macro expansion.
parse_text: Lexes and parses a text buffer associated with source_id.
parse_tokens: Parses one already-tokenized NWScript translation unit.
preprocess_source_bundle: Preprocesses one already-loaded source bundle into a token stream.
read_ndb: Parses NDB V1.0 from a buffered reader.
render_disassembly_lines: Renders already-decoded disassembly lines into plain text.
render_ncs_disassembly: Renders a full NCS stream into stable human-readable disassembly text.
render_ncs_disassembly_with_ndb: Renders a full NCS stream into NDB-aware disassembly text.
render_script_graphviz: Renders one parsed script as Graphviz DOT.
write_ndb: Writes an NDB V1.0 file in upstream-compatible textual form.

Type Aliases§

VmCommandHandler: One immutable ACTION handler.
VmEngineStructureComparer: One engine-structure equality hook used by EQ and NEQ.
VmEngineStructureFactory: One engine-structure default factory used by RSADD.
VmObjectId: One opaque object id visible to the VM runtime.
VmTraceHook: One instruction trace hook invoked before the VM executes each opcode.