Skip to main content

nwnrs_nwscript/
lib.rs

1#![forbid(unsafe_code)]
2#![doc = "# nwnrs-nwscript\n\n`nwnrs-nwscript` is the workspace\'s pure Rust `NWScript` frontend and compiler\ntoolchain. It depends on `nwnrs-types` for shared IO and resource vocabulary,\nbut owns the language pipeline itself.\n\n## Scope\n\n- source loading and preprocessing\n- lexing, parsing, semantic analysis, and optimization\n- emission of `NCS` and `NDB` artifacts\n- `NCS` asm and disassembly through the upstream-style `nwasm` text layer\n- a lightweight `NCS` VM and test-runner layer for exercising compiled scripts\n- typed vocabulary for NWScript-related binary formats\n\n## Internal Structure\n\n- `source` and `preprocess`: source loading and include handling\n- `lexer`, `token`, and `parser`: tokenization and syntax construction\n- `ast`, `hir`, `sema`, and `ir`: progressively richer semantic and lowered\n  program forms\n- `opt` and `codegen`: optimization and NCS emission\n- `ncs`, `ndb`, and `nwasm`: binary artifact support plus text asm and disasm\n- `vm`: lightweight bytecode execution and action-command test harness\n- `diag`, `langspec`, and `hash`: diagnostics, builtin language specification,\n  and NWScript-specific string hashing\n\n## Public Surface by Stage\n\n### Source loading and preprocessing\n\n- `ScriptResolver`\n- `SourceBundle`\n- `SourceFile`\n- `SourceId`\n- `SourceMap`\n- `SourceLocation`\n- `SourceLoadOptions`\n- `SourceError`\n- `PreprocessedSource`\n- `PreprocessError`\n- `IncludeDirective`\n- `load_source_bundle`\n- `preprocess_source_bundle`\n\n### Lexing and parsing\n\n- `Lexer`\n- `LexerError`\n- `Token`\n- `TokenKind`\n- `Keyword`\n- `MAX_TOKEN_LENGTH`\n- `ParseError`\n- `ParserError`\n- `ResolvedParseError`\n- `parse_bytes`\n- `parse_text`\n- `parse_tokens`\n- `parse_source`\n- `parse_source_bundle`\n- `lex_bytes`\n- `lex_text`\n- `lex_source`\n\n### Syntax-layer vocabulary\n\n- `Script`\n- `TopLevelItem`\n- `Declaration`\n- `FunctionDecl`\n- `StructDecl`\n- `StructFieldDecl`\n- `Parameter`\n- `TypeSpec`\n- `TypeKind`\n- `Stmt`\n- `SimpleStmt`\n- `BlockStmt`\n- `IfStmt`\n- `ForStmt`\n- `WhileStmt`\n- `DoWhileStmt`\n- `SwitchStmt`\n- `CaseStmt`\n- `DefaultStmt`\n- `ReturnStmt`\n- `ExpressionStmt`\n- `Expr`\n- `ExprKind`\n- `UnaryOp`\n- `BinaryOp`\n- `AssignmentOp`\n- `VarDeclarator`\n- `MagicLiteral`\n- `NamedItem`\n\n### Semantic and lowered representations\n\n- `SemanticModel`\n- `SemanticFunction`\n- `SemanticGlobal`\n- `SemanticStruct`\n- `SemanticField`\n- `SemanticParameter`\n- `SemanticType`\n- `SemanticOptions`\n- `SemanticError`\n- `HirModule`\n- `HirFunction`\n- `HirStmt`\n- `HirExpr`\n- `HirExprKind`\n- `HirStruct`\n- `HirField`\n- `HirGlobal`\n- `HirLocal`\n- `HirLocalId`\n- `HirLocalKind`\n- `HirValueRef`\n- `HirBlock`\n- `HirParameter`\n- `HirCallTarget`\n- `HirDeclarator`\n- `HirDeclareStmt`\n- `HirIfStmt`\n- `HirForStmt`\n- `HirDoWhileStmt`\n- `HirReturnStmt`\n- `HirSwitchStmt`\n- `HirLowerError`\n- `IrModule`\n- `IrFunction`\n- `IrBlock`\n- `IrBlockId`\n- `IrInstruction`\n- `IrTerminator`\n- `IrValueId`\n- `IrLocalId`\n- `IrGlobal`\n- `IrLowerError`\n- `analyze_script`\n- `analyze_script_with_options`\n- `lower_to_hir`\n- `lower_hir_to_ir`\n\n### Builtins and language specification\n\n- `LangSpec`\n- `LangSpecError`\n- `BuiltinType`\n- `BuiltinFunction`\n- `BuiltinParameter`\n- `BuiltinConstant`\n- `BuiltinValue`\n- `DEFAULT_LANGSPEC_SCRIPT_NAME`\n- `NW_SCRIPT_SOURCE_RES_TYPE`\n- `load_langspec`\n- `parse_langspec`\n- `parse_langspec_bytes`\n- `parse_langspec_from_source_map`\n\n### Compile and optimization\n\n- `CompileOptions`\n- `CompileArtifacts`\n- `CompileError`\n- `CodegenError`\n- `CompilerErrorCode`\n- `OptimizationLevel`\n- `compile_script`\n- `compile_script_with_source_map`\n- `compile_source_bundle`\n- `compile_hir_to_ncs`\n\n### Artifacts: `NCS`, `NDB`, and asm\n\n- `NCS_HEADER`\n- `NCS_BINARY_HEADER_SIZE`\n- `NCS_OPERATION_BASE_SIZE`\n- `NcsHeader`\n- `NcsHeaderError`\n- `NcsInstruction`\n- `NcsOpcode`\n- `NcsAuxCode`\n- `NcsReadError`\n- `NcsAsmError`\n- `NcsAsmLine`\n- `NcsDisassemblyOptions`\n- `Ndb`\n- `NdbFile`\n- `NdbFunction`\n- `NdbLine`\n- `NdbStruct`\n- `NdbStructField`\n- `NdbType`\n- `NdbVariable`\n- `NdbError`\n- `decode_ncs_header`\n- `decode_ncs_instructions`\n- `encode_ncs_instructions`\n- `disassemble_ncs`\n- `render_disassembly_lines`\n- `render_ncs_disassembly`\n- `render_ncs_disassembly_with_ndb`\n- `assemble_ncs_bytes`\n- `assemble_ncs_text`\n- `read_ndb`\n- `parse_ndb_str`\n- `write_ndb`\n\n### Compiler sessions\n\n- `CompilerSession`\n- `CompilerSessionError`\n- `CompilerSessionOptions`\n\n### Compiler driver\n\n- `CompilerHost`\n- `CompilerHostError`\n- `CompilerDriverOptions`\n- `CompilerDriverError`\n- `CompileFileOutcome`\n- `compile_file_with_host`\n- `FileSystemScriptResolver`\n- `DirectoryCompilerHost`\n- `BatchCompileOptions`\n- `BatchCompileEntry`\n- `BatchCompileStatus`\n- `BatchCompileReport`\n- `BatchCompileError`\n- `compile_paths`\n\n### Graphviz\n\n- `render_script_graphviz`\n\n### VM and test execution\n\n- `Vm`\n- `VmRunOptions`\n- `VmScript`\n- `VmSituation`\n- `VmStepOutcome`\n- `VmTraceEvent`\n- `VmTraceHook`\n- `VmValue`\n- `VmObjectId`\n- `VmEngineStructureComparer`\n- `VmEngineStructureFactory`\n- `VmEngineStructureValue`\n- `VmFunctionInfo`\n- `VmCommandHandler`\n- `VmError`\n- `VmSourceLocation`\n\nFor compiled scripts that include user-function calls, prefer the `NDB`-backed\nexecution path (`VmScript::from_bytes_with_ndb`, `Vm::run_bytes_with_ndb`, or\n`Vm::run_function_bytes`) so the VM can recover callee stack layouts. The\ndirect named-function runner also boots global initializers automatically for\n`main()` and `StartingConditional()` entry loaders. The debugger-oriented VM\nsurface also supports single-step execution plus `step_over`, `step_out`,\n`run_until_offset`, `run_until_function`, and `run_until_line` when attached\n`NDB` metadata is available.\n\n### Miscellaneous semantic helpers\n\n- `Span`\n- `nwscript_string_hash`\n- `nwscript_string_hash_bytes`\n\n## Logical Edges\n\n- the crate intentionally exposes multiple representations instead of\n  pretending parsing and compilation are one stage\n- `LangSpec` is part of normal compilation, not an optional afterthought\n- HIR and IR are real public control points\n- `nwasm` is both an artifact boundary and a debugging surface\n- source loading and include handling are operationally significant\n\n## See also\n\n- [`nwnrs_types::resman`](https://docs.rs/nwnrs-types/latest/nwnrs_types/resman/), which provides the resource\n  layer through which source and compiled script files are typically loaded\n- [`nwnrs_types::install`](https://docs.rs/nwnrs-types/latest/nwnrs_types/install/),\n  which resolves the install root and language root needed to locate\n  `nwscript.nss` for compilation\n\n## Why This Crate Exists\n\nThe point of `nwnrs-types` is to make the language subsystem inspectable and\noperable at every meaningful stage, from raw source bundle through lowered IR\nand into bytecode and debug artifacts.\n"include_str!("../README.md")]
3
4extern crate self as nwnrs_nwscript;
5
6mod ast;
7mod codegen;
8mod diag;
9mod driver;
10mod graphviz;
11mod hash;
12mod hir;
13mod int_literal;
14mod ir;
15mod langspec;
16mod lexer;
17mod ncs;
18mod ndb;
19mod nwasm;
20mod opt;
21mod parser;
22mod preprocess;
23mod sema;
24mod session;
25mod source;
26mod token;
27mod vm;
28
29pub use ast::*;
30pub use codegen::*;
31pub use diag::*;
32pub use driver::*;
33pub use graphviz::*;
34pub use hash::*;
35pub use hir::*;
36pub use ir::*;
37pub use langspec::*;
38pub use lexer::*;
39pub use ncs::*;
40pub use ndb::*;
41pub use nwasm::*;
42pub use parser::*;
43pub use preprocess::*;
44pub use sema::*;
45pub use session::*;
46pub use source::*;
47pub use token::*;
48pub use vm::*;
49
50/// Common imports for consumers of this crate.
51pub mod prelude {
52    pub use crate::{
53        AssignmentOp, BatchCompileEntry, BatchCompileError, BatchCompileOptions,
54        BatchCompileReport, BatchCompileStatus, BinaryOp, BlockStmt, BuiltinConstant,
55        BuiltinFunction, BuiltinParameter, BuiltinType, BuiltinValue, CaseStmt, CodegenError,
56        CompileArtifacts, CompileError, CompileFileOutcome, CompileOptions, CompilerDriverError,
57        CompilerDriverOptions, CompilerErrorCode, CompilerHost, CompilerHostError, CompilerSession,
58        CompilerSessionError, CompilerSessionOptions, DEFAULT_LANGSPEC_SCRIPT_NAME, Declaration,
59        DefaultStmt, DirectoryCompilerHost, DoWhileStmt, Expr, ExprKind, ExpressionStmt,
60        FileSystemScriptResolver, ForStmt, FunctionDecl, HirBlock, HirCallTarget, HirDeclarator,
61        HirDeclareStmt, HirDoWhileStmt, HirExpr, HirExprKind, HirField, HirForStmt, HirFunction,
62        HirGlobal, HirIfStmt, HirLocal, HirLocalId, HirLocalKind, HirLowerError, HirModule,
63        HirParameter, HirReturnStmt, HirStmt, HirStruct, HirSwitchStmt, HirValueRef, IfStmt,
64        IncludeDirective, IrBlock, IrBlockId, IrFunction, IrGlobal, IrInstruction, IrLocalId,
65        IrLowerError, IrModule, IrTerminator, IrValueId, Keyword, LangSpec, LangSpecError, Lexer,
66        LexerError, MAX_TOKEN_LENGTH, MagicLiteral, NCS_BINARY_HEADER_SIZE, NCS_HEADER,
67        NCS_OPERATION_BASE_SIZE, NW_SCRIPT_SOURCE_RES_TYPE, NamedItem, NcsAsmError, NcsAsmLine,
68        NcsAuxCode, NcsDisassemblyOptions, NcsHeader, NcsHeaderError, NcsInstruction, NcsOpcode,
69        NcsReadError, Ndb, NdbError, NdbFile, NdbFunction, NdbLine, NdbStruct, NdbStructField,
70        NdbType, NdbVariable, OptimizationLevel, Parameter, ParseError, ParserError,
71        PreprocessError, PreprocessedSource, ResolvedParseError, ReturnStmt, Script,
72        ScriptResolver, SemanticError, SemanticField, SemanticFunction, SemanticGlobal,
73        SemanticModel, SemanticOptions, SemanticParameter, SemanticStruct, SemanticType,
74        SimpleStmt, SourceBundle, SourceError, SourceFile, SourceId, SourceLoadOptions,
75        SourceLocation, SourceMap, Span, Stmt, StructDecl, StructFieldDecl, SwitchStmt, Token,
76        TokenKind, TopLevelItem, TypeKind, TypeSpec, UnaryOp, VarDeclarator, Vm, VmCommandHandler,
77        VmEngineStructureComparer, VmEngineStructureFactory, VmEngineStructureValue, VmError,
78        VmFunctionInfo, VmObjectId, VmRunOptions, VmScript, VmSituation, VmSourceLocation,
79        VmStepOutcome, VmTraceEvent, VmTraceHook, VmValue, WhileStmt, analyze_script,
80        analyze_script_with_options, assemble_ncs_bytes, assemble_ncs_text, compile_file_with_host,
81        compile_hir_to_ncs, compile_paths, compile_script, compile_script_with_source_map,
82        compile_source_bundle, decode_ncs_header, decode_ncs_instructions, disassemble_ncs,
83        encode_ncs_instructions, lex_bytes, lex_source, lex_text, load_langspec,
84        load_source_bundle, lower_hir_to_ir, lower_to_hir, nwscript_string_hash,
85        nwscript_string_hash_bytes, parse_bytes, parse_langspec, parse_langspec_bytes,
86        parse_langspec_from_source_map, parse_ndb_str, parse_resolved_script, parse_source,
87        parse_source_bundle, parse_text, parse_tokens, preprocess_source_bundle, read_ndb,
88        render_disassembly_lines, render_ncs_disassembly, render_ncs_disassembly_with_ndb,
89        render_script_graphviz, write_ndb,
90    };
91}