Object E

From Erights

The object known as "E" in the safeEnv is the primitive with which variable-argument calls and sends may be made, and also provides shortcuts for converting objects to strings.

(Note: Caja-CapTP, which borrows E's reference/call/send system, conflates this object with Ref.)

Note that even though send expressions (<-) are defined in terms of the E object, it does not solely constitute the authority to eventual send; Miranda __whenMoreResolved means every object provides this authority.

Protocol

call/3

Signature: call(recipient, verb :String, args :List) :any

XXX copied javadoc - review appropriateness as spec language

An E immediate call -- ask 'rec' to immediately do the request described by verb using the supplied args.

See The Immediate Call.

callWithPair/3

Signature: callWithPair(recipient, message :Tuple[String, List]) :any

Equivalent to E.call(recipient, message[0], message[1]).

Defined in order to be more efficient when forwarding matcher messages than E.call.

The E implementation is not required to use a guard on message as strict as shown, though the guards for E.call's arguments must of course be applied. XXX Review - is this a good idea? EoJ coerces to array but doesn't check the length, which is what I'm trying to capture here. --Kevin Reid 16:14, 12 August 2009 (CDT)

send/3

Signature: send(rec, verb :String, args :List) :Promise

XXX copied javadoc - review appropriateness as spec language

Queue the described delivery.

Rather than providing an explicit Resolver as input argument, this method returns a promise that represents the outcome. When the actual outcome is determined, the returned reference will reflect that outcome.

This should only synchronously throw an exception if invoked while there's no current Vat.

See The Pipelined Send.

sendOnly/3

Signature: sendOnly(rec, verb :String, args :List) :void

XXX copied javadoc - review appropriateness as spec language

Like sendAll(rec, verb, args), except that "Only" means we don't care about the result (including whether it succeeded), as is appropriate for event notifications.

Return value: Why wasn't this event queued? It isn't queued if this vat or comm connection is shut down, in which case the returned problem explains why. If null is returned, then the event was queued, though it may still not arrive. XXX Review: User:Kevin Reid recalls discussing deprecating this return value since it is not particularly useful and only available in the sendOnly case.

See The Eventual Send: sendOnly.

toString/1

Signature: toString(object) :String

def [tw, sb] := <elib:oldeio.makeTextWriter>.makeBufferingPair()
tw.print(object)
return sb.toString()

XXX copied javadoc - review appropriateness as spec language. Also, this particular one was edited from the toTwine doc to explain toString. Note that toTwine is not a method of EoJ E4E. Is this an oversight or a silent deprecation? --Kevin Reid 16:14, 12 August 2009 (CDT)

Prints obj, and returns this printed form.

E programmers should generally call "E.toString(obj)", rather than "obj.toString()". This applies both to E language programmers and to ELib programmers. However, E programmers should not generally call E.toString(obj) from within __printOn(TextWriter) methods, as that will circumvent the cycle-breaking logic in TextWriter. Instead, you should usually call a TextWriter.*print*(obj) method, as it will check for a cycle before calling __printOn(TextWriter) on its argument.

toQuote/1

Signature: toQuote(object) :String

def [tw, sb] := <elib:oldeio.makeTextWriter>.makeBufferingPair()
tw.quote(object)
return sb.toString()

XXX Review Twine vs. String. EoJ E4E has Twine here but only String for non-quoting version. Seems incoherent --Kevin Reid 16:14, 12 August 2009 (CDT)

Like toString, but gets the quoted form.