Class MechanismXml

Namespace

Hi.Mech

Assembly

HiMech.dll

Reads and writes the three members of an IMechanism — <Asmb>, <Root> and <AnchorToSolid> — as direct children of a host element. The layout is the one GeneralMechanism has always written, so a <GeneralMechanism> element is itself a valid host. The role-reference helpers persist which anchor or branch of the topology a mechanism's role names, by Guid, under the mechanism's own element name for that role.

public static class MechanismXml

Inheritance

object

MechanismXml

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

AnchorToSolidXName

Name of the anchor-to-solid dictionary element.

public const string AnchorToSolidXName = "AnchorToSolid"

Field Value

string

EntryXName

Name of one dictionary entry element.

public const string EntryXName = "Entry"

Field Value

string

RootXName

Name of the root-anchor element.

public const string RootXName = "Root"

Field Value

string

Methods

Read(XElement, string, IProgress<IMessage>, out Asmb, out Anchor, out Dictionary<Anchor, Solid>, out Dictionary<Guid, Anchor>)

Reads the assembly, the root anchor and the solid dictionary from the children of host. All three elements are required, as they always were: a host missing one fails the way the mechanism reader always failed, so the corpus fingerprint does not move.

public static void Read(XElement host, string baseDirectory, IProgress<IMessage> progress, out Asmb asmb, out Anchor root, out Dictionary<Anchor, Solid> anchorToSolid, out Dictionary<Guid, Anchor> guidToAnc)

Parameters

host XElement

The element whose children are the three members.

baseDirectory string

The base directory the solids' file references resolve against.

progress IProgress<IMessage>

Progress reporter for diagnostics emitted while the solids load.

asmb Asmb

The assembly read from <Asmb>.

root Anchor

The root anchor, resolved by Guid inside asmb.

anchorToSolid Dictionary<Anchor, Solid>

The solid dictionary, keyed by the anchors resolved by Guid; a persisted entry may carry a null solid.

guidToAnc Dictionary<Guid, Anchor>

Every anchor of asmb by Guid — the index the caller can keep resolving other references against.

Exceptions

NullReferenceException

The host lacks <Asmb>, <Root> or <AnchorToSolid>.

KeyNotFoundException

The root or a dictionary entry names a Guid the assembly does not have.

Read(XElement, string, IProgress<IMessage>, out Asmb, out Anchor, out Dictionary<Anchor, Solid>, out Dictionary<Guid, Anchor>, out Dictionary<Guid, Branch>)

Reads the three members as Read(XElement, string, IProgress<IMessage>, out Asmb, out Anchor, out Dictionary<Anchor, Solid>, out Dictionary<Guid, Anchor>) does and hands out the branch index as well, for a mechanism whose roles name branches.

public static void Read(XElement host, string baseDirectory, IProgress<IMessage> progress, out Asmb asmb, out Anchor root, out Dictionary<Anchor, Solid> anchorToSolid, out Dictionary<Guid, Anchor> guidToAnc, out Dictionary<Guid, Branch> guidToBrn)

Parameters

host XElement

The element whose children are the three members.

baseDirectory string

The base directory the solids' file references resolve against.

progress IProgress<IMessage>

Progress reporter for diagnostics emitted while the solids load.

asmb Asmb

The assembly read from <Asmb>.

root Anchor

The root anchor, resolved by Guid inside asmb.

anchorToSolid Dictionary<Anchor, Solid>

The solid dictionary, keyed by the anchors resolved by Guid; a persisted entry may carry a null solid.

guidToAnc Dictionary<Guid, Anchor>

Every anchor of asmb by Guid.

guidToBrn Dictionary<Guid, Branch>

Every branch inside asmb by Guid.

Exceptions

NullReferenceException

The host lacks <Asmb>, <Root> or <AnchorToSolid>.

KeyNotFoundException

The root or a dictionary entry names a Guid the assembly does not have.

ReadAnchorReference(XElement, string, Dictionary<Guid, Anchor>)

Reads the anchor a role element written by WriteAnchorReference(XElement, string, Anchor, bool) names, resolved by Guid among guidToAnc. Null when the element is absent or empty, or names a Guid the assembly does not have — the role stays unbound.

public static Anchor ReadAnchorReference(XElement host, string name, Dictionary<Guid, Anchor> guidToAnc)

Parameters

host XElement

The element the role element is a child of.

name string

The role's element name.

guidToAnc Dictionary<Guid, Anchor>

Every anchor of the assembly by Guid, as Read(XElement, string, IProgress<IMessage>, out Asmb, out Anchor, out Dictionary<Anchor, Solid>, out Dictionary<Guid, Anchor>) indexed them.

Returns

Anchor

The anchor, or null.

ReadBranchReference(XElement, string, Dictionary<Guid, Branch>)

Reads the branch a role element written by WriteBranchReference(XElement, string, Branch, bool) names, resolved by Guid among guidToBrn. Null when the element is absent or empty, or names a Guid the assembly has no branch of — the role stays unbound.

public static Branch ReadBranchReference(XElement host, string name, Dictionary<Guid, Branch> guidToBrn)

Parameters

host XElement

The element the role element is a child of.

name string

The role's element name.

guidToBrn Dictionary<Guid, Branch>

Every branch of the assembly by Guid, as Read(XElement, string, IProgress<IMessage>, out Asmb, out Anchor, out Dictionary<Anchor, Solid>, out Dictionary<Guid, Anchor>, out Dictionary<Guid, Branch>) indexed them.

Returns

Branch

The branch, or null.

Write(XElement, IMechanism, string, bool)

Appends the three members of mechanism to host: the assembly, the root anchor's index and one <Entry Guid="…"> per dictionary entry with the solid's own XML inside (empty when the entry carries no solid).

public static void Write(XElement host, IMechanism mechanism, string baseDirectory, bool exhibitionOnly)

Parameters

host XElement

The element to append to.

mechanism IMechanism

The mechanism to write; its root anchor must not be null.

baseDirectory string

The base directory the solids' file references are made relative to.

exhibitionOnly bool

When true, the solids write no side files.

Exceptions

InvalidOperationException

The mechanism has no root anchor.

WriteAnchorReference(XElement, string, Anchor, bool)

Appends <name><Anc Guid="…"/></name> naming anchor — the way a mechanism persists which of its anchors plays a role. An unbound role writes nothing, or — with emptyWhenUnbound — an empty <name/>, which tells a reader with a fallback that the role was persisted as unbound rather than never persisted.

public static void WriteAnchorReference(XElement host, string name, Anchor anchor, bool emptyWhenUnbound = false)

Parameters

host XElement

The element to append to.

name string

The role's element name.

anchor Anchor

The anchor playing the role; null when unbound.

emptyWhenUnbound bool

When true, an unbound role writes an empty element instead of nothing.

WriteBranchReference(XElement, string, Branch, bool)

Appends <name><Brn Guid="…"/></name> naming branch — the way a mechanism persists which of its branches plays a role. An unbound role writes nothing, or — with emptyWhenUnbound — an empty <name/>.

public static void WriteBranchReference(XElement host, string name, Branch branch, bool emptyWhenUnbound = false)

Parameters

host XElement

The element to append to.

name string

The role's element name.

branch Branch

The branch playing the role; null when unbound.

emptyWhenUnbound bool

When true, an unbound role writes an empty element instead of nothing.