Documents and assembly

Splitting a model into files should preserve its relationships. Nexus Script distinguishes making definitions available from contributing them to output.

Import reusable definitions

Save these two files in the same folder:

Defaults.nxscript

Catalog Defaults {
    Product Standard {
        Currency: USD;
        PriceCents: 100;
        Title: "Standard product";
    }
}

Catalog.nxscript

module Defaults "Defaults.nxscript";

Catalog Shop {
    Product Notebook (Defaults.Standard) {
        Title: "Pocket notebook";
        PriceCents: 450;
    }
    Featured: @Notebook;
}

Compile Catalog to JSON. Notebook has its composed values. Defaults is available to the compiler, but is not a separate top-level output root.

module Defaults selects the root already named Defaults in the other file. It does not rename that root or introduce an arbitrary alias. To import all roots under their declared names, write module "Defaults.nxscript"; instead.

Imported definitions retain the dependencies needed by their own references. Those private dependencies do not automatically become public roots in the importing document.

Include output contributions

Add this file:

Seasonal.nxscript

Catalog Seasonal {
    Product Card { Title: "Greeting card"; PriceCents: 250; }
}

Then create an entry document:

Publication.nxscript

include "Catalog.nxscript";
include "Seasonal.nxscript";

Run:

NexusScript /input=Publication.nxscript /output=Publication.json

The artifact contains Shop and Seasonal. Each included document compiles in its own context; include does not splice source text or make one included document's names visible in another. Catalog still explicitly imports Defaults.

The artifact set means the entry document and the included documents whose definitions contribute to the result. Module dependencies and dialect files are not automatically part of this set.

Use both relationships when both are intended

Combined.nxscript

module Seasonal "Seasonal.nxscript";
include "Seasonal.nxscript";

Catalog Promotion {
    Featured: @Seasonal.Card;
}

The module makes Seasonal addressable; the include contributes its authored definitions to output. The same included file contributes once even when several include paths reach it. A separate definition composed from its content is still a separate definition.

Need	Declaration
Reference or compose from another file	module
Assemble that file's definitions into the artifact	include
Both access and output contribution	Both
Validate against domain rules	dialect

Paths, order, and conflicts

Put dependency declarations before definitions. Relative paths resolve from the declaring file, including dependencies of imported files. File extensions and descriptive filename components do not select a processor or dialect.

Included output is collected entry first, then includes in declaration order, recursively. Root names must be unique in the assembled artifact; include does not merge same-named roots. Nested names remain scoped to their owners.

Import collisions and dependency cycles produce diagnostics. They are not a mechanism for overriding definitions from an earlier import. Use explicit composition for that purpose.

Filename patterns

After an explicit arrangement works, a directory can supply several files:

include "catalogs/*.nxscript";
module "defaults/*.nxscript";
include recursive "catalogs/*.nxscript";

These are alternative header examples. A pattern applies to filenames; recursive also searches descendant directories. Matching files are processed in the source provider's returned order; the filesystem provider does not sort that enumeration. An existing folder with no matching files adds no dependencies; a missing folder is an error. The declaring document is excluded from its own pattern results. Explicit loading cycles still fail.

Named-root imports select a single file; do not combine a named root selector with a filename pattern. Use explicit paths when a particular order or exact membership matters to the consumer.

Continue with External values.