Syntax-props-default.txt

From Erights

Revision as of 12:07, 29 November 2006 by Mscheffler (Talk)
Jump to: navigation, search
  1. Copyright 2004, Hewlett Packard, Inc. under the terms of the MIT X license
  2. found at http://www.opensource.org/licenses/mit-license.html ................
  1. XXX documentation obsolete. Should be rewritten to de-emphasize versions
  2. per se, and instead mostly talk groups of switch settings.
  1. Settings of syntactic properties for a particular form of E. The
  2. expansion of E to Kernel-E depends upon these switches. Nothing else
  3. should.
  1. The settings of these switches that support a particular version of
  2. E are given by first reading the resource file
  3. 'syntax-props-<major_version>.txt', where the <major_version>
  4. string of is just the first two numeric part of the version
  5. separated by dots. For example, the major_version of the "0.8.25n"
  6. is "0.8".
  1. These files are in the classpath and accessible by E expressions
  2. like
  3. <resource:org/erights/e/elang/syntax/syntax-props-<version>.txt>
  4. where the appropriate text is substituted for <version>.
  5. An individual E compilation unit can declare itself to be written in
  6. a particular version of E by saying, for example:
  7. pragma.syntax("0.8")
  8. This has exactly the effect of loading the definitions corresponding
  9. that version of E, in order to effect the parsing and expansion of
  10. the remainder of this compilation unit. (XXX We should insist that
  11. this directive occur as a top-level expression, to avoid ambiguity
  12. as to when it starts to apply. We don't enforce this yet, but you
  13. should follow this practice.) This directive does *not* cause any
  14. further attempts to be compatible with that version beyond the
  15. changes caused by these switch settings.
  1. Over time, the switches used to describe each version may change in
  2. order to, as closely as possible, continue to support that old
  3. version of the language in the context of the new language
  4. implementation. The first priority is to ensure that, *if a program
  5. is accepted*, then its meaning is adequately preserved. When the old
  6. meaning of old constructs is no longer supported, the settings of
  7. these switches should disallow those constructs, causing programs
  8. using these constructs to be statically rejected.
  1. As the language changes, the default settings are likely to get more
  2. restrictive over time, so that a program which does not declare its
  3. version is likely to be restricted to that subset of the language
  4. which means the same thing in all the versions of the language since
  5. 0.8.25n.


  1. To ease the transition to the new restricted syntax, you can set
  2. some of the switches below to 'warn' or 'true'.
  1. This syntax switch mechanism was originally added to allow
  2. experimentation. All these features were added for reasons that
  3. seemed good at the time. If you feel a particular feature's revival
  4. (making it again part of official E) is a good idea, please try it
  5. out and if you still think it would be a good idea, please speak up
  6. and explain why.


  1. If e.enable.anon-lambda is set to 'true', E accepts the
  2. " 'fn' params... '{' eExpr '}' lambda shorthand. To turn a program
  3. using this feature into a proper
  4. modern E program, this form should be prefixed by 'def' and the
  5. method body should be explicitly declared with 'method' rather than
  6. 'to', since an anon-lambda doesn't bind '__return'.

e.enable.anon-lambda=true


  1. Accept the 'eExpr::bar' shorthand as a representation of the . 'eExpr::bar'
  2. as an expression expands to 'eExpr.__getPropertySlot("bar").getValue()'. If
  3. the Miranda __getPropertySlot/1 is not overridden, this will be equivalent to
  4. 'eExpr.getBar()'. 'eExpr1::bar := eExpr2' expands (approximately) to
  5. 'eExpr.__getPropertySlot("bar").setValue(eExpr2)', which, when using the
  6. Miranda behavior, will be equivalent to 'eExpr1.setBar(eExpr2)'. Finally,
  7. 'eExpr::&bar' expands to 'eExpr.__getPropertySlot("bar")'. The Miranda
  8. behavior of this synthesizes a Slot whose getValue/0, setValue/1 accesses
  9. eExpr's getBar/0, setBar/1.
  10. We say "(approximately)" above, since the value of the assignment expression
  11. will be the value expr2 evaluates to.

