Guard

From Erights

(Difference between revisions)
Jump to: navigation, search
(copy in documentation from Guard.java in E-on-Java with permission)
Line 1: Line 1:
-
XXX explain what a Guard is
+
A Guard will either coerce an input to a value that matches some condition, or it will fail.
 +
 
 +
A Guard is used in the E language to guard the definition of a variable or the return value of a method. Implementors of Guard should always override __printOn/1 to print a guard expression reflecting the guard's value.
 +
 
 +
It is planned but not yet implemented that all objects used as guards must be [[DeepFrozen]].
==Protocol==
==Protocol==
===coerce/2===
===coerce/2===
-
to coerce(<var>specimen</var>, <var>ejector</var> :[[OneArgFunc]]) :[[any]]
+
to coerce(<var>specimen</var>, <var>optEjector</var> :[[nullOk]]<nowiki>[</nowiki>[[OneArgFunc]]]) :[[any]]
 +
 
 +
If <var>specimen</var> coerces to a reference that matches the condition represented by this guard, return that reference; otherwise fail (according to <var>[[optEjector]]</var>) with a [[problem]] explaining why not.
 +
 
 +
If optEjector is [[null]], then [[throw]] the problem. Otherwise, call optEjector with the problem. optEjector should perform a non-local exit, and so should not return. If optEjector returns anyway, then throw the problem after all.
-
{{unspecified message}}
+
(See also: the [[non-optional ejectors]] proposal.)
===rangeSupersetOf/1===
===rangeSupersetOf/1===
-
to rangeSupersetOf(<var>other</var> :[[Guard]]) :[[nullOK]][[[Boolean]]]
+
to rangeSupersetOf(<var>other</var> :[[Guard]]) :[[nullOk]]<nowiki>[</nowiki>[[Boolean]]]
Experimental. See [[guard-based auditing]].
Experimental. See [[guard-based auditing]].

Revision as of 19:02, 20 June 2008

A Guard will either coerce an input to a value that matches some condition, or it will fail.

A Guard is used in the E language to guard the definition of a variable or the return value of a method. Implementors of Guard should always override __printOn/1 to print a guard expression reflecting the guard's value.

It is planned but not yet implemented that all objects used as guards must be DeepFrozen.

Protocol

coerce/2

to coerce(specimen, optEjector :nullOk[OneArgFunc]) :any

If specimen coerces to a reference that matches the condition represented by this guard, return that reference; otherwise fail (according to optEjector) with a problem explaining why not.

If optEjector is null, then throw the problem. Otherwise, call optEjector with the problem. optEjector should perform a non-local exit, and so should not return. If optEjector returns anyway, then throw the problem after all.

(See also: the non-optional ejectors proposal.)

rangeSupersetOf/1

to rangeSupersetOf(other :Guard) :nullOk[Boolean]

Experimental. See guard-based auditing.

Personal tools
more tools