N4L API

N4LState

Mutable state for the N4L parser/compiler. Each parse session gets its own state object to avoid global mutable state.

N4LResult

Result of parsing N4L input.

Fields

• errors::Vector{String}: parse errors encountered
• warnings::Vector{String}: parse warnings encountered
• nd::NodeDirectory: the node directory populated by the parser
• state::N4LState: the final parser state

N4LParseError <: Exception

Exception thrown when the N4L parser encounters an unrecoverable error.

Fields

• message::String: description of the parse error

parse_n4l(input::String; verbose=false, config_dir=nothing, load_config=true) -> N4LResult

Parse N4L text and return the result. This is the main entry point.

• input: N4L source text
• verbose: print diagnostic output
• config_dir: path to SSTconfig directory (auto-detected if not given)
• load_config: whether to load SSTconfig arrow definitions

parse_n4l_file(filename::String; verbose=false, config_dir=nothing, load_config=true) -> N4LResult

Parse an N4L file and return the result.

parse_config_file(filename::String; st::N4LState=N4LState()) -> N4LState

Parse a single config file and register its arrows.

find_config_dir(search_paths=nothing) -> Union{String, Nothing}

Search for the SSTconfig directory. Checks:

1. SSTCONFIGPATH environment variable
2. ./SSTconfig, ../SSTconfig, ../../SSTconfig
3. Custom search_paths if provided

read_config_files(config_dir::String) -> Vector{String}

Return the list of config file paths from an SSTconfig directory.

has_errors(r::N4LResult) -> Bool

Return true if the parse result contains any errors.

has_warnings(r::N4LResult) -> Bool

Return true if the parse result contains any warnings.

N4L line role: an event or item declaration.

N4L line role: a relation (arrow) between items.

N4L line role: a section/chapter declaration.

N4L line role: a context assignment.

N4L line role: add to the current context.

N4L line role: subtract from the current context.

N4L line role: a blank line (separator).

N4L line role: a line alias definition (@label).

N4L line role: a lookup/back-reference ($label.n).

N4L line role: a composition (multi-part relation).

N4L line role: a result/output declaration.

N4LCompileResult

Summary of a compile operation.

compile_n4l!(store::MemoryStore, result::N4LResult) -> N4LCompileResult

Transfer parsed N4L nodes and edges from the parse result's NodeDirectory into the given store. Returns a summary of what was created.

compile_n4l_file!(store::MemoryStore, filepath::String;
                  config_dir=nothing, verbose=false) -> N4LCompileResult

Parse an N4L file and compile the result into the store.

compile_n4l_string!(store::MemoryStore, text::String;
                    config_dir=nothing, verbose=false) -> N4LCompileResult

Parse an N4L string and compile the result into the store.

N4LValidationResult

Result of validating N4L input without compiling to a store.

validate_n4l(text::String; config_dir=nothing, verbose=false) -> N4LValidationResult

Parse N4L text and report validation results without creating a store.

validate_n4l_file(filepath::String; config_dir=nothing, verbose=false) -> N4LValidationResult

Parse an N4L file and report validation results without creating a store.

n4l_summary(result::N4LResult; io::IO=stdout)

Print a human-readable summary of the parsed N4L result.

n4l_summary(cr::N4LCompileResult; io::IO=stdout)

Print a human-readable summary of a compile result.

Provenance

Metadata tracking the origin of a node or link.

set_provenance!(store::MemoryStore, nptr::NodePtr, prov::Provenance)

Attach provenance metadata to a node via EXPRESS annotation nodes. Creates annotation nodes linked via the note arrow.

get_provenance(store::MemoryStore, nptr::NodePtr) -> Union{Provenance, Nothing}

Retrieve provenance metadata from a node's EXPRESS annotations.

compile_n4l_with_provenance!(store::MemoryStore, text::String;
    source::String="<string>", author::String="", config_dir=nothing) -> N4LCompileResult

Like compilen4lstring! but attaches provenance to every created node.

n4l"..."

Parse an N4L string literal at runtime, returning an N4LResult. Uses the default SSTconfig if available, otherwise parses without config.

Examples

result = n4l"-section\n\n apple (contains) fruit\n"

result = n4l"""
-vocabulary

 apple (contains) fruit
 banana (contains) fruit
"""

n4l"..."config_dir

Parse an N4L string literal with a specific config directory.

Example

result = n4l"""
-section

 apple (contains) fruit
""""/path/to/SSTconfig"

@sst [store] begin ... end

Create a MemoryStore and execute a block of operations on it, returning the store. If a variable name is given, it is bound within the block; otherwise the store is accessible as s.

Examples

# Implicit variable `s`
store = @sst begin
    v1 = vertex!(s, "apple", "fruits")
    v2 = vertex!(s, "banana", "fruits")
    edge!(s, v1, "contains", v2)
end

# Explicit variable name
store = @sst g begin
    a = vertex!(g, "hello", "greetings")
    b = vertex!(g, "world", "greetings")
    edge!(g, a, "note", b)
end

@compile text
@compile store text
@compile text config_dir=path

Compile an N4L string into a MemoryStore. If no store is provided, a new one is created. Returns (store, compile_result).

Examples

# New store
store, result = @compile """
-section

 apple (contains) fruit
"""

# Into existing store
store = MemoryStore()
_, result = @compile store """
-section

 banana (contains) fruit
"""

@graph store begin
    "node1" -arrow-> "node2"
    ...
end

Build a graph declaratively. Each line in the block should be a call to vertex! or edge!, or use the DSL helpers.

Example

store = MemoryStore()
@graph store begin
    a = vertex!("apple", "fruits")
    b = vertex!("banana", "fruits")
    c = vertex!("fruit", "fruits")
    edge!(a, "contains", c)
    edge!(b, "contains", c)
end

Inside @graph, vertex! and edge! calls automatically use the store.