[e-lang] Announcing E 0.8.20t: A preview of a real 0.8.20

Mark S. Miller e-lang@mail.eros-os.org
Sun, 29 Sep 2002 18:36:28 -0700


At 06:51 AM 9/22/2002 Sunday, Mark S. Miller wrote:
>I expect this version of 0.8.20 [0.8.20t] will be useful only to Constantine.  Many 
>things don't yet work, but the reorganization of the parts of ELib relevant 
>to Constantine's work is done and works great.  [...]
>
>I should at least be posting new javadoc-umentation soon.  Much 
>documentation about the new Constantine-relevant stuff is already in 
>doc-comments in the org.erights.e.elib.vat package. [...]

The new javadoc-umentation is now posted at 
http://www.erights.org/javadoc/index.html , and represents real progress 
towards edoc. This documentation includes all the public interface of Java 
code available to the ELib programmer, both from the E implementation 
itself, and for each java or SWT package which contains any tamed class. 
Besides the normal javadoc info, these pages also reflect the taming of the 
API. (I should be able to include doc-comments extracted from E code soon, 
but not quite yet.)


Each class or interface is annotated with an initial bold:

* "Safe:" -- if the class is importable via the import__uriGetter, ie, by an 
  expression of the form
     <import:...>
  A class should only be declared Safe when it's enabled (see below) 
  constructors and static members provide no ability to effect or be effected 
  by the world outside the invoking object (ie, provide no "authority" as we 
  define the term). If you see any questionable Safe declarations, please 
  ask. Our security rests on not making errors of inclusion here. Note:
  the AWT and Swing classes currently declared Safe will be reclassified 
into a new category, since we don't ever expect to completely tame these.

* "Unsafe:" -- if the class is importable via the unsafe__uriGetter, ie, by an 
  expression of the form
     <unsafe:...>
  A class should only be declared Unsafe when there's a clear theory of the 
  authority provided by its enabled constructors and static members, and when 
  these have been tamed in accordance with this theory.

* "Untamed:" -- if this class has not been tamed. Currently, such classes 
  are still importable via <unsafe:...>, but this will eventually be 
  controlled by a properties setting, with the default being for untamed 
  classes to be unimportable. However, we can't make this change until we make 
  it *much* easier to tame existing classes.


Each member (method, constructor, or field) is annotated with an initial bold:

* "Enabled:" -- if this member is visible both to Java clients and to E/ELib 
  clients. A member should only be enabled if it follows capability 
  discipline. For a constructor or static member, this means it provides no 
  more authority than is thought to be provided by the imported class (the 
  class' maker). For an instance member, this means it provides no more 
  authority than is thought to be provided by an instance.

* "Suppressed:" -- if the member is not visible to the E-language 
  programmer, nor to the ELib programmer via the ELib invocation mechanisms 
  (E.call(...), E.send(...), etc). These are still accessible to the Java 
  programmer, and therefore to the ELib programmer when using Java's "." 
  operator.

* "Added:" -- if the member is directly visible to the E/ELib programmer as 
  if it were a member of the class, though it's actually a static public 
  member of a sugaring class. The Java programmer must invoke these indirectly 
  by calling the static member instead. For example using

  http://www.erights.org/javadoc/java/awt/Component.html#transferFocus(java.awt.Component[],%20java.awt.Component)

  the E-language programmer can say

      def makeComponent := <import:java.awt.Component>
      makeComponent.transferFocus(oldComponents, newComponent)

  whereas the Java programmer would say

      import org.erights.e.meta.java.awt.ComponentMakerSugar;
      ComponentMakerSugar.transferFocus(oldComponents, newComponent);

  For an added instance method, like 

  http://www.erights.org/javadoc/java/awt/Component.html#iterate(org.erights.e.elib.tables.AssocFunc)

  the Java programmer would provide the receiver as first argument to the static method:

      import org.erights.e.meta.java.awt.ComponentSugar;
      ComponentSugar.iterate(component, assocFunc);



In getting something like an edoc right, the trick is to choose the right 
level of detail. I have a feeling the current pages presents both too much 
and too little, but I'm not sure what to do about it. In any case, it makes 
the evolving design of our system sufficiently visible that it should allow 
us all to spot issues much easier. 

Finally, returning to Constantine's original needs, see 
http://www.erights.org/javadoc/org/erights/e/elib/vat/Vat.html



----------------------------------------
Text by me above is hereby placed in the public domain

        Cheers,
        --MarkM