Surgeon - Revision history

Kevin Reid: /* Maker protocol */ list formatting

2009-08-12T20:54:13Z

Maker protocol: list formatting

New page

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==
{{maker msgdoc|withSrcKit|1|<var>optPrefix</var> :[[nullOk]]<nowiki>[</nowiki>[[String]]]|[[Surgeon]]}}

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

{{specbycode|1=
makeSurgeon([
"depictionBuilderMaker" => [[deSrcKit]],
=> <var>optPrefix</var>,
"depictionRecognizer" => [[deSrcKit]]]).snapshot()}}

{{maker msgdoc|run|0||[[Surgeon]]}}

Use all the defaults of [[#run/1]].

{{maker msgdoc|run|1|3= 
[
=> uncallers := deSubgraphKit.getDefaultUncallers(),
=> unscope := deSubgraphKit.getDefaultUnscope(),
=> depictionBuilderMaker := deBytecodeKit,

=> optPrefix :nullOk[String] := null,

=> depictionRecognizer := deBytecodeKit,
=> scope := deSubgraphKit.getDefaultScope(),
=> caller := E
]
 |4=[[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 <code>[[Object E|E]]</code>. Used to perform a Data-E call expression during unserialization.

==Protocol==

{{instance msgdoc|snapshot|0||Const[[Surgeon]]}}

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

{{instance msgdoc|diverge|0||[[Surgeon]]}}

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

{{instance msgdoc|readOnly|0||[[Surgeon]]}}

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

{{instance msgdoc|serialize|1|<var>root</var> :[[any]]|[[any]]}}

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

{{instance msgdoc|unserialize|1|<var>depiction</var>|[[any]]}}

Unserializes the provided <var>depiction</var>, using the configured depiction recognizer and stripping off the specified prefix.

{{instance msgdoc|addExit|2|<var>value</var>, <var>exitName</var> :[[String]]|[[void]]}}

Not available in ConstSurgeons.

Adds the provided <var>value</var> as a graph exit:
* The subgraph recognizer's [[env]] now maps <var>value</var> to <var>exitName</var>.
* The subgraph builder's [[unenv]] now maps <var>exitName</var> to <var>value</var>.

{{instance msgdoc|addExit|3|<var>value</var>, <var>exitName</var>, <var>mustBeSettled</var> :[[boolean]]|[[void]]}}

As [[#addExit/2]], but if <var>mustBeSettled</var>, additionally requires that <var>value</var> is settled.

{{instance msgdoc|addUncaller|1|<var>uncaller</var> :[[Uncaller]]|[[void]]}}

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

{{instance msgdoc|addLastUncaller|1|<var>uncaller</var> :[[Uncaller]]|[[void]]}}

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

{{instance msgdoc|addLoader|2|<var>loader</var> :[[Uncaller]], <var>exitName</var> :[[String]]}}

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

{{instance msgdoc|addLoader|2|<var>loader</var>, <var>exitName</var> :[[String]], <var>mustBeSettled</var> :[[boolean]]|[[void]]}}

Adds <var>loader</var> as an exit (as in [[#addExit/3]]) and an uncaller (as in [[#addUncaller]]).

{{specbycode|
{{this}}.addExit(loader, exitName, mustBeSettled)
{{this}}.addUncaller(loader)
}}

{{instance msgdoc|beForgiving|0||[[void]]}}

{{unspecified message}}

{{instance msgdoc|addFromScope|3|<var>otherScope</var>, <var>exitNames</var>, <var>loaderNames</var>|[[void]]}}

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

{{XXX|Deprecate and rename to addFromEnv}}

{{unspecified message}}

{{instance msgdoc|addFromSafeScope|0||[[void]]}}

{{XXX|Deprecate and rename to addFromSafeEnv}}

{{unspecified message}}

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.

{{instance msgdoc|addFromPrivScope|1|<var>privScope</var> :[[Env]]|[[void]]}}

{{XXX|Deprecate and rename to addFromPrivEnv}}

Starts by doing an addFromSafeScope()

{{unspecified message}}

{{instance msgdoc|getDepictionRecognizer|0||[[DERecognizer]]}}

{{unspecified message}}

{{instance msgdoc|makeDepictionBuilder|0||[[DEBuilder]]}}

{{unspecified message}}

{{instance msgdoc|getOptPrefix|0||nullOk[String]}}

Returns the <var>optPrefix</var> with which this surgeon was constructed.

{{instance msgdoc|getSubgraphRecognizer|0||[[DERecognizer]]}}

{{unspecified message}}

{{instance msgdoc|makeSubgraphBuilder|0||[[DEBuilder]]}}

{{unspecified message}}

[[Category:ELib specification]]
[[Category:Data-E]]

Kevin Reid: add beForgiving

2009-08-11T01:37:33Z

add beForgiving

←Older revision		Revision as of 01:37, 11 August 2009
Line 115:		Line 115:
	{{this}}.addUncaller(loader)		{{this}}.addUncaller(loader)
	}}		}}
		+
		+	{{instance msgdoc\|beForgiving\|0\|\|[[void]]}}
		+
		+	{{unspecified message}}

	{{instance msgdoc\|addFromScope\|3\|<var>otherScope</var>, <var>exitNames</var>, <var>loaderNames</var>\|[[void]]}}		{{instance msgdoc\|addFromScope\|3\|<var>otherScope</var>, <var>exitNames</var>, <var>loaderNames</var>\|[[void]]}}

Kevin Reid at 00:11, 11 August 2009

2009-08-11T00:11:07Z

←Older revision		Revision as of 00:11, 11 August 2009
Line 33:		Line 33:

	;uncallers		;uncallers
-	: Defaults to [[deSubgraphKit]].getDefaultUncallers(). The search path used to find a portrayal for traversing each node of the subgraph.	+	: Defaults to [[deSubgraphKit]].getDefaultUncallers().
		+	The search path used to find a portrayal for
		+	traversing each node of the subgraph.
	;unscope		;unscope
-	: Defaults to [[deSubgraphKit]].getDefaultUnscope(). Cuts off outgoing references, replacing them with named exit points to be reconnected.	+	: Defaults to [[deSubgraphKit]].getDefaultUnscope().
		+	Cuts off outgoing references, replacing them with
		+	named exit points to be reconnected.
	;depictionBuilderMaker		;depictionBuilderMaker
-	: Defaults to [[deBytecodeKit]]. Used to make the builder which will make the depiction.	+	: Defaults to [[deBytecodeKit]].
		+	Used to make the builder which will make
		+	the depiction.
	;optPrefix		;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.	+	: 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		;depictionRecognizer
-	: Defaults to [[deBytecodeKit]]. Used to recognize the depiction built according to optDepictionBuilderMaker.	+	: Defaults to [[deBytecodeKit]].
-	;scope	+	Used to recognize the depiction built
-	:Defaults to deSubgraphKit.getDefaultScope(). Used to reconnect the named exit points.	+	according to optDepictionBuilderMaker.
-	;caller	+	;scope Defaults to deSubgraphKit.getDefaultScope().
-	:Defaults to <code>[[Object E\|E]]</code>. Used to perform a Data-E call expression during unserialization.	+	Used to reconnect the named exit points.
		+	;caller Defaults to <code>[[Object E\|E]]</code>.
		+	Used to perform a Data-E call expression during
		+	unserialization.

	==Protocol==		==Protocol==
Line 101:		Line 115:
	{{this}}.addUncaller(loader)		{{this}}.addUncaller(loader)
	}}		}}
-
-	~~{{instance msgdoc\|beForgiving\|0\|\|[[void]]}}~~
-
-	~~{{unspecified message}}~~

	{{instance msgdoc\|addFromScope\|3\|<var>otherScope</var>, <var>exitNames</var>, <var>loaderNames</var>\|[[void]]}}		{{instance msgdoc\|addFromScope\|3\|<var>otherScope</var>, <var>exitNames</var>, <var>loaderNames</var>\|[[void]]}}