Node Specification Language#

The Node Specification Language (NSL) is SAMSON's string-based query language for selecting data graph nodes.

Use NSL when a selection should be expressible as a compact query string instead of only as C++ code. It is useful in the UI, in scripts, and in extension code that wants to accept or generate human-readable selections.

For example, the Find command in SAMSON lets users enter an NSL expression to select nodes.

Internally, SAMSON converts an NSL string into a node predicate (SBNodePredicate) that can be passed to node-collection functions.

NSL can therefore be used in two ways:

directly as a string query
indirectly by compiling the string into a predicate with api/classSAMSON.md#function-makenodepredicate

Mental model#

NSL is the string representation of the same kind of selection logic you can also express with functors, getters, and predicates in C++.

That makes it useful when:

you want the query to be editable or configurable
you want to expose a selection rule to users
you want to store or transmit a selection expression

Equivalent C++ predicate logic#

Under the hood, NSL relates to the same predicate system used in C++:

// find all atoms with temperature factor > 1.0

SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer, 
    SBNode::IsType(SBNode::Atom) && (SBAtom::GetTemperatureFactor() > 1.0));

Direct use: query with a string#

You can use an NSL string directly to retrieve nodes:

// Select all residue nodes from the active document 
// that are within 4 angstrom of any sulfur atom.
// Note: the selection string may be abbreviated to "n.t r w 4A of S"

SBNodeIndexer nodeIndexer;
SAMSON::getNodes(nodeIndexer, "node.type residue within 4A of S");

Indirect use: compile to a predicate#

You can also convert an NSL string into a reusable predicate.

Note that ownership of the returned predicate is passed to the caller, who must delete it after use.

// Make a predicate that is true if and only if 
// the node is a hydrogen atom bonded to an oxygen atom.
// Note: the selection string may be abbreviated to "H l O"

SBNodePredicate* nodePredicate = SAMSON::makeNodePredicate("H linking O");

This route is useful when the query comes from configuration or user input but you want to reuse the predicate more than once.

When to prefer NSL#

Prefer NSL when:

the query should be editable by users
the selection should be serializable as text
readability as a declarative query matters more than compile-time composition

Prefer direct C++ predicates when:

the selection logic is static and code-local
the query depends on C++ types or logic that does not map naturally to NSL
you want compile-time checking without a string parsing step

Please refer to Getting nodes to learn more about using NSL in practical node-collection workflows.