Erights - User contributions [en]

Test bin

Kevin Reid — Mon, 10 Jun 2013 01:48:48 GMT

Kevin Reid: /* Expansion of bare try */ new test case

This page is for E implementation conformance tests for which a more specific location has not ''yet'' been found.

===How [[User:Kevin Reid]] thinks doc-comments ought to work===

(1 outside space is dropped, function obj doc goes on the method) {{XXX|add multiline doc tests, w roundtrip}}

? /** foo */ def x {}
# value: <x>

? x.__getAllegedType().getDocComment()
# value: "foo"

? /** foo */ def y() :void {}
# value: <y>

? y.__getAllegedType().getDocComment()
# value: ""

? y.__getAllegedType().getMessageTypes()["run/0"].getDocComment()
# value: "foo"

===Trailing commas===

Trailing commas should be consistently accepted everywhere (aren't in map-patterns):
? __identityFunc(1,)
# value: 1

? [1,]
# value: [1]

? [1 => 2,]
# value: [1 => 2]

? [null, true, false][1,]
# value: true

? def [a,] := [1]
# value: [1]

? def foo(a,) :void {}
# value: <foo>

===Expansion of multiple try-catch===

? try { throw("oops") } catch ==1 {}
# problem: oops

? try { throw("oops") } catch ==1 {} catch ==2 {}
# problem: oops
That is, none of the patterns matching should be equivalent to a single catch not matching (Fails in [[EoJ]] 0.9.1b)

===Expansion of bare try===

? def x := 1; try { def x := 2 }; x
# value: 1

General <code>try</code> should expand to a [[HideExpr]] for the sake of scoping if there are no clauses. (Currently fails in [[E-on-CL]].)

===Expansion of bind===

? def x
# value: <Resolver>

? bind x {}
# value: <x>

? x.__getAllegedType().getFQName()
# value: "__main$x"

===Expansion of map pattern===

? def a := "43"
# value: "43"

? def b :int := a
# problem: <ClassCastException: String doesn't coerce to an int>

? def [b :int] := [a]
# problem: <ClassCastException: String doesn't coerce to an int>

? def ["" => b :int] := ["" => a]
# problem: <ClassCastException: String doesn't coerce to an int>

? def ["x" => _] := ["" => a]
# problem: x not found

===Serialization===

? pragma.syntax("0.9")
> pragma.enable("accumulator")

? def makeSurgeon := <elib:serial.makeSurgeon>
# value: <makeSurgeon>

? def surgeons := ["default" => makeSurgeon(), "src" => makeSurgeon.withSrcKit(null)]
# value: ["default" => <surgeon>, "src" => <readOnlySurgeon>]

? def check(x, ignore) {
> def diffs := accum [].asMap() for k => surgeon in surgeons { _.with(k,
> def y := surgeon.unserialize(surgeon.serialize(x))
> accum [] for check ? (!ignore.contains(check)) => r ? (!r) in [
> "same" => x == y,
> "equiv" => !x.__respondsTo("compareTo",1) || x <=> y,
> "print" => E.toString(x) == E.toString(y)
> ] { _.with([check, x, y]) }
> )}
> return accum [].asMap() for k => v ? (v !~ []) in diffs { _.with(k, v) }
> }
# value: <check>

? check(1, [])
# value: [].asMap()

? check([1,2,3], [])
# value: [].asMap()

? check(def x := [1,2,x], [])
# value: [].asMap()

? check(Guard, [])
# value: [].asMap()

? check(78452960457820936578390758342950673284590431267589324057832946723148963275893465783049856783294507632894506732158912365478567145683415063127849561839450768239032675890432675843294067538490576382590432764589320457832940732849507324893076849051326758903426758903265748329405678329056732895032764853290576438259063278590267589023157689023456784321905632748950634278590342675893214056732841095673214850934726589032467583904576823904561758463859340758329067430642891467389027548790365783567438567473287237458763289478945137536498671236478658920786905234876435187903524783452608079342580796345218076953410876913458079634512087963451208796345017890493578108793452107893451289073452178960345179802879345178693451025734689012768059341278695134278906543210453780216978690543214532786091453782619054386719023452187690134528076931248570691578034629132076845932145768032104657834521780690786934512673845120978603459123456712809341572680931457086293457806219, [])
# value: [].asMap()

? check([].diverge(), ["same"])
# value: [].asMap()

===???===
? E.toString(help(/** FOO */ def _{})).indexOf("FOO") != -1
# value: true

===Behavior of __getAllegedType on objects with non-general matchers===
{{XXX|write some explanation with this}}

? def _ {}.__getAllegedType()
# value: _

? def _ { match _ {} }.__getAllegedType()
# value: _

? def _ { match [] {} }.__getAllegedType()
# value: _

? require.__getAllegedType()
# value: require0

===Processing __N should be idempotent===

? def foos := ["a", "b"]

? e`def [foo__1, foo__2] := foos`
# value: e`def [foo__1, foo__2] := foos`

? e__quasiParser(e`def [foo__1, foo__2] := foos`.asText()) \
> =~ e`def [foo__1, foo__2] := foos`
# value: true

? def [foo__1, foo__2] := foos; null
? [=> foo__1, => foo__2]
# value: ["foo__1" => "a", "foo__2" => "b"]

? meta.getState()["&foo__1"].getValue()
# value: "a"

==Regression tests==

===This used to hang on [[E-on-Java]]===
? def T := nullOk[Tuple[any, T]]
# value: nullOk[Tuple[any, <***CYCLE***>]]

===These used to reveal pointers on [[E-on-Java]]===
? [].asMap()[<import:java.lang.makeObject>()]
# problem: <IndexOutOfBoundsException: <an Object> not found>

? 1.0.random()
# problem: <NoSuchMethodException: <a Double>.random/0>

===???===
? def l := [].diverge(char)
# value: [].diverge()

? l.append(['a', 'b', 'c'])

? l
# value: ['a', 'b', 'c'].diverge()

===This used to fail to be rejected in [[E-on-Java]]===
? { x + 1; def x := 2 }
# problem: Failed: Undefined variable: x

? {[x + 1, def x := 2]}
# problem: Failed: Undefined variable: x

As of 0.8.30d, the results of these were:
# value: 2
# value: [485, 2]

===Miranda messages should not expose Java typed names===

? def obj {
> to __getAllegedType() :any { return null.__getAllegedType() }
> }
# value: <obj>

? obj.__getAllegedType()
# value: void

? [obj."__getAllegedType()"()]
# problem: <NoSuchMethodException: <an obj>.__getAllegedType()/0>

[[Category:E specification]]

Services

Kevin Reid — Sun, 25 Nov 2012 18:55:09 GMT

Kevin Reid: Created page with "This page is a catalog of web sites, repositories, and other services pertaining to the ERights project. It is intended to assist in assessing the health of the project and make …"

This page is a catalog of web sites, repositories, and other services pertaining to the ERights project. It is intended to assist in assessing the health of the project and make sure that historical data is not lost.

{|class="wikitable sortable"
|-
! Service !! Administrators !! Dependencies (servers, companies) !! Notes (backups, etc)
|-
| Mailing lists (e-lang and cap-talk) || Jonathan S. Shapiro || eros-os.org || Both mailing lists and archives
|-
| [http://www.erights.org/ erights.org] DNS || Mark Miller, {{XXX|any others?}} || {{XXX}} ||
|-
| [http://www.erights.org/ www.erights.org] hosting/content || Mark Miller, {{XXX|any others?}} || {{XXX}} ||
|-
| [http://wiki.erights.org/wiki/Main_Page wiki.erights.org] || James Graves (ansible) || {{XXX}} || See [[Erights:About]] for information about database backups.
|-
| E Subversion repository: <code>svn://svn.synchrona.org/erights/</code> || Dean Tribble || {{XXX}}
| Contents:
* www.erights.org content
* E-on-Java source code
* Horton source code and paper
* Joe-E source code
Kevin Reid has a private svnsync mirror of the entire repository and a [https://github.com/kpreid/e-on-java public git-svn mirror] of the E-on-Java component.
|-
| [https://sourceforge.net/tracker/?group_id=75274&atid=551529 E-on-Java bug tracker] || Mark Miller, Darius Bacon, Kevin Reid, Marc Stiegler, Steve Jenson, Terry Stanley || SourceForge.net ||
|}

Development

Kevin Reid — Sun, 25 Nov 2012 18:46:05 GMT

Kevin Reid: /* Bug Tracking */ provided URL was auth-only, hopefully this one isn't

== Source Code ==

If you wish to obtain an official stable release of '''''E''''', see the [[Downloads]] page.

=== Official Subversion Repository ===

The '''''E''''' sources and the erights.org website are both maintained in [[wikipedia:Subversion|Subversion]]. If you have a Subversion client, you can check out the latest '''''E''''' sources by doing, for example,

$ svn co svn://svn.synchrona.org/erights/e/trunk e

You can obtain the erights.org website by doing

$ svn co svn://svn.synchrona.org/erights/doc doc

=== Unofficial Git Repository ===

http://gitorious.org/repo-roscidus/e-core

== Bug Tracking ==

[https://sourceforge.net/tracker/?group_id=75274&atid=551529 '''''E''''' Bug Tracking on SourceForge]

== Design and Future Directions ==

[[:Category:Unresolved design issues|Unresolved Design Issues]]

== Development Environments ==

[[E Under Eclipse|'''''E''''' Under Eclipse]]

[http://code.google.com/p/nbe-lang/ NetBeans support for '''''E''''']

User:Kevin Reid

Kevin Reid — Thu, 10 May 2012 22:43:18 GMT

Kevin Reid: /* Projects */ link tmbundle

[http://switchb.org/kpreid/ My web site].

[http://www.google.com/search?q=inurl:www.eros-os.org/pipermail/+%22Kevin+Reid%22&filter=0 My posts on the e-lang and cap-talk mailing lists].

== Projects ==

Roughly in order of liveness.

* I am currently the semi-official E-on-Java maintainer as [[User:Markm|Mark Miller]] is busy with other projects.
* eel/runebot/murepl, the IRC bot etc. project (source not released; currently runs on my personal laptop which is a situation that Really Ought To Be Fixed)
* [[E-on-CL]] — E implementation
* [https://github.com/kpreid/E.tmbundle E support for TextMate]
* [[Caja-CapTP]] — adapting [[CapTP]] to [[Caja]].
* [[e-benchmark]] — benchmarking E implementations.
* [[E-on-Haskell]] — E implementation
* [[kEIO]] — [[EIO]] implementation for [[E-on-Java]]
* [[Den]] — distributed virtual world platform
* The [[surprise list]].

== Scraps ==

* [[gendoc.e]]
* [[/java3d.e-awt]] — Java 3D API used from E
* [[/scribble.e-awt]] — Simple Swing UI application with custom graphics

=== Drafts ===

* [[/User far proxy]] — project to allow a human to provide the behavior of a far ref
* [[/Thoughts on protocol queries]] — how does one object ask another what protocols it supports reliably?
* [[/Defining algebraic data types]] — sketch of a shortcut for defining data structures in the style of Haskell

=== Nonworking programs ===

* [[/Mac open event handler test]] — Can we have an [[E-on-Java]] app that handles Mac open events using the Apple Java extensions? No success yet.
* [[/ASTPrint.java]] — Minimal Java program attempting to set up an E-on-Java vat and do something in it. Doesn't work currently (or ever); haven't investigated.

Not even completely written:

* [[/unification.emaker]] — Implement unification variables in E: a single object which acts as promise and resolver, and a procedure which makes two values equal by resolving variables if possible. Incomplete code.

== Snippets ==

;Redefine interp.getArgs():
:<code>def scope := e`def baseInterp := interp;def interp extends baseInterp { to getArgs() { return [the new args] }}`.evalToPair(privilegedScope.nestOuter())[1]</code>
;Bring a file's definitions into REPL scope:
:<code>interp.setTopScope(e__quasiParser('''myFile'''.getTwine()).evalToPair(privilegedScope)[1])</code>

== Other material ==

* [[/JS bookmarks]] — JavaScript and Caja links.

== Todo ==

This should probably be migrated into an issue tracker. Right now we're nominally [http://sourceforge.net/tracker/?group_id=75274 using SourceForge], but I, at least, find it tedious to work with.

That said, these are my ''personal'' things-which-ought-to-be-done, and not the reflection of any consensus; I'm just dumping them here because it's better than them living in a random file on my hard disk.

=== E-on-Java work to do===

* Security
** Change the default taming policy for no-safej-file classes from ALL to NONE. (2010-02-27)
** Add shortcut syntax to [[SafeJ]] files for declaring allow-all, then replace the functionality of ApprovedClassList with safej files using that syntax. (2010-02-27)

* Cleanup
** Documentation, including impl-specific, should go to the wiki. Spec tests go to the wiki ([[:Category:E specification]]). Impl-specific (features and regression) tests stay in source tree. (2010-02-27)

* Features
** add fromKeysOf and fromValuesOf as [[ConstList]] and [[ConstMap]] maker methods. also rename fromIteratable to fromAssociationsOf (2008-03-24)
** Make setup.e-awt work on other platforms. (2008-03-24)
** Make setup use powerbox-style operation rather than being unconditionally privileged. (2008-03-24)
** Make [[TextWriter]]s [[pass by construction]], as provided in [[E-on-CL]]. (2008-03-24)
** Make objects print with FQN-prefix components if their local name is _, like they used to. (2008-03-24)
** Make safejTemplate.e into a caplet, if we can make it possible to give a caplet permission to run javap ... oh, my taming-command-line-tools framework (2008-03-24)
** Java subtyping relations should be exposed as Class's implementation of rangeSupersetOf
* ???
** https://sourceforge.net/tracker/index.php?func=detail&aid=1666433&group_id=75274&atid=551529 (2008-03-24)
** https://sourceforge.net/tracker/?group_id=75274&atid=551529 (2008-03-24)

* Bug fixes:
** powerboxControllerMakerAuthor.emaker -- JFileChooser usage treats cancel the same as OK (2008-03-24)
* Test fixes:
** makeIOUIssuer.updoc and sugar-demo.e-swt contain hardcoded references to ~/e/src/ which is wrong (2008-03-24)
** esrc/com/opencola/drm/example/MintMaker.updoc contains an expectation of E version (2008-03-24)
** esrc/org/erights/e/elang/interp/makeBootServer.updoc contains an expectation of install path (2008-03-24)
** esrc/org/erights/e/elib/sealing/makeVOCPair.emaker contains an expectation of ~ path (2008-03-24)
** esrc/org/erights/e/elib/slot/lamport.updoc has <_> where is now <everFormula> (2008-03-24)
** esrc/org/erights/e/examples/arith/makeRational.updoc ditto <makeRational> (2008-03-24)
** esrc/org/erights/e/extern/persist/persist.updoc runs out of heap space - ??? (2008-03-24)
** esrc/org/erights/e/facet/makeCaretaker.updoc expectation of cwd path (2008-03-24)

=== E-on-CL work to do/misc notes ===

* Old notes from Jul 17 2008:
** eocl r992:993 introduced a slowdown [in executing --updoc tests/captp/introducer.updoc].
** Stuff about custom method specializers in SBCL: [http://doc.gold.ac.uk/~mas01cr/tmp/skill.lisp] [http://doc.gold.ac.uk/~mas01cr/tmp/paper.pdf] [http://www.doc.gold.ac.uk/~mas01cr/tmp/mop-27.impure.lisp]
** [[transparent]] does NOT imply ok-for-[[Selfless]]. transparent can be mutable, e.g. [[FlexList]] (w/o value guard?) is transparent. TODO: revise Selfless to drop the independent Selfless auditor, in favor of TransparentSelfless approval, etc. -- because (Selfless+Transparent) isn't sufficient, we need to require immutability as well
** invocation for benchmarking + sprof-tree: <pre>time rlwrap ./clrune -L--eval -L'(require :sb-sprof)' -L--load -L ~/Documents/sbslow-project/sbcl/sprof-tree.lisp -L--eval -L'(setf sb-sprof:*sample-interval* 0.1)' -L--eval -L'(defun sb-sprof::report () (with-open-file (s "sampler-updoc.trace" :direction :output :element-type :default :if-exists :supersede) (sb-sprof::write-sampler-data s)))' -p ../sb-parse-cache.sexp --updoc --profile sb-sprof tests/captp/AnswersTable.updoc</pre>
*** this may be obsolete due to having profile options in clrune —[[User:Kevin Reid|Kevin Reid]] 08:56, 6 May 2010 (CDT)

=== For all implementations ===

* Take the draft utility library called 'Flow' and publish it, possibly as part of the E standard library
* meta.getState() is to be deprecated and replaced; it has the following flaws:
** Its result should be an [[Env]], not a [[ConstMap]], so as to avoid using any ampersands
** It uses the innermost enclosing object expression, so its presence means that introducing a function has possibly surprising effects; instead, it should take a parameter being the name of the object (i.e. <code>def foo() { meta.getEnv(foo) }</code>)

=== E design work ===

* Idea: Every directory serves as a root (that is, has the facilities of [[file__uriGetter|<file>]] like optUnget). This allows chrooting and allows updoc tests to be given virtual roots that aren't different in implementation from the real root.(2010-02-27)
** File pathname getting is tamed away, use <myRoot>.optUnget instead. The REPL's printFunc's textWriter has authority to show paths.
* Post as unresolved design issue whether to use E-on-CL's isQuoting and printSame methods in standard E. (2010-02-27)
* [[ConstList]] should have an operation analogous to [[FlexList#replace/5]].

=== Meta ===

* Post the contents of my 'To be discussed with MarkM' file on the wiki. (2010-02-27)

MediaWiki:Pagetitle

Kevin Reid — Wed, 18 Apr 2012 12:17:39 GMT

Kevin Reid: "Erights" is wrong capitalization and too broad: change to "ERights.org Wiki" and use emdash

$1 — ERights.org Wiki

E-benchmark

Kevin Reid — Sun, 19 Feb 2012 22:22:26 GMT

Kevin Reid: moved to GitHub

[[e-benchmark]] is an E program for benchmarking E implementations. It is very basic and was written by [[User:Kevin Reid|Kevin Reid]].

Repository: https://github.com/kpreid/e-benchmark

==Missing features==

* Benchmarking anything that happens over more than one turn.
* Saving results in a parseable form to a file.
** ...and then comparing results from multiple runs.
* Statistical interpretation of the results.

{{stub}}

E-on-CL

Kevin Reid — Sun, 19 Feb 2012 21:12:27 GMT

Kevin Reid: moved to GitHub

This is an implementation of [[E|E programming language]] in Common Lisp.

There are as yet no releases, but the source is available in a Git repository:

: https://github.com/kpreid/e-on-cl

==Status, Description==

The full E language is implemented, by compilation to Common Lisp and execution by the underlying CL implementation. The libraries are incomplete.

E-on-CL requires [[E-on-Java]] for:
* Support for the E parser (which is written in [http://www.antlr.org/ ANTLR].
* Parts of the library implementation (those <code>[[emaker]]</code>s which are not different)

There is Updoc and a REPL, written in CL.

IO is limited to:
* Writing text to stdout and stderr.
* Reading and writing files as text from absolute pathnames.
* TCP sockets, as octets or a small selection of character encodings.
* Unsafely accessing the underlying Lisp system.

===Differences from E-on-Java===

Support for EIO and <code>DeepFrozen</code> auditing.

throw() and CatchExpr have been changed to reduce information leakage: see [[sealed throw]].

<code>makeEProxyResolver</code> is replaced with <code>[[makeProxy]]</code>, a safer interface.

Updoc does not ignore the return value of expressions when the updoc script omits them.

==News==

For major announcements, watch [http://www.eros-os.org/mailman/listinfo/e-lang the e-lang mailing list]. For individual changes to the repository, [http://cia.navi.cx/stats/project/e-on-cl E-on-CL is monitored on cia.navi.cx] which offers status pages, RSS feeds, and IRC messages.

==Requirements==

*A Common Lisp implementation.E-on-CL is designed to be portable, but requires many nonstandard features for full operation. I use [http://www.sbcl.org/ SBCL], and therefore its support is the most complete. Other implementations E-on-CL includes some support for, roughly in order of completeness, are [http://ccl.clozure.com/ Clozure CL], [http://www.cons.org/cmucl/ CMUCL], [http://www.armedbear.org/abcl.html ABCL], [http://clisp.cons.org/ CLISP], [http://www.lispworks.com/downloads/index.html LispWorks], and [http://www.franz.com/downloads/trial.lhtml Allegro CL]. Whether E-on-CL works on any given implementation (other than SBCL) will vary as I make changes. If it doesn’t run on an implementation you’d like to use, please let me know and I’ll see what can be done about it.
* The [http://www.cliki.net/asdf-install asdf-install]able libraries [http://www.cliki.net/bordeaux-threads bordeaux-threads], [http://www.cliki.net/cl-ppcre cl-ppcre], [http://www.cliki.net/cl-yacc cl-yacc], [http://www.cliki.net/cl-fad cl-fad], [http://www.cliki.net/genhash genhash], [http://www.cliki.net/rt rt], and [http://www.cliki.net/trivial-garbage trivial-garbage].
* An existing [http://www.erights.org/download/ E-on-Java] installation.
* One of either:
** the E-on-Java source distribution, placed at <code><var>$EHOME</var>/src</code> ({{XXX|This is an inappropriate location}}), or
** the [http://www.cliki.net/asdf-install asdf-install]able libraries [http://www.cliki.net/ZIP ZIP] and [http://www.cliki.net/Salza Salza], which will be used to extract <code>.emaker</code> files from <code><var>$EHOME</var>/e.jar</code>.
* <code>bash</code> and <code>perl</code>, if you wish to use the standard startup script <code>clrune</code> (equivalent to <code>rune</code> in [[E-on-Java]].

==Previous discussion / timeline==

Posts from me on the e-lang list containing information about E-on-CL:

# [http://www.eros-os.org/pipermail/e-lang/2004-December/010199.html 2004-12-11: Initial announcement]
# [http://www.eros-os.org/pipermail/e-lang/2004-December/010210.html Early technical notes on the compilation method]
# [http://www.eros-os.org/pipermail/e-lang/2004-December/010208.html Message dispatch and 'native' object definition]
# [http://www.eros-os.org/pipermail/e-lang/2004-December/010241.html 2004-12-20: Status update]
# [http://www.eros-os.org/pipermail/e-lang/2005-April/010563.html 2005-04-16: Repository available]
# [http://www.eros-os.org/pipermail/e-lang/2005-April/010567.html Portability, naming, and usage info]
# [http://www.eros-os.org/pipermail/e-lang/2005-April/010587.html More of the same]
# [http://www.eros-os.org/pipermail/e-lang/2005-May/010605.html 2005-05-14: Reply to MarkM's comments on the source]
# [http://www.eros-os.org/pipermail/e-lang/2005-June/010758.html 2005-06-25: Status update]
# {{XXX|Fill in more recent info here.}}

[[Category:E implementations]]

E-XML

Kevin Reid — Thu, 16 Feb 2012 18:42:36 GMT

Kevin Reid: update repository link

An XML library for E, aiming to be the standard clean way to manipulate XML in E programs. By [[User:Kevin Reid]].

Repository: https://github.com/kpreid/e-xml

== Current state ==

The library provides XML quasiliterals, indexing them by XPath expressions, and coercion of text and attribute values to strings. It does not provide any proper way to read or write an XML document, or construct XML fragments.

Development is currently on hold; the most recent roadblock was constructing an efficient implementation of immutable trees with XPath support.

== Discussion ==

{{XXX|link e-lang archive messages from these dates:
Oct 26 2009
Jan 12 2010-continuing to Feb 17
Mar 10 2010
}}

E-on-JavaScript

Kevin Reid — Thu, 16 Feb 2012 18:24:18 GMT

Kevin Reid: new source location

E-on-JavaScript is an E implementation which compiles E to JavaScript code, suitable for running in web browsers.

The source is currently hosted [https://github.com/kpreid/e-on-javascript/ at GitHub].

It was designed to interoperate with [[Caja]], however it is not compatible with modern Caja so the rest of this paragraph is out of date. If cajita.js is also loaded,
E code can call Cajita-tamed objects; also, the output of the compiler
should be within the Cajita subset (I have not tested this). However, Cajita code can create objects which violate E [[sameness]] invariants.

It is as yet quite incomplete; especially, the compiler does not
implement all of Kernel-E, and generates inefficient and verbose code.

==Demo==

[http://www.slimy.com/~kpreid/eojs/demo/ Out-of-date demo] {{XXX|broken link}}

It supports converting an Updoc document, or a HTML document with embedded Updoc, into a HTML document such
that the tests are executed. [http://www.slimy.com/~kpreid/eojs/serve/vm.html A (stale) example].

Not-yet-executed tests have dashed bars to the left, successful tests
have light gray bars, and unsuccessful tests have red bars and show
the expected and actual values (which are not differentiated except by
color; this is to be fixed).

As this particular Updoc example was borrowed from [[E-on-CL]], many of the tests fail
because they are specific to E-on-CL in some way. Many other tests
fail because in the demonstrated version there was no printing subsystem yet, so everything uses
JS .toString() and thus the wrong syntax.

==History==

*[http://www.eros-os.org/pipermail/e-lang/2009-January/012946.html E-on-JavaScript announcement]
*[http://www.eros-os.org/pipermail/e-lang/2009-March/013070.html Announcement of Updoc conversion improvements]

[[Category:E implementations]]

Getting Started

Kevin Reid — Tue, 01 Nov 2011 14:57:35 GMT

Kevin Reid: Reverted edits by Reverse101 (Talk); changed back to last version by Kevin Reid

This page contains some helpful tips for people who are planning on learning E.

==Where to start==

* You should have basic knowledge of [[wikipedia:Java_(language)|Java]] and its [[wikipedia:Classpath_(Java)|class path system]].
* [[Downloads|Download]] and install '''''E'''''
* Read the [[Walnut]] - it is the most concise text on the '''''E''''' language and library.
* Bookmark the [http://erights.org/javadoc/index.html ELib api].
* Either download the '''''E''''' source or open the e.jar (for example with unzip) and take a look around.
* You can get information about '''''E''''' objects by using the help() method. For example, open rune and enter:

<code>? help([])</code>

You will get information about the ConstList class and its methods.
*[[Syntax-props-default.txt]] contains information about various language constructs not explained elsewhere at this point. In the '''''E''''' distribution, it is stored as: <code>org.erights.e.elang.syntax/syntax-props-default.txt</code>.
* The source also contains a number of [[Walnut/Ordinary_Programming/Emakers|emakers]] that can be used when developing programs. For example:
**<code>org.erights.e.facet.makeStoneCast.emaker</code>: An implementation of the [[Walnut/Secure_Distributed_Computing/Capability_Patterns#Facets|Facets]] pattern
**<code>org.erights.e.facet.makeCaretaker.emaker</code>: An implementation of the [[Walnut/Secure_Distributed_Computing/Capability_Patterns#Revocable_Capabilities|Revocable Capabilities]] pattern
**<code>org.erights.e.elib.slot.makeLamportSlot.emaker</code>: An implementation of the [http://www.erights.org/javadoc/org/erights/e/elib/slot/EverReporter.html EverReporter] pattern/interface

== [[Documentation]] and help==
* The [[Walnut]]
* The [http://erights.org/javadoc/index.html ELib api]
* Documentation on the [http://www.erights.org ERights homepage]. See [[List_of_papers]]
* The [http://www.eros-os.org/pipermail/e-lang/ '''''E''''' mailing list]. You can search the archives using google by including "site:eros-os.org" in the search field.

User:Kevin Reid/ASTPrint.java

Kevin Reid — Mon, 03 Oct 2011 11:36:09 GMT

Kevin Reid: repair wikitext=source

// Minimal Java program attempting to set up an E-on-Java vat and do something in it. Written 2008-10-11. Doesn't work as of 2010-11-22 testing; I don't recall whether I ever finished it. Result is <code>problem: <nowiki><NoSuchMethodException: <an HeadlessRunnerMgr__Maker>.getTHE_ONE/0></nowiki></code>

// [ It probably needs a <code>System.setProperty("e.safej.bind-var-to-propName", "true");</code> ] — [[User:ThomasLeonard]]

import org.erights.e.elang.interp.ScopeSetup;
import org.erights.e.elib.tables.Twine;
import org.erights.e.elib.prim.E;
import org.erights.e.elang.syntax.EParser;
import org.erights.e.elang.evm.ENode;
import org.erights.e.elib.serial.Loader;
import org.erights.e.elib.vat.Vat;

class ASTPrint {
public static void main(String[] args) {
try {
Vat vat = Vat.make("headless", "start");
Throwable optNoStart = vat.enqueue(new Runnable() {
public void run() {
ENode node = EParser.run(Twine.fromString("aardvarks"));
System.out.print(node);
Loader i = (Loader)(ScopeSetup.safeScope("__main$").get("import__uriGetter"));
Object converter = E.call(i.get("org.erights.e.elang.visitors.makeConvertENode2Term"), "run");
System.out.print(E.call(converter, "run", node));
}
});
if (null != optNoStart) {
throw optNoStart;
}
} catch (Throwable e) {
System.err.print(E.toString(e));
System.err.print(E.call(e, "eStack"));
}
}
}

Updoc

Kevin Reid — Mon, 26 Sep 2011 14:21:13 GMT

Kevin Reid: /* Running Updoc */ typo

''Updoc'' is a tool for creating checkable documentation and regression tests.

Please read more about it here: http://www.erights.org/elang/tools/updoc.html

==[[:Category:E specification|E specification]]==

The E specification contained in this wiki incorporates a test suite written in Updoc.

==Running Updoc==

In [[E-on-Java]], the program <code>scripts/updoc.e</code> runs Updoc tests. It takes one argument which is an Updoc file or a directory containing them. Updoc may be by itself, embedded in E source, or embedded in HTML.

{{XXX|Explain startup options}}

{{XXX|doc E-on-CL}}

==Updoc syntax and behavior==

{{XXX|write the rest of this}}

An updoc test failure occurs when the actual answers resulting from evaluation are not equal (except for stack traces) to the expected answers written in the test script.

{{XXX|Note: E-on-Java currently permits the actual "value" answer to be anything if the script does not contain one. We have decided that this behavior is too hazardous (hiding leaks) but it has not yet been fixed.}}

===Parsing===

Exactly like an interactive session, parser pragmas persist from one step to the next.

? accum [] for _ in "" { _ + [1] }; null
# syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off.

? pragma.enable("accumulator")
? accum [] for _ in "" { _ + [1] }; null
? pragma.syntax("0.9")
? accum [] for _ in "" { _ + [1] }; null
# syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off.

===Printing===

In the Updoc [[environment]], the text printed via the output objects <code>stdout</code>, <code>stderr</code>, <code>print</code>, and <code>println</code> is part of the results checked.

Semantics: stdout and stderr write to separate buffers. At the following times in the execution of each step, the contents of each buffer, if nonempty, are moved into answers named "stdout" and "stderr":
* after evaluation of the step, but before the <code>value</code> is printed
* after interp.waitAtTop/blockAtTop pauses and after all turns queued by the step have executed, but before the evaluation of the next step

{{XXX|Review whether this definition matches E-on-CL and E-on-Java}}

Line breaks and buffers:

? stdout.print("a")
# stdout: a

? stdout.print("a\n")
# stdout: a
#

? stdout.print("a"); stderr.print("b")
# stdout: a

# stderr: b

Timing:

? stdout.print("a"); stdout <- print("b"); "c"
# stdout: a

# value: "c"

# stdout: b

? # This step should have no output.

<code>print</code> and <code>println</code>:

? println("a", "b"); print("c", "d")
# stdout: ab
# cd

{{stub}}
[[Category:E specification]]

Updoc

Kevin Reid — Mon, 26 Sep 2011 14:18:38 GMT

Kevin Reid: stub section

''Updoc'' is a tool for creating checkable documentation and regression tests.

Please read more about it here: http://www.erights.org/elang/tools/updoc.html

==[[:Category:E specification|E specification]]==

The E specification contained in this wiki incorporates a test suite written in Updoc.

==Running Updoc==

In [[E-on-Java]], the program <code>scripts/updoc.e</scripts> runs Updoc tests. It takes one argument which is an Updoc file or a directory containing them. Updoc may be by itself, embedded in E source, or embedded in HTML.

{{XXX|Explain startup options}}

{{XXX|doc E-on-CL}}

==Updoc syntax and behavior==

{{XXX|write the rest of this}}

An updoc test failure occurs when the actual answers resulting from evaluation are not equal (except for stack traces) to the expected answers written in the test script.

{{XXX|Note: E-on-Java currently permits the actual "value" answer to be anything if the script does not contain one. We have decided that this behavior is too hazardous (hiding leaks) but it has not yet been fixed.}}

===Parsing===

Exactly like an interactive session, parser pragmas persist from one step to the next.

? accum [] for _ in "" { _ + [1] }; null
# syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off.

? pragma.enable("accumulator")
? accum [] for _ in "" { _ + [1] }; null
? pragma.syntax("0.9")
? accum [] for _ in "" { _ + [1] }; null
# syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off.

===Printing===

In the Updoc [[environment]], the text printed via the output objects <code>stdout</code>, <code>stderr</code>, <code>print</code>, and <code>println</code> is part of the results checked.

Semantics: stdout and stderr write to separate buffers. At the following times in the execution of each step, the contents of each buffer, if nonempty, are moved into answers named "stdout" and "stderr":
* after evaluation of the step, but before the <code>value</code> is printed
* after interp.waitAtTop/blockAtTop pauses and after all turns queued by the step have executed, but before the evaluation of the next step

{{XXX|Review whether this definition matches E-on-CL and E-on-Java}}

Line breaks and buffers:

? stdout.print("a")
# stdout: a

? stdout.print("a\n")
# stdout: a
#

? stdout.print("a"); stderr.print("b")
# stdout: a

# stderr: b

Timing:

? stdout.print("a"); stdout <- print("b"); "c"
# stdout: a

# value: "c"

# stdout: b

? # This step should have no output.

<code>print</code> and <code>println</code>:

? println("a", "b"); print("c", "d")
# stdout: ab
# cd

{{stub}}
[[Category:E specification]]

Talk:Future research topics

Kevin Reid — Wed, 21 Sep 2011 10:12:18 GMT

Kevin Reid: spam? irrelevant anyway

Capability

Kevin Reid — Tue, 20 Sep 2011 22:15:41 GMT

Kevin Reid: Add some info on URLs as capabilities

== Definition ==

A ''capability'' is a token that identifies an [[subject, object, operation and permission|object]] and provides its holder with the [[subject, object, operation and permission|permission]] to operate on the object it identifies. Capabilities must either be totally unforgeable or infeasible to forge by being ''sparse''.

== Examples ==
Some examples of unforgeable capabilities:
* Designations of objects in the [[E language]]. Those who hold these capabilities have the permission to invoke any method supported by the designated object.
* Designations of functions and procedures in [[Emily]]. Those who hold these capabilities have the permission to call designated functions or procedures.
* Capabilities held by a process in [[capability operating system]]s.
* POSIX file descriptors.
Some examples of sparse capabilities (sometimes called password capabilities):
* Designations of remote objects in E, such as <code>captp://*orwqphzlugjwqj2wozz7tmg47ime466j@74.125.87.147:55189/oa6vn5whhapylswhzesdlqh5ppmjkcrq.</code> Those who hold these capabilities have the permission to invoke any method supported by the designated object.
* Private URLs where having the URL is necessary and sufficient to use the resource. Common examples are:
** "Confirm your e-mail address" links for website account registrations, mailing list subscriptions or opt-outs, e.g. <code><nowiki>http://drupal.cbreurope.sk/civicrm/mailing/optout?reset=1&jid=XX&qid=XXXXX&h=XXXXXXXXXXXXXXXX&confirm=1</nowiki></code>
** Shared private documents such as in Google Docs, Google Maps, [http://picasa.google.com Picasa] albums, [http://www.doodle.com Doodle] schedulers.
* Designation of file-system sub-trees in [[MinorFs]], such as <code>/mnt/minorfs/cap/3d5d3efbf73bb711e7a47f82a44f471fcf77c70e/</code>

An [[Unum]] can be also considered as a capability to a (replicated) object in a similar way as file descriptors of transparently replicated files by RAID are still regarded as file descriptors.

== URLs as capabilities ==

As noted above, URLs are often used as capabilities in practice, especially when sent over e-mail. Some explicitly capability-structured systems, such as [[Tahoe-LAFS]], use capability URLs.

A hazard to using capability URLs directly in a web browser is that many browser extensions or options may transmit URLs to a third-party server. In the worst case, this may make those URLs public. However, there is some mitigation:
* The fragment part of a URL reference (<code>#id</code>) is not transmitted. If the browser supports executing JavaScript, then the capability can be placed in the fragment and transmitted only under script control, not as part of a URL.
* The query string part (<code>?foo=bar</code>) is often not transmitted. (Citation needed on this one!)

== See also ==

See [http://www.eros-os.org/essays/capintro.html What is a Capability, Anyway?] for a partisan explanation of what capabilities actually are.

See also [http://www.erights.org/elib/capability/overview.html Overview: Capability Computation]

{{stub}}

Sandbox

Kevin Reid — Sun, 18 Sep 2011 12:24:36 GMT

Kevin Reid: clear out sandbox

Use this page for test edits of the wiki.
----

Capability

Kevin Reid — Fri, 16 Sep 2011 11:52:36 GMT

Kevin Reid: sample URLs shouldn't be buried in actual links

== Definition ==

A ''capability'' is a token that identifies an [[subject, object, operation and permission|object]] and provides its holder with the [[subject, object, operation and permission|permission]] to operate on the object it identifies. Capabilities must either be totally unforgeable or infeasible to forge by being ''sparse''.

== Examples ==
Some examples of unforgeable capabilities:
* Designations of objects in the [[E language]]. Those who hold these capabilities have the permission to invoke any method supported by the designated object.
* Designations of functions and procedures in [[Emily]]. Those who hold these capabilities have the permission to call designated functions or procedures.
* Capabilities held by a process in [[capability operating system]]s.
* POSIX file descriptors.
Some examples of sparse capabilities (sometimes called password capabilities):
* Designations of remote objects in E, such as <code>captp://*orwqphzlugjwqj2wozz7tmg47ime466j@74.125.87.147:55189/oa6vn5whhapylswhzesdlqh5ppmjkcrq.</code> Those who hold these capabilities have the permission to invoke any method supported by the designated object.
* Private URLs where having the URL is necessary and sufficient to use the resource. Common examples are:
** "Confirm your e-mail address" links for website account registrations, mailing list subscriptions or opt-outs, e.g. <code><nowiki>http://drupal.cbreurope.sk/civicrm/mailing/optout?reset=1&jid=XX&qid=XXXXX&h=XXXXXXXXXXXXXXXX&confirm=1</nowiki></code>
** Shared private documents such as in Google Docs, Google Maps, [http://picasa.google.com Picasa] albums, [http://www.doodle.com Doodle] schedulers.
* Designation of file-system sub-trees in [[MinorFs]], such as <code>/mnt/minorfs/cap/3d5d3efbf73bb711e7a47f82a44f471fcf77c70e/</code>

An [[Unum]] can be also considered as a capability to a (replicated) object in a similar way as file descriptors of transparently replicated files by RAID are still regarded as file descriptors.

== See also ==

See [http://www.eros-os.org/essays/capintro.html What is a Capability, Anyway?] for a partisan explanation of what capabilities actually are.

See also [http://www.erights.org/elib/capability/overview.html Overview: Capability Computation]

{{stub}}

E-on-CL

Kevin Reid — Tue, 30 Aug 2011 20:05:19 GMT

Kevin Reid: Reverted edits by ShannonPatterson (Talk); changed back to last version by Kevin Reid

This is an implementation of [[E|E programming language]] in Common Lisp.

There are as yet no releases, but the source is available in a [http://subversion.tigris.org/ Subversion] repository:

: http://switchb.org/svn/e/cl-e/trunk/

==Status, Description==

The full E language is implemented, by compilation to Common Lisp and execution by the underlying CL implementation. The libraries are incomplete.

E-on-CL requires [[E-on-Java]] for:
* Support for the E parser (which is written in [http://www.antlr.org/ ANTLR].
* Parts of the library implementation (those <code>[[emaker]]</code>s which are not different)

There is Updoc and a REPL, written in CL.

IO is limited to:
* Writing text to stdout and stderr.
* Reading and writing files as text from absolute pathnames.
* TCP sockets, as octets or a small selection of character encodings.
* Unsafely accessing the underlying Lisp system.

===Differences from E-on-Java===

Support for EIO and <code>DeepFrozen</code> auditing.

throw() and CatchExpr have been changed to reduce information leakage: see [[sealed throw]].

<code>makeEProxyResolver</code> is replaced with <code>[[makeProxy]]</code>, a safer interface.

Updoc does not ignore the return value of expressions when the updoc script omits them.

==News==

For major announcements, watch [http://www.eros-os.org/mailman/listinfo/e-lang the e-lang mailing list]. For individual changes to the repository, [http://cia.navi.cx/stats/project/e-on-cl E-on-CL is monitored on cia.navi.cx] which offers status pages, RSS feeds, and IRC messages.

==Requirements==

*A Common Lisp implementation.E-on-CL is designed to be portable, but requires many nonstandard features for full operation. I use [http://www.sbcl.org/ SBCL], and therefore its support is the most complete. Other implementations E-on-CL includes some support for, roughly in order of completeness, are [http://ccl.clozure.com/ Clozure CL], [http://www.cons.org/cmucl/ CMUCL], [http://www.armedbear.org/abcl.html ABCL], [http://clisp.cons.org/ CLISP], [http://www.lispworks.com/downloads/index.html LispWorks], and [http://www.franz.com/downloads/trial.lhtml Allegro CL]. Whether E-on-CL works on any given implementation (other than SBCL) will vary as I make changes. If it doesn’t run on an implementation you’d like to use, please let me know and I’ll see what can be done about it.
* The [http://www.cliki.net/asdf-install asdf-install]able libraries [http://www.cliki.net/bordeaux-threads bordeaux-threads], [http://www.cliki.net/cl-ppcre cl-ppcre], [http://www.cliki.net/cl-yacc cl-yacc], [http://www.cliki.net/cl-fad cl-fad], [http://www.cliki.net/genhash genhash], [http://www.cliki.net/rt rt], and [http://www.cliki.net/trivial-garbage trivial-garbage].
* An existing [http://www.erights.org/download/ E-on-Java] installation.
* One of either:
** the E-on-Java source distribution, placed at <code><var>$EHOME</var>/src</code> ({{XXX|This is an inappropriate location}}), or
** the [http://www.cliki.net/asdf-install asdf-install]able libraries [http://www.cliki.net/ZIP ZIP] and [http://www.cliki.net/Salza Salza], which will be used to extract <code>.emaker</code> files from <code><var>$EHOME</var>/e.jar</code>.
* <code>bash</code> and <code>perl</code>, if you wish to use the standard startup script <code>clrune</code> (equivalent to <code>rune</code> in [[E-on-Java]].

==Previous discussion / timeline==

Posts from me on the e-lang list containing information about E-on-CL:

# [http://www.eros-os.org/pipermail/e-lang/2004-December/010199.html 2004-12-11: Initial announcement]
# [http://www.eros-os.org/pipermail/e-lang/2004-December/010210.html Early technical notes on the compilation method]
# [http://www.eros-os.org/pipermail/e-lang/2004-December/010208.html Message dispatch and 'native' object definition]
# [http://www.eros-os.org/pipermail/e-lang/2004-December/010241.html 2004-12-20: Status update]
# [http://www.eros-os.org/pipermail/e-lang/2005-April/010563.html 2005-04-16: Repository available]
# [http://www.eros-os.org/pipermail/e-lang/2005-April/010567.html Portability, naming, and usage info]
# [http://www.eros-os.org/pipermail/e-lang/2005-April/010587.html More of the same]
# [http://www.eros-os.org/pipermail/e-lang/2005-May/010605.html 2005-05-14: Reply to MarkM's comments on the source]
# [http://www.eros-os.org/pipermail/e-lang/2005-June/010758.html 2005-06-25: Status update]
# {{XXX|Fill in more recent info here.}}

[[Category:E implementations]]

Env

Kevin Reid — Sat, 27 Aug 2011 00:22:02 GMT

Kevin Reid: expand

Env: what [[Scope]] objects ought to be renamed to.

The error is long-standing in E's design, but [[User:Markm]] did not not want to use the technically correct “environment” since it was rather lengthy to write in code. [[User:Kevin Reid]] advocates using “Env”, this being both correct and short.

{{XXX|Expand this with actually explaining the protocol of Env objects. Also see Thomas Leonard's proposal that Scope objects in [[E-on-Java]] remain what they are for implementation efficiency while Envs have the nice user-facing and [[GBA]]-providing protocol.}}

{{stub}}

Env

Kevin Reid — Sat, 27 Aug 2011 00:18:49 GMT

Kevin Reid: Environment moved to Env: New short name preferred by MarkM

Environment: what [[Scope]] objects ought to be renamed to.

Environment

Kevin Reid — Sat, 27 Aug 2011 00:18:49 GMT

Kevin Reid: Environment moved to Env: New short name preferred by MarkM

#REDIRECT [[Env]]

Signature

Kevin Reid — Sat, 27 Aug 2011 00:18:32 GMT

Kevin Reid: finish subst

A [[Signature]] describes the protocol of another object.

This type is proposed to replace [[TypeDesc]], [[MessageDesc]], and [[ParamDesc]]; the motivation for doing so is that while TypeDesc allows for message parameters' [[guard]]s to be presented, it is difficult to define the means for doing so as a [[miranda method]]; Signature is defined so as to simplify this. Furthermore, it is arguably "fewer moving parts" in that rather than having the TD/MD/PD structure imitating a subset of what Kernel-E can express, we use Kernel-E directly.

(REVIEW: Should we adopt Signature in place of TypeDesc?)

(REVIEW: What should the expansion of the nonkernel "interface" expression be, given that we eliminate MessageDesc and ParamDesc which it uses? -- MarkM suggests expanding to an ObjectExpr which is asked for its alleged type, and then twiddling it further.)

(XXX Define the [[Miranda __getAllegedType/0]] behavior under this system precisely.)

(XXX [[User:Kevin Reid]] needs to review the experimental code and add other design decision questions to this page.)

== State ==

* <code>objectExpr</code> :[[ObjectExpr]]
* <code>env</code> :[[Env]]
* <code>supers</code> :[[List]]<nowiki>[</nowiki>[[Signature]]]
* <code>mirandaSignature</code> :[[Signature]]

The most important fields of a signature are the ''object expr'' and ''env''.

The object expr is the expression of the object which this is the signature of (or the closest approximation, if the object is not written in E), except redacted: the method and matcher bodies have been replaced with UnspecifiedExpr, a new [[EExpr]] introduced for this purpose, and the auditors (<code>as</code> (if under [[Guard-based auditing|GBA]]) and <code>implements</code> clauses) have been eliminated.

The environment field contains an [[Env]] with bindings for every free noun in the redacted version of the object expr. (These will mostly be guards.)

(REVIEW: This proposal therefore exposes every object mentioned in a parameter list. Is this too hazardous? (MarkM feels that the simple rule of "everything between the braces is public" (i.e. from the { of the object to the { of a method) helps.) Are there practical ways to reduce the potential harm from mentioning authority-bearing objects? ([[User:Kevin Reid]],[[User:Markm]],[[User:dtribble]] have discussed this 2008-08-14 and decided that nothing need be done.))

The supers field lists additional signatures of protocols which this object also implements, such as by <code>[[extends]]</code>, or explicit protocols, or multiple inheritance in objects implemented in languages providing such. The significance of the ordering of the list is left to the generator of the signature.

The miranda signature field holds a signature containing the miranda protocol in use by the E implementation hosting the object whose signature this is. This is the means provided for E programs to see the miranda protocol, and it replaces TypeDesc's approach of including the miranda MessageDescs in every __getAllegedType TypeDesc. It also might be used to detect un-translated mismatches between E system versions.

(NOTE: A planned extension is to allow type-parameterized protocols. This will be done by allowing nouns not bound in the env, but bound by a parameter list instead. Such a signature responds to get/N returning a concrete protocol.)

== Maker protocol ==

(XXX there is no way to specify the mirandaSignature.)

=== asType/0 ===
{{asType|Signature}}

{{maker msgdoc|run|2|objectExpr :[[ObjectExpr]], env :[[Env]]|[[Signature]]}}

As run/3 but with the supers field being <code>[]</code>.

{{maker msgdoc|run|3|objectExpr :[[ObjectExpr]], env :[[Env]], supers :[[List]]<nowiki>[</nowiki>[[Signature]]]|[[Signature]]}}

{{unspecified message}}

== Protocol ==

{{instance msgdoc|getObjectExpr|0||[[ObjectExpr]]}}

Accessor; see state description.

{{instance msgdoc|getEnv|0||[[Env]]}}

Accessor; see state description.

{{instance msgdoc|getMirandaSignature|0||[[Signature]]}}

Accessor; see state description.

{{instance msgdoc|getSupers|0||[[List]]<nowiki>[</nowiki>[[Signature]]]}}

Accessor; see state description.

{{instance msgdoc|getFQName|0||[[String]]}}

Returns the [[fully-qualified name]] constructed from the environment's FQN prefix and the object expr's pattern.

(XXX Define the method of construction.)

[[Category:ELib specification]]
[[Category:Unresolved design issues]]

Signature

Kevin Reid — Sat, 27 Aug 2011 00:17:34 GMT

Kevin Reid: /* State */ s/Scope/Env/

A [[Signature]] describes the protocol of another object.

This type is proposed to replace [[TypeDesc]], [[MessageDesc]], and [[ParamDesc]]; the motivation for doing so is that while TypeDesc allows for message parameters' [[guard]]s to be presented, it is difficult to define the means for doing so as a [[miranda method]]; Signature is defined so as to simplify this. Furthermore, it is arguably "fewer moving parts" in that rather than having the TD/MD/PD structure imitating a subset of what Kernel-E can express, we use Kernel-E directly.

(REVIEW: Should we adopt Signature in place of TypeDesc?)

(REVIEW: What should the expansion of the nonkernel "interface" expression be, given that we eliminate MessageDesc and ParamDesc which it uses? -- MarkM suggests expanding to an ObjectExpr which is asked for its alleged type, and then twiddling it further.)

(XXX Define the [[Miranda __getAllegedType/0]] behavior under this system precisely.)

(XXX [[User:Kevin Reid]] needs to review the experimental code and add other design decision questions to this page.)

== State ==

* <code>objectExpr</code> :[[ObjectExpr]]
* <code>env</code> :[[Env]]
* <code>supers</code> :[[List]]<nowiki>[</nowiki>[[Signature]]]
* <code>mirandaSignature</code> :[[Signature]]

The most important fields of a signature are the ''object expr'' and ''env''.

The object expr is the expression of the object which this is the signature of (or the closest approximation, if the object is not written in E), except redacted: the method and matcher bodies have been replaced with UnspecifiedExpr, a new [[EExpr]] introduced for this purpose, and the auditors (<code>as</code> (if under [[Guard-based auditing|GBA]]) and <code>implements</code> clauses) have been eliminated.

The environment field contains an [[Env]] with bindings for every free noun in the redacted version of the object expr. (These will mostly be guards.)

(REVIEW: This proposal therefore exposes every object mentioned in a parameter list. Is this too hazardous? (MarkM feels that the simple rule of "everything between the braces is public" (i.e. from the { of the object to the { of a method) helps.) Are there practical ways to reduce the potential harm from mentioning authority-bearing objects? ([[User:Kevin Reid]],[[User:Markm]],[[User:dtribble]] have discussed this 2008-08-14 and decided that nothing need be done.))

The supers field lists additional signatures of protocols which this object also implements, such as by <code>[[extends]]</code>, or explicit protocols, or multiple inheritance in objects implemented in languages providing such. The significance of the ordering of the list is left to the generator of the signature.

The miranda signature field holds a signature containing the miranda protocol in use by the E implementation hosting the object whose signature this is. This is the means provided for E programs to see the miranda protocol, and it replaces TypeDesc's approach of including the miranda MessageDescs in every __getAllegedType TypeDesc. It also might be used to detect un-translated mismatches between E system versions.

(NOTE: A planned extension is to allow type-parameterized protocols. This will be done by allowing nouns not bound in the env, but bound by a parameter list instead. Such a signature responds to get/N returning a concrete protocol.)

== Maker protocol ==

(XXX there is no way to specify the mirandaSignature.)

=== asType/0 ===
{{asType|Signature}}

{{maker msgdoc|run|2|objectExpr :[[ObjectExpr]], env :[[Scope]]|[[Signature]]}}

As run/3 but with the supers field being <code>[]</code>.

{{maker msgdoc|run|3|objectExpr :[[ObjectExpr]], env :[[Scope]], supers :[[List]]<nowiki>[</nowiki>[[Signature]]]|[[Signature]]}}

{{unspecified message}}

== Protocol ==

{{instance msgdoc|getObjectExpr|0||[[ObjectExpr]]}}

Accessor; see state description.

{{instance msgdoc|getEnv|0||[[Scope]]}}

Accessor; see state description.

{{instance msgdoc|getMirandaSignature|0||[[Signature]]}}

Accessor; see state description.

{{instance msgdoc|getSupers|0||[[List]]<nowiki>[</nowiki>[[Signature]]]}}

Accessor; see state description.

{{instance msgdoc|getFQName|0||[[String]]}}

Returns the [[fully-qualified name]] constructed from the environment's FQN prefix and the object expr's pattern.

(XXX Define the method of construction.)

[[Category:ELib specification]]
[[Category:Unresolved design issues]]

Verb

Kevin Reid — Sun, 07 Aug 2011 03:54:33 GMT

Kevin Reid: see also Noun; formally define as being String

A verb is a string.

The verb is one of the parts of a message or a method signature; in other languages it might be called the "method name" or "selector". Ordinary E objects dispatch to methods based on the combination of the verb and the ''arity'', the number of arguments; this combination is conventionally written “<var>verb</var>/<var>arity</var>” (e.g. “add/1”) and when used in a program is known as a ''mangled verb'' or ''mverb''.

def Verb := String

==See also==

* [[Object E#call/3|E#call/3]]
* [[Miranda respondsTo]]
* [[Miranda getAllegedType]]
* [[Noun]]

[[Category:ELib specification]]

Mangled verb

Kevin Reid — Sun, 07 Aug 2011 03:53:04 GMT

Kevin Reid: Redirecting to Verb

#REDIRECT [[Verb]]

Miranda order

Kevin Reid — Sun, 07 Aug 2011 03:52:42 GMT

Kevin Reid: let's have an explicit verb type

{{instance msgdoc|__order|2|<var>verb</var> :[[Verb]], <var>args</var> :[[List]]|[[any]]}}

'''__order/2''' is a [[Miranda message]] for sending messages contingent on an earlier success.

This method does the equivalent of

to __order(verb, args) :any {
[E.call(self, verb, args), self]
}

In other words, it calls the receiving object with the message
<code><var>verb</var>(<var>args...</var>)</code>, and, if successful, returns a pair
of the result of this call and the receiving object itself.

What is this for? Consider the client code fragment

databaseRcvr <- put(key1, value1)
def value2Vow := databaseRcvr <- get(key2)
E's [http://www.erights.org/elib/concurrency/partial-order.html partial ordering semantics]
ensure that put will be delivered before
get is delivered. That is often good enough. But it is a weaker
guarantee than that provided by the following sequential code

database put(key1, value1)
def value2Vow := database get(key2)

In this code, not only will get only happen after put is delivered, get
will only happen after put ''succeeds''. If put instead throws an
exception, the get will never happen. Often we want this effect. How can
we achieve this with eventual-sends to eventual references?

When one wants to take an action contingent on the results of a previous
action, the conventional E answer is to use a when-catch-finally
expression

def ackVow := databaseRcvr <- put(key1, value1)
def value2Vow := when (ackVow) -> {
databaseRcvr <- get(key2)
} catch problem {
throw(problem)
}

This is fine, as is probably the solution to be used by default for this
situation. However, it does force a round-trip between the get and put,
and so loses the benefits of pipelining. Using the __order message, we
can get contingent execution + pipelining, at some cost in obscurity.
(Note: often, the cost of obscurity will dominate.)

def pairVow := databaseRcvr <- __order("put", [key1, value1])
# If put's return value were interesting, we'd 'pairVow <- get(0)'
def newDBRcvr := pairVow <- get(1)
def value2Vow := newDBRcvr <- get(key2)

If put throws, then <var>pairVow</var> will resolve directly to broken, so newDB
will likewise resolve to broken, as will <var>value2Vow</var>.

===Distinguishing unresolved response from unresolved value===

It is also possible to use __order to observe when the turn caused by an eventual send finishes, even if its return value is itself an unresolved promise, by waiting for the returned tuple, or its second element, to resolve.

[[Category:Miranda messages]]
[[Category:Pluribus]]

Miranda protocol

Kevin Reid — Sun, 07 Aug 2011 03:52:25 GMT

Kevin Reid: let's have an explicit verb type

Every normal object responds to these '''miranda messages'''; [[miranda methods]] are provided for them.

* [[Miranda conformTo|__conformTo]](<var>guard</var> :[[Guard]]) :[[any]]
* [[Miranda getAllegedType|__getAllegedType]]() :[[TypeDesc]]
* [[Miranda getPropertySlot|__getPropertySlot]](<var>property</var> :[[String]]) :Slot
* [[Miranda optSealedDispatch|__optSealedDispatch]](<var>brand</var> :[[any]]) :[[any]]
* [[Miranda optUncall|__optUncall]]() :[[Portrayal]]
* [[Miranda order|__order]](<var>verb</var> :[[Verb]], <var>args</var> :[[List]]) :[[Tuple]]<nowiki>[</nowiki>any, any<nowiki>]</nowiki>
* [[Miranda printOn|__printOn]](<var>out</var> :[[TextWriter]]) :[[void]]
* [[Miranda reactToLostClient|__reactToLostClient]](<var>problem</var>) :[[void]]
* [[Miranda respondsTo|__respondsTo]](<var>verb</var> :[[Verb]], <var>arity</var> :[[int]]) :[[Boolean]]
* [[Miranda whenBroken|__whenBroken]](<var>reactor</var>) :[[void]]
* [[Miranda whenMoreResolved|__whenMoreResolved]](<var>reactor</var>) :[[void]]

== Constraints on revision of this protocol ==

No version of the Miranda protocol shall introduce a Miranda message which has the same verb but different arity as another Miranda message. '''Rationale:''' This ensures that if a plumbing object forwards messages, adding leading/trailing arguments, it will not invoke a Miranda method of the forwarding target.

== See also ==

* [http://www.erights.org/javadoc/org/erights/e/elib/prim/MirandaMethods.html MirandaMethods class] in [[E-on-Java]]
* [http://www.erights.org/elib/distrib/captp/index.html CapTP protocol documentation], section “Helper Messages”

[[Category:ELib specification]]
[[Category:Protocols]]

Verb

Kevin Reid — Sun, 07 Aug 2011 03:51:29 GMT

Kevin Reid:

A verb is a string.

A verb is one of the parts of a message or a method signature; in other languages it might be called the "method name" or "selector". Ordinary E objects dispatch to methods based on the combination of the verb and the ''arity'', the number of arguments; this combination is conventionally written “<var>verb</var>/<var>arity</var>” (e.g. “add/1”) and when used in a program is known as a ''mangled verb'' or ''mverb''.

==See also==

* [[Object E#call/3|E#call/3]]
* [[Miranda respondsTo]]
* [[Miranda getAllegedType]]

[[Category:ELib specification]]

Miranda respondsTo

Kevin Reid — Sun, 07 Aug 2011 03:46:38 GMT

Kevin Reid:

'''__respondsTo/2''' is a [[Miranda message]] for asking whether an object understands a message.

{{instance msgdoc|__respondsTo|2|<var>verb</var> :[[Verb]], <var>arity</var> :([[int]] > 0)|[[boolean]]}}

Returns a boolean indicating whether this object responds to messages with the verb <var>verb</var> and arity (number of arguments) <var>arity</var>.

The Miranda method for E-language objects is:
# If this object has a method with the given verb and arity, return true.
# If there is a [[Miranda method]] with the given verb and arity, return true.
# If the object has a [[matcher]], return the result of invoking the matcher with the __respondsTo message. If the matcher does not match, return false.
# Return false.
{{XXX|confirm this is an accurate description of current behavior.}}

[[Category:Miranda messages]]

Miranda conformTo

Kevin Reid — Sun, 07 Aug 2011 03:39:04 GMT

Kevin Reid: add javadoc

'''__conformTo/1''' is a [[Miranda message]].

{{instance msgdoc|__conformTo|1|<var>guard</var> :[[Guard]]|[[any]]}}

====Clients====

A guard which does not immediately accept the recipient may call <code>__conformTo</code>(the guard) on it, and check and return the result thereof instead.

====Implementations====

Implementations of <code>__conformTo/1</code> should return the recipient if they have no better answer.

====Miranda behavior====

Returns the recipient.

? def obj {}
> obj.__conformTo(any)
# value: <obj>

? obj.__conformTo(List)
# value: <obj>

? obj.__conformTo(def bobj {})
# value: <obj>

? obj.__conformTo(null)
# value: <obj>

==Original Javadoc==

{{XXX|merge}}

When a guard doesn't succeed by itself at coercing an object, the guard
may enlists the object's aid in bring about a coercion it would find
acceptable.

A guard enlists the object's aid at the price of being
[http://www.sims.berkeley.edu/~ping/auditors/ Gozarian]. A
Gozarian guard wants to enlists the object's aid because it is
ignorant of the kind of object it's dealing with, so a generic protocol
is needed. That's why __conformTo/1 is provided as a MirandaMethod.

The guard asks the object to conform to some guard that the object may
know about. Often this will be the guard that's attempting the coercion.
An object should attempt to return a representation of itself that the
argument guard would succeed in coercing. A requesting guard should then
try again on the result, but if this doesn't coerce, it should fail
there rather than making further __conformTo/1 requests. This implies
that it's the responsibility of the object's __conformTo/1
implementation to do any iteration needed for multi-step conversions.

The default (Miranda) implementation of __conformTo/1 just returns
self.

[[Category:Miranda messages]]

Miranda printOn

Kevin Reid — Sun, 07 Aug 2011 03:33:23 GMT

Kevin Reid:

'''__printOn/1''' is a [[Miranda message]] which constitutes E's protocol for turning objects into strings.

{{instance msgdoc|__printOn|1|<var>out</var> :[[TextWriter]]|[[void]]}}

{{XXX|Loosen spec to permit non-text-writers}}

Print a representation of or name for this object on the provided [[TextWriter]].

The TextWriter is responsible for breaking cycles.

The Miranda method is:
to __printOn(out) {
out.write("<" + the simple name from this object's FQN + ">")
}

==Tests==

{{XXX|Write tests}}

[[Category:Miranda messages]]

Miranda optSealedDispatch

Kevin Reid — Sun, 07 Aug 2011 03:25:06 GMT

Kevin Reid: create from javadoc

'''__optSealedDispatch/1''' is a [[Miranda message]].

{{instance msgdoc|__optSealedDispatch|1|<var>brand</var> :[[Brand]]|[[void]]}}

Generic object-level rights amplification protocol.

Dispatch on the brand much as one would dispatch on a message name. If
we recognize the brand and we have the corresponding sealer, then we may
return something meaningful inside a [[SealedBox]] sealed with that [[Sealer]].
If we have nothing to return, given the meaning we associate with that
brand as a request, then we return null.

Something meaningful? Sounds strange. See [http://www.eros-os.org/pipermail/e-lang/2002-May/006435.html <nowiki>[e-lang]</nowiki> Object coercion / adaptation] and the surrounding thread for more on
the rationale for the design of this method. Note that, at the time of
that discussion, this method was named getOptMeta instead.

The default implementation: return null.

If this object isn't actually transparent, but if <tt>brand</tt>
represents a party this object would like to reveal itself to (such as a
serialization system implementing persistence for this object's
subsystem), then this object can choose to return a [[SealedBox]], sealed by
the by the [[Sealer]] for that brand, containing the same triple that [[Miranda optUncall|__optUncall]] would otherwise have returned. By so doing, the object
reveals its internals only to someone having the corresponding
[[Unsealer]].

[[Category:Miranda messages]]

Miranda getPropertySlot

Kevin Reid — Sun, 07 Aug 2011 03:21:09 GMT

Kevin Reid: add method header

'''__getPropertySlot/1''' is a deprecated [[Miranda message]].

{{instance msgdoc|__getPropertySlot|1|<var>propName</var> :[[String]]|[[Slot]]}}

==Original Javadoc==

Used in the expansion of '<tt>foo::bar</tt>' so that this syntax
represents foo's "bar" property.

'<tt>foo::bar</tt>' expands to '<tt>foo.__getPropertySlot("bar").get()</tt>'.
When used an an lValue, '<tt>foo::bar := newValue</tt>' expands
essentially to '<tt>foo.__getPropertySlot("bar").put(newValue)</tt>'
except that the expansion also has the value of the assignment
expression be the value assigned.

And finally '<tt>foo::&bar</tt>' expands to '<tt>foo.__getPropertySlot("bar")</tt>'
<hr> The Miranda behavior provided here synthesizes, for foo's bar
property, a Slot object <ul> <li>whose '<tt>get()</tt>' does a
'<tt>foo.getBar()</tt>' <li>whose '<tt>put(newValue)</tt>' does a
'<tt>foo.setBar(newValue)</tt>' <li>and whose '<tt>isFinal()</tt>'
returns false</tt>'. </ul>

See also: [http://www.eros-os.org/pipermail/e-lang/2004-April/009720.html Re: On kernel-E, operators, and properties (part 1)]

'''Deprecated:''' Even if E does again decide to support explicit properties,
it'll do it with a global function that asks the object's
{@link #__getAllegedType} for the methods for its
properties.

== Issues ==

This protocol should probably be deprecated and removed, as it does not compose under inheritance. Thread: [http://www.eros-os.org/pipermail/e-lang/2005-December/thread.html#11042] [http://www.eros-os.org/pipermail/e-lang/2006-January/thread.html#11064]

[[Category:Miranda messages]]
[[Category:Unresolved design issues]]

Miranda getPropertySlot

Kevin Reid — Sun, 07 Aug 2011 03:19:27 GMT

Kevin Reid: Add Javadoc.

==Original Javadoc==

Used in the expansion of '<tt>foo::bar</tt>' so that this syntax
represents foo's "bar" property.

'<tt>foo::bar</tt>' expands to '<tt>foo.__getPropertySlot("bar").get()</tt>'.
When used an an lValue, '<tt>foo::bar := newValue</tt>' expands
essentially to '<tt>foo.__getPropertySlot("bar").put(newValue)</tt>'
except that the expansion also has the value of the assignment
expression be the value assigned.

And finally '<tt>foo::&bar</tt>' expands to '<tt>foo.__getPropertySlot("bar")</tt>'
<hr> The Miranda behavior provided here synthesizes, for foo's bar
property, a Slot object <ul> <li>whose '<tt>get()</tt>' does a
'<tt>foo.getBar()</tt>' <li>whose '<tt>put(newValue)</tt>' does a
'<tt>foo.setBar(newValue)</tt>' <li>and whose '<tt>isFinal()</tt>'
returns false</tt>'. </ul>

See also: [http://www.eros-os.org/pipermail/e-lang/2004-April/009720.html Re: On kernel-E, operators, and properties (part 1)]

'''Deprecated:''' Even if E does again decide to support explicit properties,
it'll do it with a global function that asks the object's
{@link #__getAllegedType} for the methods for its
properties.

== Issues ==

This protocol should probably be deprecated and removed, as it does not compose under inheritance. Thread: [http://www.eros-os.org/pipermail/e-lang/2005-December/thread.html#11042] [http://www.eros-os.org/pipermail/e-lang/2006-January/thread.html#11064]

[[Category:Miranda messages]]
[[Category:Unresolved design issues]]

Miranda whenBroken

Kevin Reid — Sun, 07 Aug 2011 03:08:27 GMT

Kevin Reid:

'''__whenBroken/1''' is a [[Miranda message]] for determining when a reference has become a [[broken reference]].

{{instance msgdoc|__whenBroken|1|<var>reactor</var> :[[OneArgFunc]]|[[void]]}}

Notify the <var>reactor</var> when the reference has transitioned to the [[broken]] state.

* The Miranda method ignores the argument and returns null, as a near reference cannot become broken.
* If the recipient is an [[eventual ref]], then the message should not be forwarded, but the reactor should be stored for use as follows. (This forms part of the expected behavior of any [[proxy]] handler.)
** If it becomes broken, <code><var>reactor</var> <- run(<var>problem</var>)</code> should be performed for every __whenBroken message previously received.
** If it becomes resolved to another ref, then it should forward every __whenBroken message it received to the target.

==Original Javadoc==

{{XXX|merge}}

Used to implement "Ref whenBroken/2"; it should not be called directly.

The Miranda behavior ignores the message, as only breakable ref
implementations ever respond to this message.

See also: [[Ref#whenBroken/2]]

==Tests==

{{XXX|Write tests}}

[[Category:Miranda messages]]
[[Category:Pluribus]]

Miranda whenMoreResolved

Kevin Reid — Sun, 07 Aug 2011 02:56:36 GMT

Kevin Reid: clean up, incorporate javadoc

'''__whenMoreResolved/1''' is a [[Miranda message]].

{{instance msgdoc|__whenMoreResolved|1|<var>reactor</var> :[[OneArgFunc]]|[[void]]}}

Notify the <var>reactor</var> when the reference is resolved, or is importantly ''closer'' to being resolved; specifically when it has become the [[same]] as a reference into a different vat (is a candidate for [[shortening]]).

* If the recipient is a [[near ref]], then the Miranda method should be:
to __whenMoreResolved(reactor) {
reactor <- run(<var>recipient</var>)
return null
}
* If the recipient is a [[local promise]] then it should buffer and forward the message normally.
* If the recipient is a [[remote promise]] then {{XXX|Specify the CapTP-related behavior.}}

==Original Javadoc==

{{XXX|merge}}

Used to implement when-catch and the "[[Ref#whenResolved/2]]"; it should not
be called directly.

The Miranda behavior responds by doing 'reactor <- run(self)'. If the
reference never becomes resolved, the reactor is not invoked.

In the cooperative (non-malicious) case, the reactor will not be invoked
more than once.

When sent on a reference, once the reference becomes resolved the
reactor will be invoked with the resolution. Should the reactor be
invoked with a non-broken reference, all earlier messages are guaranteed
to have been successfully delivered.

Should the reference become broken, or should breakage prevent the
reporting of fulfillment to the reactor, the reactor will be invoked
with a broken reference. The reactor may be invoked more than once. In
particular, if the reference becomes fulfilled and then broken, the
reactor may hear of either or both of these events.

See also: [[Ref#whenBroken/2]]

==Tests==

? var r := null
> def ret := 1 <- __whenMoreResolved(fn x { r := x + 1 })
> interp.waitAtTop(ret)
> ret
# value: <Promise>

? r
# value: 2

? [ret]
# value: [null]

{{XXX|Above tests do not check for reactor<-run rather than reactor.run}}

[[Category:Miranda messages]]
[[Category:Pluribus]]

Miranda getAllegedType

Kevin Reid — Mon, 01 Aug 2011 04:44:09 GMT

Kevin Reid:

{{instance msgdoc|getAllegedType|0||[[TypeDesc]]}}

__getAllegedType/0 is a [[Miranda message]]. It returns a description of the protocol this object alleges to implement.

The [[Miranda method]] for this message, for E objects, returns a TypeDesc generated from the object's actual method signatures and doc-comments, combined with the response to __getAllegedType/0 of its matcher.

==See also==

* The [[Signature]] proposal.

[[Category:Miranda messages]]

Miranda optUncall

Kevin Reid — Mon, 01 Aug 2011 04:40:41 GMT

Kevin Reid: import javadoc

'''__optUncall/0''' is a [[Miranda message]] which may return a [[portrayal]] of the object receiving it.

{{instance msgdoc|__optUncall|0||[[Portrayal]]}}

The [[miranda method]] for this message always returns <code>[[null]]</code>.

For [[Selfless]] objects, __optUncall is guaranteed to return a portrayal which exactly represents the object; if <var>a</var> is selfless, then <var>a</var> [[==]] E.call(E, "call", <var>a</var>.__optUncall()).

__optUncall is typically used by serialization systems for the default portrayal in the absence of other knowledge about the object.

===Original Javadoc===

Note: The terminology and taxonomy of this text may be outdated. {{XXX|Update this text and integrate it into the wiki}}

This should return either <code>null</code> or a triple describing a call
that, if performed, will create an object resembling this one.

Scalars (ints, float64s, chars, boolean, null) and bare Strings are
''atomic''. __optUncall on an atomic objects return null,
but atomic objects are still considered transparent. Objects which
return non-null are ''non-atomic'' and ''transparent''. Non-atomic
objects that return null are ''opaque''. Opaque objects may be
''selectively transparent'' to certain clients by implementing
[[Miranda optSealedDispatch|__optSealedDispatch]] as described there.

When a transparent non-atomic object is [[Selfless]], then the
result of __optUncall is guaranteed to be accurate: It
describes a call that, when performed, must result in this very same
object, according to [[Ref#isSameEver|E's "==" operation]]. The
Selfless auditor ensures that all Selfless objects are accurately
self-describing in this way.

The uncall of a Selfless object is canonical, so if x and y are both
Selfless, then

x == y iff x.__optUncall() == y.__optUncall()

Performing the call described by the uncall of a non-Selfless object
generally creates whatever that object wished to create as its
representative, but because it had to provide the ingredients, its
representative could only be something it could have created. Therefore,
the representative cannot convey any more authority than the original
object itself has.

[[Category:Miranda messages]]

Miranda order

Kevin Reid — Mon, 01 Aug 2011 04:17:48 GMT

Kevin Reid: Distinguishing unresolved response from unresolved value

{{instance msgdoc|__order|2|<var>verb</var> :[[String]], <var>args</var> :[[List]]|[[any]]}}

'''__order/2''' is a [[Miranda message]] for sending messages contingent on an earlier success.

This method does the equivalent of

to __order(verb, args) :any {
[E.call(self, verb, args), self]
}

In other words, it calls the receiving object with the message
<code><var>verb</var>(<var>args...</var>)</code>, and, if successful, returns a pair
of the result of this call and the receiving object itself.

What is this for? Consider the client code fragment

databaseRcvr <- put(key1, value1)
def value2Vow := databaseRcvr <- get(key2)
E's [http://www.erights.org/elib/concurrency/partial-order.html partial ordering semantics]
ensure that put will be delivered before
get is delivered. That is often good enough. But it is a weaker
guarantee than that provided by the following sequential code

database put(key1, value1)
def value2Vow := database get(key2)

In this code, not only will get only happen after put is delivered, get
will only happen after put ''succeeds''. If put instead throws an
exception, the get will never happen. Often we want this effect. How can
we achieve this with eventual-sends to eventual references?

When one wants to take an action contingent on the results of a previous
action, the conventional E answer is to use a when-catch-finally
expression

def ackVow := databaseRcvr <- put(key1, value1)
def value2Vow := when (ackVow) -> {
databaseRcvr <- get(key2)
} catch problem {
throw(problem)
}

This is fine, as is probably the solution to be used by default for this
situation. However, it does force a round-trip between the get and put,
and so loses the benefits of pipelining. Using the __order message, we
can get contingent execution + pipelining, at some cost in obscurity.
(Note: often, the cost of obscurity will dominate.)

def pairVow := databaseRcvr <- __order("put", [key1, value1])
# If put's return value were interesting, we'd 'pairVow <- get(0)'
def newDBRcvr := pairVow <- get(1)
def value2Vow := newDBRcvr <- get(key2)

If put throws, then <var>pairVow</var> will resolve directly to broken, so newDB
will likewise resolve to broken, as will <var>value2Vow</var>.

===Distinguishing unresolved response from unresolved value===

It is also possible to use __order to observe when the turn caused by an eventual send finishes, even if its return value is itself an unresolved promise, by waiting for the returned tuple, or its second element, to resolve.

[[Category:Miranda messages]]
[[Category:Pluribus]]

Template:Instance msgdoc

Kevin Reid — Mon, 01 Aug 2011 04:06:58 GMT

Kevin Reid: how 'bout a label?

=== {{{1}}}/{{{2}}} ===
[[Category:Message {{{1}}}/{{{2}}}]]
:''Signature:'' {{{1}}}({{{3}}}) :{{{4}}}<noinclude>

Usage of this template: <nowiki>{{instance msgdoc|verb|arity|parameters|result type}}</nowiki></noinclude>

Template:Instance msgdoc

Kevin Reid — Mon, 01 Aug 2011 04:04:32 GMT

Kevin Reid: indent signature. let's see if this looks good.

=== {{{1}}}/{{{2}}} ===
[[Category:Message {{{1}}}/{{{2}}}]]
: {{{1}}}({{{3}}}) :{{{4}}}<noinclude>

Usage of this template: <nowiki>{{instance msgdoc|verb|arity|parameters|result type}}</nowiki></noinclude>

Miranda order

Kevin Reid — Mon, 01 Aug 2011 03:59:23 GMT

Kevin Reid: Documentation from MirandaMethods.java (licensed by MarkM's stated blanket permission)

{{instance msgdoc|__order|2|<var>verb</var> :[[String]], <var>args</var> :[[List]]|[[any]]}}

'''__order/2''' is a [[Miranda message]] for sending messages contingent on an earlier success.

This method does the equivalent of

to __order(verb, args) :any {
[E.call(self, verb, args), self]
}

In other words, it calls the receiving object with the message
<code><var>verb</var>(<var>args...</var>)</code>, and, if successful, returns a pair
of the result of this call and the receiving object itself.

What is this for? Consider the client code fragment

databaseRcvr <- put(key1, value1)
def value2Vow := databaseRcvr <- get(key2)
E's [http://www.erights.org/elib/concurrency/partial-order.html partial ordering semantics]
ensure that put will be delivered before
get is delivered. That is often good enough. But it is a weaker
guarantee than that provided by the following sequential code

database put(key1, value1)
def value2Vow := database get(key2)

In this code, not only will get only happen after put is delivered, get
will only happen after put ''succeeds''. If put instead throws an
exception, the get will never happen. Often we want this effect. How can
we achieve this with eventual-sends to eventual references?

When one wants to take an action contingent on the results of a previous
action, the conventional E answer is to use a when-catch-finally
expression

def ackVow := databaseRcvr <- put(key1, value1)
def value2Vow := when (ackVow) -> {
databaseRcvr <- get(key2)
} catch problem {
throw(problem)
}

This is fine, as is probably the solution to be used by default for this
situation. However, it does force a round-trip between the get and put,
and so loses the benefits of pipelining. Using the __order message, we
can get contingent execution + pipelining, at some cost in obscurity.
(Note: often, the cost of obscurity will dominate.)

def pairVow := databaseRcvr <- __order("put", [key1, value1])
# If put's return value were interesting, we'd 'pairVow <- get(0)'
def newDBRcvr := pairVow <- get(1)
def value2Vow := newDBRcvr <- get(key2)

If put throws, then <var>pairVow</var> will resolve directly to broken, so newDB
will likewise resolve to broken, as will <var>value2Vow</var>.

[[Category:Miranda messages]]
[[Category:Pluribus]]

Miranda methods

Kevin Reid — Tue, 26 Jul 2011 18:40:45 GMT

Kevin Reid:

A Miranda method is a method which, if it is not defined on a given object, is implicitly given a default definition. There are Miranda methods for every message in the [[Miranda protocol]]; descriptions of the Miranda methods may be found on each Miranda message's page.

[[Category:ELib specification]]

{{stub}}

Miranda protocol

Kevin Reid — Tue, 26 Jul 2011 18:38:52 GMT

Kevin Reid: add no-same-verb constraint

Every normal object responds to these '''miranda messages'''; [[miranda methods]] are provided for them.

* [[Miranda conformTo|__conformTo]](<var>guard</var> :[[Guard]]) :[[any]]
* [[Miranda getAllegedType|__getAllegedType]]() :[[TypeDesc]]
* [[Miranda getPropertySlot|__getPropertySlot]](<var>property</var> :[[String]]) :Slot
* [[Miranda optSealedDispatch|__optSealedDispatch]](<var>brand</var> :[[any]]) :[[any]]
* [[Miranda optUncall|__optUncall]]() :[[Portrayal]]
* [[Miranda order|__order]](<var>verb</var> :[[String]], <var>args</var> :[[List]]) :[[Tuple]]<nowiki>[</nowiki>any, any<nowiki>]</nowiki>
* [[Miranda printOn|__printOn]](<var>out</var> :[[TextWriter]]) :[[void]]
* [[Miranda reactToLostClient|__reactToLostClient]](<var>problem</var>) :[[void]]
* [[Miranda respondsTo|__respondsTo]](<var>verb</var> :[[String]], <var>arity</var> :[[int]]) :[[Boolean]]
* [[Miranda whenBroken|__whenBroken]](<var>reactor</var>) :[[void]]
* [[Miranda whenMoreResolved|__whenMoreResolved]](<var>reactor</var>) :[[void]]

== Constraints on revision of this protocol ==

No version of the Miranda protocol shall introduce a Miranda message which has the same verb but different arity as another Miranda message. '''Rationale:''' This ensures that if a plumbing object forwards messages, adding leading/trailing arguments, it will not invoke a Miranda method of the forwarding target.

== See also ==

* [http://www.erights.org/javadoc/org/erights/e/elib/prim/MirandaMethods.html MirandaMethods class] in [[E-on-Java]]
* [http://www.erights.org/elib/distrib/captp/index.html CapTP protocol documentation], section “Helper Messages”

[[Category:ELib specification]]
[[Category:Protocols]]

Miranda reactToLostClient

Kevin Reid — Tue, 26 Jul 2011 18:35:20 GMT

Kevin Reid:

'''__reactToLostClient/1''' is a [[Miranda message]].

{{instance msgdoc|__reactToLostClient|1|<var>problem</var> :XXX|[[void]]}}

__reactToLostClient/1 is delivered to an object when one of its clients may no longer be able to contact it due to network partition.

A typical use of __reactToLostClient is to revoke a [[caretaker]] in the event of the revoker's client losing access to it.

====Miranda behavior====

Does nothing.

? def obj {}
> obj.__reactToLostClient("foo")
# value: null

? obj.__reactToLostClient(null)
# value: null

{{stub}}
[[Category:Miranda messages]]
[[Category:ELib specification]]

Miranda whenMoreResolved

Kevin Reid — Tue, 26 Jul 2011 18:30:09 GMT

Kevin Reid: subcategorized, no longer needs to be in ELib cat directly

'''__whenMoreResolved/1''' is a [[Miranda message]].

{{instance msgdoc|__whenMoreResolved|1|<var>reactor</var> :[[OneArgFunc]]|[[void]]}}

The overall effect is to notify the <var>reactor</var> when the reference is resolved, or is ''closer'' to being resolved — in particular, when a resolution has changed its target to another vat. {{XXX|poor terminology}}

If the recipient is a [[near ref]], then the Miranda method should be:
to __whenMoreResolved(reactor) {
reactor <- run(<var>recipient</var>)
return null
}

? var r := null
> def ret := 1 <- __whenMoreResolved(fn x { r := x + 1 })
> interp.waitAtTop(ret)
> ret
# value: <Promise>

? r
# value: 2

? [ret]
# value: [null]

{{XXX|Above tests do not check for reactor<-run rather than reactor.run}}

If the recipient is a [[local promise]] then it should buffer and forward the message normally.

If the recipient is a [[remote promise]] then {{XXX|Specify the CapTP-related behavior.}}

[[Category:Miranda messages]]
[[Category:Pluribus]]

Category:Miranda messages

Kevin Reid — Tue, 26 Jul 2011 18:28:47 GMT

Kevin Reid: subcategorize

Messages which are part of the [[Miranda protocol]].
[[Category:ELib specification]]

Miranda conformTo

Kevin Reid — Tue, 26 Jul 2011 18:27:57 GMT

Kevin Reid: uniform style for miranda pages

Miranda optUncall

Kevin Reid — Tue, 26 Jul 2011 18:27:35 GMT

Kevin Reid: uniform style for miranda pages

Miranda whenMoreResolved

Kevin Reid — Tue, 26 Jul 2011 18:26:58 GMT

Kevin Reid: uniform style for miranda pages

Integer

Kevin Reid — Tue, 26 Jul 2011 18:25:30 GMT

Kevin Reid: mention guard, etc

[[Integer]] is one of the built-in numeric types in [[ELib]]. Integers may be literals in [[E language]] source.

In the [[universal environment]], the Integer guard is named <code>int</code>.

==Maker protocol==

{{maker msgdoc|run|1|<var>string</var> :[[String]]|[[Integer]]}}

{{specbycode|{{this}}.run(<var>string</var>, 10)}}

{{maker msgdoc|run|2|<var>string</var> :[[String]], base :(0..36)|[[Integer]]}}

Convert <var>string</var> to an integer. If it does not match the following syntax then an exception is thrown. {{need-ejector-arg}}

<var>string</var> must contain only an optional leading minus sign "-" (U+002D), followed by at least one digit of the specified base ("0"-"9" for bases up to 10, then "a"-"z" or "A"-"Z" for additional digits up to base 36).

==Tests==

Many E implementations have multiple representations of Integers for different size ranges. These implementations ''must'' be indistinguishable, or there must be exactly one representation for any given integer.

? def a := 4
# value: 4

? def b := (400000000000000000000 // 100000000000000000000)
# value: 4

? a == b
# value: true

? a.__getAllegedType()
# value: int

? b.__getAllegedType()
# value: int

? 400000000000000000000.__getAllegedType()
# value: int

[[Category:ELib specification]]
{{stub}}