Re: Change: MUST support block comment "#|...|#" and datum comment "#; datum" David A. Wheeler 08 Aug 2013 01:58 UTC

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

Thoughts?

--- David A. Wheeler

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

<p>
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).
</p>

<p>
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.
</p>

<p>
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.
</p>

<p>
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).
</p>

<p>
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.
</p>

<p>
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>
(<tt>#|</tt>&nbsp;...&nbsp;<tt>|#</tt>)
and
<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.
</p>

<p>
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).
</p>

<p>
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.
</p>

<p>
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.
</p>

<p>
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.
</p>

<p>
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>

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