Syntax-props-default.txt

Some embedded html tags removed below to avoid interfering with wiki logic. None of these changes affect the meaning of the text.


 * 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-.txt', where the 
 * 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)     
 * 4) where the appropriate text is substituted for.
 * 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) this directive occur as a top-level expression, to avoid ambiguity
 * 2) as to when it starts to apply. We don't enforce this yet, but you
 * 3) should follow this practice.) This directive does *not* cause any
 * 4) further attempts to be compatible with that version beyond the
 * 5) 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.
 * 1) 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'.
 * 1) 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.
 * 1) 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, ...]
 * or
 * 1)     map =~ [..., => foo := expr, ...]
 * 2) will succeed even if map contains no mapping for
 * 3) "foo", in which case foo will be bound to the
 * 4) value of the expr.
 * 5) Note: the above proposed syntax sucks, but the semantics seems
 * 6) good. What would be a better syntax?
 * 1) good. What would be a better syntax?

e.enable.pattern-default=true


 * 1) In reaction to the bug "need type guard on data from renderer", 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").
 * 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) Note that the definition of an object name in an object definition
 * 15) expression does not allow a guard, so none of these switches will
 * 16) cause one to be required there.
 * 17) As with all pragmas, these pragma swicthes are not part of the
 * 18) official E language. In fact, we expect to retire these swicthes
 * 19) and migrate the ability to ask for this extra check into an advisory
 * 20) static checker.
 * 21) e.enable.explicit-slot-guard added as of 0.8.23g
 * 1) and migrate the ability to ask for this extra check into an advisory
 * 2) static checker.
 * 3) e.enable.explicit-slot-guard added as of 0.8.23g
 * 1) 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:
 * 4)     accum [] for i in 1..5 { + i**2 }
 * 5) to accumulate the list [ 1, 4, 9, 16, 25 ]. This expands into
 * 6)     var accum_n := []
 * 7)     for i in 1..5 {
 * 8)         accum_n += { i**2 }
 * 9)     }
 * 10)     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.
 * 1) Smalltalk injection.

e.enable.accumulator=allow


 * 1) Turns on the unary prefix '*' operator.
 * 2)     *x
 * 3) expands to
 * 4)     x.getValue
 * so, by the normal assignment rules,
 * 1)     *x := y
 * 2) expands approximately to
 * 3)     x.setValue(y)
 * 4) except that the expansion also arranges for the value of the
 * 5) 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.
 * 6)   to foo { ... } ===> method foo :void { escape __return { ... } }
 * 7) to
 * 8)   to foo { ... } ===> method foo { escape __return { ...; null } }
 * 1)   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
 * 7)     escape ejector-pattern {
 * 8)         body-expression
 * 9)     } catch handler-pattern {
 * 10)         handler-expression
 * 11)     }
 * 12) If such an escape expression, if the ejector is invoked during the
 * 13) execution of body-expression, body-expression is terminated, the
 * 14) handler-pattern is matched against the argument to the ejector, and
 * 15) the handler-expression is evaluated in the resulting scope.
 * 16) In a while-loop or for-loop with a escape-handler, if the break
 * 17) ejector is called, the loop is exited and the argument to break is
 * 18) passed to the handler.
 * 1) ejector is called, the loop is exited and the argument to break is
 * 2) 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
 * 4)     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 web-calculus, this is a cheap notation for forming a bar-only
 * 11) unforseen-facet (a filtering forwarder, sort-of) on the "foo" object.
 * 1) >web-calculus, this is a cheap notation for forming a bar-only
 * 2) 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) 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) 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