Surgeon

From Erights

The Surgeon is a Data-E component which is the high-level serialization-and-unserialization tool. It provides a convenient interface to configuring serialization and unserialization in matching ways.

Maker protocol

withSrcKit/1

withSrcKit(optPrefix :nullOk[String]) :Surgeon

Returns a const Surgeon using the deSrcKit, and the specified textual prefix, for its depictions.

Equivalent to makeSurgeon([

    "depictionBuilderMaker" => deSrcKit,
    => optPrefix,
    "depictionRecognizer" => deSrcKit]).snapshot().

run/0

run() :Surgeon

Use all the defaults of #run/1.

run/1

run( 

    [
        => uncallers := deSubgraphKit.getDefaultUncallers(),
        => unscope := deSubgraphKit.getDefaultUnscope(),
        => depictionBuilderMaker := deBytecodeKit,
        
        => optPrefix :nullOk[String] := null,
        
        => depictionRecognizer := deBytecodeKit,
        => scope := deSubgraphKit.getDefaultScope(),
        => caller := E
    ]

 ) :Surgeon

General constructor for surgeons.

uncallers

Defaults to deSubgraphKit.getDefaultUncallers(). The search path used to find a portrayal for traversing each node of the subgraph.

unscope

Defaults to deSubgraphKit.getDefaultUnscope(). Cuts off outgoing references, replacing them with named exit points to be reconnected.

depictionBuilderMaker

Defaults to deBytecodeKit. Used to make the builder which will make the depiction.

optPrefix

Defaults to null. If non-null, then the optDepictionBuilderMaker and optDepictionRecognizer must be for depictions which are strings. If provided, then it is prepended to the depiction to create the serialized form, and is stripped from the beginning of the depiction prior to serialization.

depictionRecognizer

Defaults to deBytecodeKit. Used to recognize the depiction built according to optDepictionBuilderMaker.

scope

Defaults to deSubgraphKit.getDefaultScope(). Used to reconnect the named exit points.

caller

Defaults to E. Used to perform a Data-E call expression during unserialization.

Protocol

snapshot/0

Signature: snapshot() :ConstSurgeon

Returns a surgeon whose configuration is a snapshot of this one and cannot be changed. XXX state more precisely.

diverge/0

Signature: diverge() :Surgeon

Returns a surgeon whose configuration is a copy of this one and can be changed. XXX state more precisely.

readOnly/0

Signature: readOnly() :Surgeon

Returns a surgeon whose configuration follows this one but cannot be used to change it.

serialize/1

Signature: serialize(root :any) :any

Serializes the subgraph with the provided root, using the configured depiction builder and adding the specified prefix.

unserialize/1

Signature: unserialize(depiction) :any

Unserializes the provided depiction, using the configured depiction recognizer and stripping off the specified prefix.

addExit/2

Signature: addExit(value, exitName :String) :void

Not available in ConstSurgeons.

Adds the provided value as a graph exit:

• The subgraph recognizer's env now maps value to exitName.
• The subgraph builder's unenv now maps exitName to value.

addExit/3

Signature: addExit(value, exitName, mustBeSettled :boolean) :void

As #addExit/2, but if mustBeSettled, additionally requires that value is settled.

addUncaller/1

Signature: addUncaller(uncaller :Uncaller) :void

The provided uncaller will be consulted by the subgraph recognizer before all previously added uncallers.

addLastUncaller/1

Signature: addLastUncaller(uncaller :Uncaller) :void

The provided uncaller will be consulted by the subgraph recognizer after all previously added uncallers.

addLoader/2

Signature: addLoader(loader :Uncaller, exitName :String) :{{{4}}}

As #addLoader/3, but mustBeSettled defaults to false.

addLoader/2

Signature: addLoader(loader, exitName :String, mustBeSettled :boolean) :void

Adds loader as an exit (as in #addExit/3) and an uncaller (as in #addUncaller).

Equivalent to

thisSurgeon.addExit(loader, exitName, mustBeSettled)
thisSurgeon.addUncaller(loader)

.

beForgiving/0

Signature: beForgiving() :void

The specification for this message has not been written.

addFromScope/3

Signature: addFromScope(otherScope, exitNames, loaderNames) :void

Names which either aren't found, map to null, or aren't settled aren't added.

XXX Deprecate and rename to addFromEnv

The specification for this message has not been written.

addFromSafeScope/0

Signature: addFromSafeScope() :void

XXX Deprecate and rename to addFromSafeEnv

The specification for this message has not been written.

Unedited javadoc:

The defaultScope / defaultUnscope already has bindings for "null", "false", "true", "NaN", "Infinity", "__makeList", "__identityFunc", "__makeInt", and "import__uriGetter", so addFromSafeScope() assumes these are already present and does not add them. Similarly, the defaultUncallers already has the import__uriGetter, so this is not added as a loader.

For different reasons, the opaque__uriGetter is not added by addFromSafeScope() -- we leave its addition as a separate policy decision, especially since it needs to be added to the end, not the beginning, of the uncallers list.

addFromPrivScope/1

Signature: addFromPrivScope(privScope :Env) :void

XXX Deprecate and rename to addFromPrivEnv

Starts by doing an addFromSafeScope()

The specification for this message has not been written.

getDepictionRecognizer/0

Signature: getDepictionRecognizer() :DERecognizer

The specification for this message has not been written.

makeDepictionBuilder/0

Signature: makeDepictionBuilder() :DEBuilder

The specification for this message has not been written.

getOptPrefix/0

Signature: getOptPrefix() :nullOk[String]

Returns the optPrefix with which this surgeon was constructed.

getSubgraphRecognizer/0

Signature: getSubgraphRecognizer() :DERecognizer

The specification for this message has not been written.

makeSubgraphBuilder/0

Signature: makeSubgraphBuilder() :DEBuilder

The specification for this message has not been written.