DSM Introspection¶

DSM classes provide parsing and introspection of Digital Substrate Model files.

When to use: Use DSMBuilder to parse .dsm files and introspect the resulting definitions (structures, enumerations, attachments, functions).

Quick Start¶

from dsviper import DSMBuilder

# Parse DSM file
builder = DSMBuilder.assemble("model.dsm")
report, dsm_defs, defs = builder.parse()

# Check for parse errors
if report.has_error():
    for err in report.errors():
        print(f"Line {err.line()}: {err.message()}")
    raise RuntimeError("DSM parse failed")

# Introspect structures
for struct in dsm_defs.structures():
    print(f"Struct: {struct.type_name()}")
    for field in struct.fields():
        print(f"  {field.name()}: {field.type_reference()}")

# Introspect attachments
for att in dsm_defs.attachments():
    print(f"Attachment: {att.type_name()}")
    print(f"  Key: {att.key_type()}, Doc: {att.document_type()}")

# Inject constants for runtime use
defs.inject()  # Creates MYAPP_A_*, MYAPP_S_*, etc.

Parsing¶

`dsviper.DSMBuilder`	A class used to assemble a collection of DSM Definitions from various sources.
`dsviper.DSMBuilderPart`	A class used to represent a part of the assembled definitions.
`dsviper.DSMDefinitions`	A class used to represent DSM definitions.
`dsviper.DSMDefinitionsInspector`	DSMDefinitionsInspector(definitions).
`dsviper.DSMParseReport`	A class used to collect the error occurred while parsing the assembled definitions.
`dsviper.DSMParseError`	A class used to represent a parse error.

Model Elements¶

`dsviper.DSMConcept`	A class used to represent the definition of a concept.
`dsviper.DSMClub`	A class used to represent the definition of a club.
`dsviper.DSMStructure`	A class used to represent the definition of a struct.
`dsviper.DSMStructureField`	A class used to represent the definition of a field for a struct.
`dsviper.DSMEnumeration`	A class used to represent the definition of an enum.
`dsviper.DSMEnumerationCase`	A class used to represent the definition of a case for an enum.
`dsviper.DSMAttachment`	A class used to represent the definition of an attachment.

DSM Types¶

`dsviper.DSMTypeKey`	A class used to represent the type key<element_type>.
`dsviper.DSMTypeVector`	A class used to represent the type vector<element_type>.
`dsviper.DSMTypeSet`	A class used to represent the type set<element_type>.
`dsviper.DSMTypeMap`	A class used to represent the type map<key_type, element_type>.
`dsviper.DSMTypeXArray`	A class used to represent the type xarray<element_type>.
`dsviper.DSMTypeOptional`	A class used to represent the type optional<element_type>.
`dsviper.DSMTypeTuple`	A class used to represent the type tuple<T0, ...>.
`dsviper.DSMTypeVec`	A class used to represent the type vec<element_type, size>.
`dsviper.DSMTypeMat`	A class used to represent the type vec<element_type, columns, rows>.
`dsviper.DSMTypeVariant`	A class used to represent the type variant<T0, ...>.
`dsviper.DSMTypeReference`	A class used to represent a reference to a type.

Functions¶

`dsviper.DSMFunction`	A class used to represent the definition of a function.
`dsviper.DSMFunctionPool`	A class used to represent the definition of a function pool.
`dsviper.DSMFunctionPrototype`	A class used to represent the definition of a function prototype.
`dsviper.DSMAttachmentFunction`	A class used to represent the definition of an attachment function.
`dsviper.DSMAttachmentFunctionPool`	A class used to represent the definition of an attachment function pool.

Literals¶

`dsviper.DSMLiteralValue`	A class used to represent the definition of a literal value.
`dsviper.DSMLiteralList`	A class used to represent the definition of a literal list.

Source Map¶

Pass a DSMSourceMap to DSMBuilder.parse(source_map=…) and the parser records, as a by-product, the exact source span of every declaration, field, case, namespace, type sub-expression and resolved type-reference. This is what makes a span-precise codemod possible: patch a hand-authored .dsm in place under a transformation — file split, comments and ordering preserved — instead of regenerating it. Opt-in; a parse without a source map is unchanged.

from dsviper import DSMBuilder, DSMSourceMap

source_map = DSMSourceMap()
report, dsm_defs, defs = DSMBuilder.assemble("model.dsm").parse(source_map=source_map)

`dsviper.DSMSourceMap`	A source-map collected while parsing DSM: the exact source spans of every declaration, field, case, namespace and resolved type-reference.
`dsviper.DSMSourceSpan`	A source text span (line, start, stop) of a definition token.
`dsviper.DSMSourceDeclaration`	A definition declaration, its identifier and its source spans (name, block, documentation).
`dsviper.DSMSourceField`	A struct field and its source spans (name, type, whole declaration, doc).
`dsviper.DSMSourceCase`	An enumeration case and its source spans (name, doc).
`dsviper.DSMSourceNameSpace`	A namespace header and the source spans of its name and UUID.
`dsviper.DSMSourceReference`	A resolved type-reference site: its source span and its referent TypeName.
`dsviper.DSMSourceType`	A type sub-expression occurrence: its source span and its fully-qualified DSM representation (the name-based identity of a type).