load_string

Stable function · Document I/O

Tier: stable · Kind: function · Topic: Document I/O

Julia	TypeScript	Python	Rust	Go
`load_string`	`loadString`	`load_string`	`load_string`	`LoadString`

Julia

load_string(json::AbstractString; base_path, metaparameters, injected_imports)
load_string(io::IO; base_path, metaparameters, injected_imports)

load_string(json::AbstractString; base_path=nothing, metaparameters=Dict{String,Int}()) -> EsmFile
load_string(io::IO; base_path=nothing, metaparameters=Dict{String,Int}()) -> EsmFile

Parse an ESM document from JSON TEXT — held as a String, or streamed from an IO the method reads to a string first (the ::IO method is a sanctioned Julia decoration on the canonical load_string, not a fourth entry point: JSON3.read and read accept both shapes too).

Runs the SAME pipeline load_path and load_document run — _load_document: top-level {ref} inlining, version gates, schema validation, template lowering, coercion, and nested subsystem-ref resolution. (Before that was shared, a stream-loaded document kept its subsystem refs as unresolved SubsystemRefs, which flatten silently SKIPS: the same document loaded from a stream flattened to a strictly smaller system, with no error.) base_path anchors relative expression_template_imports refs and nested {ref}s (esm-spec §9.7.2, §4.7), defaulting to pwd() for that; left at nothing the document has no location of its own, so a relative coupling_import ref resolves against flatten’s own base_path instead (§10.10 -> §4.7). metaparameters binds the document’s open metaparameters at the loader API (esm-spec §9.7.6).

Source

Example (load)

doc = load_path(joinpath(FIXTURES, "decay.esm"))
@assert doc isa EsmFile
@assert collect(keys(doc.models)) == ["Decay"]

# The same document from a JSON string already in memory.
json = read(joinpath(FIXTURES, "decay.esm"), String)
from_string = load_string(json)
@assert collect(keys(from_string.models)) == ["Decay"]

From docs/api/examples/julia/documents.jl

Example (load_errors)

# Text that is not JSON at all raises a ParseError...
try
    load_string("{not json")
    error("expected a ParseError")
catch e
    @assert e isa ParseError
    println(sprint(showerror, e))
end

# ...and JSON that breaks the schema raises a SchemaValidationError, whose
# `errors` field lists each failure.
try
    load_string("""{"esm": "1.0.0"}""")
    error("expected a SchemaValidationError")
catch e
    @assert e isa SchemaValidationError
    @assert !isempty(e.errors)
    println(sprint(showerror, e))
end

From docs/api/examples/julia/documents.jl

TypeScript

function loadString(json: string, options?: LoadOptions): EsmFile

Parse an ESM document from JSON TEXT.

Parameters

json — The document as a JSON string
options — Optional load-time settings (see LoadOptions )

Returns

Typed EsmFile object

Throws

ParseError — When JSON parsing fails or version is incompatible
SchemaValidationError — When schema validation fails

Source

Example (load)

// From a file on disk:
const doc = loadPath(decayPath)
assert.deepEqual(Object.keys(doc.models ?? {}), ['Decay'])
assert.equal(doc.metadata.name, 'Decay')

// From JSON text you already hold (a fetch response, a database row, ...):
const text = readFileSync(decayPath, 'utf8')
const same = loadString(text)
const model = same.models!.Decay
// A `models` entry is a Model or, before `resolveSubsystemRefs`, a `{ ref }` mount.
assert.ok(!('ref' in model))
assert.deepEqual(Object.keys(model.variables), ['N', 'lambda', 'half_life'])

From docs/api/examples/typescript/load.ts

Python

load_string(json_text: str, *, metaparameters: dict[str, int] | None = None, base_path: str | os.PathLike[str] | None = None) -> EsmFile

Parse an ESM document from JSON TEXT.

Parameters

json_text (str) — The document as a JSON string.

Source

Example (load)

doc = earthsci_ast.load_path(FIXTURES / "decay.esm")
assert list(doc.models) == ["Decay"]

text = (FIXTURES / "decay.esm").read_text()
same = earthsci_ast.load_string(text)
assert list(same.models["Decay"].variables) == ["N", "lambda", "half_life"]

From docs/api/examples/python/documents.py

Rust

pub fn load_string(json_str: &str) -> Result<EsmFile, EsmError>

Load and parse an ESM file from JSON string

This function performs both JSON parsing and schema validation. It will throw an error for malformed JSON or schema violations.

Arguments

json_str - The JSON string to parse

Returns

Ok(EsmFile) - Successfully parsed and validated ESM file
Err(EsmError) - Parse error or schema validation error

Examples

use earthsci_ast::load_string;

let json = r#"
{
  "esm": "1.0.0",
  "metadata": {
    "name": "test_model"
  },
  "models": {
    "simple": {
      "variables": {},
      "equations": []
    }
  }
}
"#;

let esm_file = load_string(json).expect("Failed to load ESM file");
assert_eq!(esm_file.esm, "1.0.0");

Source · Rust docs

Example (load)

let doc = load_path(fixture("decay.esm"))?;
let models = doc.models.as_ref().expect("decay.esm has models");
assert_eq!(models.keys().collect::<Vec<_>>(), ["Decay"]);
assert_eq!(doc.metadata.name.as_deref(), Some("Decay"));

let text = std::fs::read_to_string(fixture("decay.esm"))?;
let same = load_string(&text)?;
assert_eq!(same.models.as_ref().unwrap().len(), 1);

// A document that is not valid JSON is an error, not a panic.
assert!(load_string("{ not json").is_err());

From docs/api/examples/rust/load.rs

func LoadString(jsonStr string, opts ...LoadOption) (*ESMFile, error)

LoadString parses an ESM file from JSON TEXT and validates it against the JSON schema

Source · Go docs

Example (load)

doc, err := esm.LoadPath(fixture("decay.esm"))
if err != nil {
	log.Fatal(err)
}
fmt.Println(sortedKeys(doc.Models))

text, err := os.ReadFile(fixture("decay.esm"))
if err != nil {
	log.Fatal(err)
}
fromText, err := esm.LoadString(string(text))
if err != nil {
	log.Fatal(err)
}
fmt.Println(fromText.Metadata.Name, len(fromText.Models["Decay"].Equations))

From docs/api/examples/go/load_test.go