Guard
From Erights
Kevin Reid (Talk | contribs) |
Kevin Reid (Talk | contribs) (copy in documentation from Guard.java in E-on-Java with permission) |
||
Line 1: | Line 1: | ||
- | + | 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> | + | 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. | ||
- | + | (See also: the [[non-optional ejectors]] proposal.) | |
===rangeSupersetOf/1=== | ===rangeSupersetOf/1=== | ||
- | to rangeSupersetOf(<var>other</var> :[[Guard]]) :[[ | + | 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.