e.enable.dot-props=allow


  1. Accept the experimental 'meta.getState()' expression, which reifies
  2. the current lexical environment into a ConstMap. The semantics of
  3. this construct only has the scope within an object include those
  4. variables defined outside the object that are used freely within the
  5. object -- the instance variables. This is currently a kernel
  6. construct, but will likely get redefined as syntactic shorthand that
  7. expands to a collection-definition expression.
  8. Also controls other experimental meta constructs in the same
  9. category, which, until 0.8.25e, included 'meta.context()'.
  10. ('meta.context()' is now an official part of the language, since it is used
  11. by the expansion of 'interface'.

e.enable.meta-scope=true


  1. Accept the " 'def' name.verb(params...) {...}" definition
  2. shorthand. Instead, the explicit object definition syntax should be
  3. used, where this method is an explicit method.

e.enable.one-method-object=allow


  1. Accept the experimental
  2. " 'def' name 'match' pattern '{' eExpr '}' "
  3. kernel construct. This is not a shorthand, so if you need it
  4. there's nothing to do instead.

e.enable.plumbing=true


  1. Once upon a time, there was general agreement that a tab character
  2. in a plain text file took you to the next tab stop, which was every
  3. 8 characters. The Microsoft blight has not only screwed up the
  4. newline conventions and the filepath separator conventions (of which
  5. the Mac is equally guilty), but also screwed up the meaning of the
  6. tab key. The best path to sanity is to simply avoid the presence of
  7. tab characters in text files, with the one unfortunate exception of
  8. "Makefile"s and "*.mk" files.
  9. Unfortunately, because so many text editors put tabs into files in a
  10. way that's hard to turn off, E must, by default, accept tabs as a
  11. valid whitespace character. However, to help you prevent yourself
  12. from including tabs, we provide the "notabs" switch, which defaults
  13. to "false". If you set it to true, the tab character will not be
  14. considered valid whitespace.

e.enable.notabs=allow


  1. Enables syntax such as 'require (cond) else {str}' to be accepted
  2. and be equivalent of
  3.     require.else__control(fn{[[cond],fn{str}]}).run__control()

e.enable.lambda-args=allow


  1. Enable the deprecated 'delegate' syntax, which has been superceded by
  2. 'extends'.

e.enable.delegate-clause=allow


                                1. New as of 0.8.20 #######################


  1. Allows the expression syntax '[..., => foo, ...]' as shorthand for
  2. '[..., "foo" => foo, ...]'

e.enable.exporter=true


  1. Allows the pattern syntax '[..., => foo, ...]' as shorthand for
  2. '[..., "foo" => foo, ...]'

e.enable.importer=true


  1. In the context of a map-pattern, whether the explicit one or the one
  2. using the above importer syntax, e.enable.pattern-default enables a
  3. value-pattern position to also include an optional default value, so
  4. that
  5.     map =~ [..., "foo" => foo := expr, ...]
  6. or
  7.     map =~ [..., => foo := expr, ...]
  8. will succeed even if map contains no mapping for
  9. "foo", in which case foo will be bound to the
  10. value of the expr.
  11. Note: the above proposed syntax sucks, but the semantics seems
  12. good. What would be a better syntax?

e.enable.pattern-default=true


  1. In reaction to the bug "<a href=
  2. "http://bugs.sieve.net/bugs/?func=detailbug&bug_id=125519&group_id=16380"
  3. >need type guard on data from renderer</a>", these three switches
  4. exist so an individual module may elect to enable them for itself,
  5. forcing itself to be more explicit. Such per-module enabling can be
  6. done with, for example, a
  7. pragma.enable("explicit-final-guard")<tt>.
  8. When off ('false' or 'allow'), the corresponding guard declarations
  9. may be ommitted, in which case a default guard is provided. When on
  10. ('true'), those guard declarations must always be explicitly
  11. provided. The official E language allows all these kinds of guards
  12. to be ommitted, and therefore these switches must not be 'true' by
  13. default.
  14. <p>
  15. Note that the definition of an object name in an object definition
  16. expression does not allow a guard, so none of these switches will
  17. cause one to be required there.
  18. <p>
  19. As with all pragmas, these pragma swicthes are not part of the
  20. official E language. In fact, we expect to retire these swicthes
  21. and migrate the ability to ask for this extra check into an advisory
  22. static checker.
  23. e.enable.explicit-slot-guard added as of 0.8.23g

e.enable.explicit-final-guard=allow e.enable.explicit-var-guard=allow e.enable.explicit-slot-guard=allow e.enable.explicit-result-guard=true

  1. Allows the new "accumulator" syntax that has most of the advantages
  2. of list comprehension (from Haskell and Python), but is more
  3. E-like. For example, with this property enabled, one can write:
# accum [] for i in 1..5 { + i**2 } #
  1. to accumulate the list [ 1, 4, 9, 16, 25 ]. This expands into
# { # var accum_n := [] # for i in 1..5 { # accum_n += { i**2 } # } # accum_n # } #
  1. Note that this is more flexible but more verbose than a list
  2. comprehension, and less flexible and comparably verbose to a
  3. Smalltalk injection.

e.enable.accumulator=allow


  1. Turns on the unary prefix '*' operator.
# *x
  1. expands to
  2. x.getValue()
  3. so, by the normal assignment rules,
# *x := y
  1. expands approximately to
  2. x.setValue(y)
  3. except that the expansion also arranges for the value of the
  4. expression to be the value of y.

e.enable.unary-star=allow


                                1. New as of 0.8.23g #######################
  1. e.enable.explicit-slot-guard added as of 0.8.23g, but it appears
  2. above because it's part of a group.
  1. Has two related effects. It makes a left out method result guard
  2. default to the equivalent of :any (internally represented with a
  3. null), and it changes the expansion of 'to' methods into primitive
  4. methods so that an explicit return is required to return a non-null
  5. value.
# to foo() { ... } ===> method foo() :void { escape __return { ... } }
  1. to
  2. to foo() { ... } ===> method foo() { escape __return { ...; null } }

e.enable.easy-return=allow

                                1. New as of 0.8.24c #######################
  1. Allows the 'escape' expression, and the loop expressions which build
  2. on it -- 'while', 'for' -- to be optionally followed by an
  3. escape-handler. As of the 0.8.24c release, the optional
  4. escape-handler is written with the same syntax as the catch-clause
  5. of a try-catch block: 'catch' pattern '{' expression '}'.
  6. An escape expression with an escape-handler is therefore written as
# escape ejector-pattern { # body-expression # } catch handler-pattern { # handler-expression # } #
  1. If such an escape expression, if the ejector is invoked during the
  2. execution of body-expression, body-expression is terminated, the
  3. handler-pattern is matched against the argument to the ejector, and
  4. the handler-expression is evaluated in the resulting scope.
  5. In a while-loop or for-loop with a escape-handler, if the break
  6. ejector is called, the loop is exited and the argument to break is
  7. passed to the handler.

e.enable.escape-handler=true

                                1. New as of 0.8.25h #######################
  1. Allows the syntax (ignoring precedence)
  2.     expr ::= specimen-expr ':' guard-expr
  3. which expands to
# Guard.coerce(guard-expr, null).coerce(specimen-expr, null) #

e.enable.cast=true


                                1. New as of 0.8.25h #######################
  1. Allows the use of unary prefix '^' as a synonym for 'return'.

e.enable.smalltalk-return=warn

                                1. New as of 0.8.25h #######################
  1. Allows a literal string anywhere an identifier would be accepted as a verb

e.enable.verb-string=true

                                1. New as of 0.8.30b #######################
  1. Allows 'foo.bar' to expand to
  2. '__makeVerbFacet.curryCall(foo, "bar")', so that '(foo.bar)(x,y)' can
  3. have the same effect as 'foo.bar(x,y)'.
  4. Likewise, allows 'foo <- bar' to expand to
  5. '__makeVerbFacet.currySend(foo, "bar")', so that '(foo <- bar)(x,y)' can
  6. have the same effect as 'foo <- bar(x,y)'.
  7. The result should be a function which responds to "run" with any number
  8. of arguments by calling (or sending) the corresponding "bar" method on the
  9. "foo" object. Inspired by the <a href="http://www.waterken.com"
  10. >web-calculus</a>, this is a cheap notation for forming a bar-only
  11. unforseen-facet (a filtering forwarder, sort-of) on the "foo" object.

e.enable.verb-curry=allow

                                1. New as of 0.8.32f #######################
  1. Enables various short forms of the when-catch construct, as discussed in the
  2. thread starting at
  3. http://www.eros-os.org/pipermail/e-lang/2004-December/010242.html

e.enable.easy-when=true

  1. Enables '->'s to be chained, forming what this thread refers to as an
  2. "event sequence". (Dean points out that "when sequence" is less ambiguous,
  3. since E has many event sequences.)

e.enable.when-sequence=allow

                                1. New as of 0.8.33o #######################
  1. Allows a literal string anywhere an identifier would be accepted as a noun

e.enable.noun-string=allow

                                1. New as of 0.8.34p #######################
  1. Used to allow the syntax
  2. "def" pattern ":=" "(" rValueExpr "," optEjectorExpr ")"
  3. As of 0.8.36s, allows the syntax
  4. "def" pattern "exit" optEjectorExpr ":=" rValueExpr

e.enable.trinary-define=allow

                                1. New as of 0.8.37b #######################
  1. http://www.eros-os.org/pipermail/e-lang/2006-July/011407.html

e.enable.call-pattern=allow

                                1. Discontinued Switches ####################


  1. The e.enable.bind switch has been retired, since 'bind' is now
  2. considered an official part of the language.
  1. The e.enable.meta-object switch has been retired, since 'meta(name)'
  2. is no longer supported, even as an experimetal feature.
  1. The e.enable.sub-object switch has been retired, since the 'extends'
  2. syntax is now considered an official part of the language.
  1. The e.enable.define switch has been retired, since we are now
  2. committed to spelling this keyword only as 'def'.
  1. The e.enable.no-paren-call switch has been retired, since no-parens
  2. following a dot are now an object-property access, and no-dot-calls
  3. are now deprecated.
  1. The e.enable.no-paren-method switch has been retired, since it makes
  2. little sense without the availability of e.enable.no-paren-call.
  1. in 0.8.18 and 0.8.19, the e.enable.explicit-*-guard switches were
  2. instead named e.enable.implicit-*-guard, and had the opposite
  3. sense. This was switched to preserve the property that the official
  4. language as of any release is defined by the behavior when all
  5. e.enable.* switches are off.
        1. Discontinued as of 0.8.20 ####
  1. e.enable.typedef, as the interface shorthand for creating a
  2. rubber-stamping auditor/guard is now an official part of the
  3. language/
  1. e.enable.auditors, as the 'implements' syntax for requiring auditor
  2. approval is now an official part of E and Kernel-E. (thanks Ping!)
  1. e.enable.new-constructor is now retired. Its documentation used to
  2. say:
  3. Constructors in E are now mapped to the 'run' method name. They
  4. used to be mapped to the 'new' method name instead. When this flag
  5. is turned on, constructors are mapped to the 'new' method name in
  6. addition to the 'run' mapping. This applies in two contexts:
  7. 1) To the expansion of the E language 'class' expression. This is
  8. done on a per-emaker basis controllable by the usual
  9. 'pragma enable(..)' and 'pragma disable(..)', and is only relevent
  10. in contexts where e.enable.class-expr is also true.
  11. 2) To the binding of a Java class constructor to an E method name.
  12. This done only on a per-JVM basis. Per-vat or per-emaker settings
  13. of these flags have no further effect.
        1. Discontinued as of 0.8.23j ####
  1. Enable the deprecated 'class' syntax, which has been superceded by
  2. 'extends'.
  3. e.enable.class-expr=allow
        1. Discontinued as of 0.8.26d ####
  1. e.enable.no-dot-call is now retired. Rather than the old
  2. 'bob foo(carol)', one must now write 'bob.foo(carol)'.
  1. e.enable.when-clauses is now retired. This alternate when-catch
  2. syntax was never used and would have been a bad idea.
        1. Discontinued as of 0.8.30c ####
  1. e.enable.synthetic-slot=allow used to enable a particular expansion of
  2. unary prefix '&' applied to a non-noun lValue expression.
  1. e.enable.access-slot=allow was to allow another expansion of
  2. unary prefix '&' applied to a non-noun lValue expression.
        1. Discontinued as of 0.8.36e ####
  1. Enables an argument list to end with a sequence of map associations
  2. without needing to surround them with square brackets. Likewise, it
  3. enables a parameter list to end with a sequence of map association
  4. patterns. This makes name-based parameters seem first class.
  1. e.enable.map-tail=true
        1. Discontinued as of 0.8.36s ####
  1. Allows the syntax "given" rValueExpr "=~" pattern
  2. e.enable.given=allow
  1. Allows the syntax "given" "(" rValueExpr "," optEjectorExpr ")" "=~" pattern
  2. e.enable.trinary-given=allow
  1. Allows the syntax rValueExpr "into" pattern
  2. e.enable.into=allow
  1. Allows the syntax rValueExpr "into" "^" "(" optEjectorExpr ")" pattern
  2. e.enable.trinary-into=allow
        1. Discontinued as of 0.8.37a ####
  1. Allows the use of a literal string as an object-expr's qualified or
  2. fully-qualified name.
  1. e.enable.literal-oname=allow

Personal tools
more tools