[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Change: MUST support block comment "#|...|#" and datum comment "#; datum"

This page is part of the web mail archives of SRFI 110 from before July 7th, 2015. The new archives for SRFI 110 contain all messages, not just those from before July 7th, 2015.

Here's a rewritten version of "Other requirements".
I've added a requirement that parsing directives be on their
own line, to simplify implementations.


--- David A. Wheeler

<h2 id="other-requirements">Other requirements</h2>

The directives <code>#!sweet</code>,
<code>#!curly-infix</code>, and <code>#!no-sweet</code>
are <i>parsing directives</i>.
A parsing directive is <i>valid</i> if and only if it begins
at the beginning of a line, it is terminated by an end of line,
and it is not contained inside an expression
(e.g., inside parentheses or a collecting list).
The standard datum readers are <code>read</code>,
<code>load</code>, <code>get-datum</code> (where applicable),
and the default implementation REPL (where applicable).

Portable Scheme applications <em>SHOULD</em> include a valid
<code>#!sweet</code> directive before using sweet-expressions.
Portable applications <em>SHOULD NOT</em>
use this directive as the very first characters of a file
because they might be misinterpreted on some platforms
as an executable script header;
an end of line before the directive avoids this problem.
Scheme applications
<em>MUST NOT</em> include a non-valid <code>#!sweet</code> directive.

An implementation <em>MAY</em> signal an error if a parsing
directive is not valid.
An implementation <em>MUST</em> accept
and ignore a valid <code>#!sweet</code> directive
when sweet-expression reading is active.
Implementations of this SRFI <em>MAY</em>
implement sweet-expressions in their standard datum readers by default,
even when a valid <code>#!sweet</code> directive is not (yet) received.

An implementation may be a "native implementation".
A native implementation <em>MUST</em> also accept,
in its standard datum readers,
a valid <code>#!sweet</code> directive,
and from then on it <em>MUST</em> accept
sweet-expressions from the same port
(until some conflicting directive or instruction is given).

A valid <code>#!curly-infix</code> directive
<em>SHOULD</em> cause the current port to switch to SRFI-105
semantics (e.g., sweet-expression processing is disabled).
A valid <code>#!no-sweet</code> directive
<em>SHOULD</em> cause the current port to
disable sweet-expression processing and
<em>MAY</em> also disable curly-infix expression processing.

A sweet-expression reader <em>MUST</em> support
<a href="http://srfi.schemers.org/srfi-30/";>SRFI-30
(Nested Multi-line comments) block comments</a>
<a href="http://srfi.schemers.org/srfi-62/";>SRFI-62
(S-expression comments) datum comments</a> (<tt>#;</tt><var>datum</var>).
It is <em>RECOMMENDED</em> that the
sweet-expression reader support
<a href="http://srfi.schemers.org/srfi-22/";>SRFI-22
(Running Scheme Scripts on Unix)</a> (where <tt>#!</tt>
followed by space ignores text to the end of the line),
<tt>#!</tt> followed by a letter as a directive
(such as <tt>#!fold-case</tt>) delimited by a whitespace character
or end-of-file,
and the formats
<tt>#!/</tt>&nbsp;...&nbsp;<tt>!#</tt> and
<tt>#!.</tt>&nbsp;...&nbsp;<tt>!#</tt> as multi-line non-nesting comments.

A sweet-expression reader <em>MAY</em> implement datum labels
with syntax <code>#<i>number</i>=<i>datum</i></code>.
If the first character after the equal sign is not whitespace,
such a reader <em>SHOULD</em> read it as a neoteric-expression.
If the equal sign is followed by whitespace,
a datum reader <em>MAY</em> reject it;
the reader <em>MAY</em> also
consider the datum an <i>it_expr</i>, and thus
as a label for a sweet-expression
(the sample implementation does not do this).

A <i>well-formatted</i> s-expression is an expression interpreted
identically by both traditional s-expressions and by sweet-expressions.
A well-formatted file is a file interpreted identically
by both traditional s-expressions and sweet-expressions.
(In practice, it appears that
<a href="#backwards-compatibility">most real s-expression files
in Scheme are well-formatted</a>.)
It is <em>RECOMMENDED</em> that files in traditional
s-expression notation be well-formatted so that they can be
directly read using a sweet-expression reader.

Implementations <em>MUST</em> provide the procedures
<var>sweet-read</var> as a sweet-expression reader and/or
<var>neoteric-read</var> as a neoteric-expression reader.
These procedures <em>MUST</em> support an optional port parameter.

Implementations <em>SHOULD</em> enable a sweet-expression reader when
reading a file whose name ends in &#8220;.sscm&#8221; (Sweet Scheme).
Application authors <em>SHOULD</em> use the
filename extension &#8220;.sscm&#8221;
when writing portable Scheme programs using sweet-expressions.

Implementations <em>MUST</em> provide the procedures
<var>curly-write</var> and <var>neoteric-write</var>
as writers that can write c-expressions and n-expressions respectively.
These procedures <em>MUST</em>
accept a first parameter (the object to write)
and an optional second parameter (the port).
Implementations that provide R7RS semantics
(<var>write</var> with cycle detection,
<var>write-shared</var> that identifies shared structures,
and <var>write-simple</var> with no guarantee of
cycle detection or shared structure identification)
<em>SHOULD</em> include appropriate variants of these.
That is,
<var>curly-write</var> and <var>neoteric-write</var>
that perform cycle detection,
<var>curly-write-shared</var> and <var>neoteric-write-shared</var>
identify shared structures, and
<var>curly-write-simple</var> and <var>neoteric-write-simple</var>
guarantee neither.

<p>Note that, by definition, this SRFI modifies lexical syntax.</p>