Issue LOOP-SYNTAX-OVERHAUL Writeup

Issue:        LOOP-SYNTAX-OVERHAUL

Forum:	      X3J13 Letter Ballot

References:   LOOP syntax (X3J13/92-102 pp6-2..6-5)

Category:     CLARIFICATION

Edit history: 16-Jun-93, Version 1 by Pitman

Status:	      Proposal REPAIR passed (7+3)-1 on letter ballot 93-304.



Problem Description:


  The LOOP syntax in the first dpANS all screwed up.


Proposal (LOOP-SYNTAX-OVERHAUL:REPAIR):


  Affirm that the following changes to the source relating to LOOP syntax

  are in fact editorial and that nothing has been broken. Note that several

  recently passed cleanups are implicitly included in this writeup.


  A typeset version of this code should have been attached for the reader's

  convenience, but the TeX source code is what is being voted upon and kept 

  as a record.  This requires a new TeX macro library, not included.


  Note that two new notations are used to make this work:

       [[ { x }1 | { y }* ]]

  means that x can occur anywhere, but exactly once (it is not optional).

  And 

       [[ x | y | ... ]]+

  means that at least one of the enclosed options must be selected.

  (Appropriate text has been added to Section 1.4 to explain this new

  notational extension.)


 \input setup		      % -*- Mode: TeX -*-

 

 \beginchapter{X}{LOOP}{ChapX}{LOOP}

 

 %%% ========== LOOP

 \begincom{loop}\ftype{Macro}

 

 \label Syntax::

 

 The ``simple'' \macref{loop} \term{form}:

 

 \DefmacWithValues loop {\starparam{compound-form}} {\starparam{result}}

 

 The ``extended'' \macref{loop} \term{form}:

 

 \DefmacWithValues loop {\brac{\down{name-clause}}

			 \stardown{variable-clause}

			 \stardown{main-clause}} {\starparam{result}}

 

 \auxbnf{name-clause}{\loopref{named} \param{name}}

 \auxbnf{variable-clause}{\down{with-clause} | \down{initial-final} | \down{for-as-clause}}

 \auxbnf{with-clause}%

 {\loopref{with} \param{var1} \brac{\param{type-spec}} \brac{$=$ \param{form1}}

  \star{\curly{\loopref{and} \param{var2} \brac{\param{type-spec}} 

			     \brac{$=$ \param{form2}}}}}

 \auxbnf{main-clause}%

 {\down{unconditional} |

  \down{accumulation}  |

  \down{conditional}   |

  \down{end-test}      |

  \down{initial-final}}

 \auxbnf{initial-final}%

 {\loopref{initially} \plusparam{form} |  \loopref{finally} \plusparam{form}}

 \auxbnf{unconditional}%

 {\curly{\loopref{do} | \loopref{doing}} \plusparam{form} |

  \loopref{return} \param{form}}

 \auxbnf{accumulation}{\down{list-accumulation} | \down{numeric-accumulation}}

 \auxbnf{list-accumulation}%

 {\curly{\loopref{collect} | \loopref{collecting} |

	 \loopref{append}  | \loopref{appending}  |

	 \loopref{nconc} | \loopref{nconcing}} \param{form} \CR

  \brac{\loopref{into} \param{var}}}

 \auxbnf{numeric-accumulation}%

 {\curly{\loopref{count}    | \loopref{counting}   |

	 \loopref{sum}      | \loopref{summing}    | \CR

  \xcurly\loopref{maximize} | \loopref{maximizing} |

	 \loopref{minimize} | \loopref{minimizing}} \param{form} \CR

  \brac{\loopref{into} \param{var}} \brac{\param{type-spec}}}

 \auxbnf{conditional}%

 {\curly{\loopref{if} | \loopref{when} | \loopref{unless}} \param{form}

	  \param{selectable-clause} \star{\curly{\loopref{and} \param{selectable-clause}}} \CR

  \brac{\loopref{else}

	  \param{selectable-clause} \star{\curly{\loopref{and} \param{selectable-clause}}}} \CR

  \brac{\loopref{end}}}

 %% I flushed the clause/clause1/clause2 distinction in the next thing, since it's not used

 %% anywhere for reference, and it's not appropriate to the bnf style.

 %% However, I'm concerned about the loss of IT here due to LOOP-MISCELLANEOUS-REPAIRS.

 %%  -kmp 4-May-93

 \auxbnf{selectable-clause}{\down{unconditional} | \down{accumulation} | \down{conditional}}

 \auxbnf{end-test}%

 {\loopref{while}   \param{form}  | 

  \loopref{until}   \param{form}  |

  \loopref{repeat}  \param{form}  |

  \loopref{always}  \param{form}  |

  \loopref{never}   \param{form}  |

  \loopref{thereis} \param{form}}

 \auxbnf{for-as-clause}%

 {\curly{\loopref{for} | \loopref{as}} \down{for-as-subclause}

  \star{\curly{\loopref{and} \down{for-as-subclause}}}}

 \auxbnf{for-as-subclause}%

 {\down{for-as-arithmetic}  |

  \down{for-as-in-list}     |

  \down{for-as-on-list}     |

  \down{for-as-equals-then} |\CR

  \down{for-as-across}      |

  \down{for-as-hash}        |

  \down{for-as-package}}

 \auxbnf{for-as-arithmetic}{\param{var} \brac{\param{type-spec}}

			    \down{for-as-arithmetic-subclause}}

 \auxbnf{for-as-arithmetic-subclause}%

 {\down{arithmetic-up} | \down{arithmetic-downto} | \down{arithmetic-downfrom}}

 \auxbnf{arithmetic-up}%

 {\begininterleave\curly{\loopref{from} | \loopref{upfrom}} \param{form1}               | 

  \extrainterleave\curly{\loopref{to} | \loopref{upto} | \loopref{below}} \param{form2} | 

  \extrainterleave\loopref{by} \param{form3}\endinterleave\prevplus}

 \auxbnf{arithmetic-downto}%

 {\begininterleave\one{\curly{\loopref{from} \param{form1}}} 				| 

  \extrainterleave\one{\curly{\curly{\loopref{downto} | \loopref{above}} \param{form2}}} | 

  \extrainterleave\loopref{by} \param{form3}\endinterleave}

 \auxbnf{arithmetic-downfrom}%

 {\begininterleave\one{\curly{\loopref{downfrom} \param{form1}}} 			 | 

  \extrainterleave\curly{\loopref{to} | \loopref{downto} | \loopref{above}} \param{form2} | 

  \extrainterleave\loopref{by} \param{form3}\endinterleave}

 \auxbnf{for-as-in-list}%

 {\param{var} \brac{\param{type-spec}}

  \loopref{in} \param{form1} \brac{\loopref{by} \param{step-fun}}}

 \auxbnf{for-as-on-list}%

 {\param{var} \brac{\param{type-spec}}

  \loopref{on} \param{form1} \brac{\loopref{by} \param{step-fun}}}

 \auxbnf{for-as-equals-then}%

 {\param{var} \brac{\param{type-spec}}

  $=$ \param{form1} \brac{\loopref{then} \param{form2}}}

 \auxbnf{for-as-across}%

 {\param{var} \brac{\param{type-spec}}

  \loopref{across} \param{vector}}

 \auxbnf{for-as-hash}%

 {\param{var} \brac{\param{type-spec}}

  \loopref{being} \curly{\loopref{each} | \loopref{the}} \CR

  \lcurly\curly{\loopref{hash-key} | \loopref{hash-keys}}

	 \curly{\loopref{in} | \loopref{of}} \param{hash-table} \CR

  \xcurly\brac{\loopref{using} \paren{\loopref{hash-value} \param{other-var}}} | \CR

  \xcurly\curly{\loopref{hash-value} | \loopref{hash-values}}

	 \curly{\loopref{in} | \loopref{of}} \param{hash-table} \CR

  \xcurly\brac{\loopref{using} \paren{\loopref{hash-key} \param{other-var}}}\rcurly}

 \auxbnf{for-as-package}%

 {\param{var} \brac{\param{type-spec}}

  \loopref{being} \curly{\loopref{each} | \loopref{the}} 	        \CR

  \lcurly\loopref{symbol} | \loopref{symbols}		               |\CR

  \xcurly\loopref{present-symbol} | \loopref{present-symbols}           |\CR

  \xcurly\loopref{external-symbol} | \loopref{external-symbols}\rcurly   \CR

  \brac{\curly{\loopref{in} | \loopref{of}} \param{package}}}

 \auxbnf{type-spec}{\down{simple-type-spec} | \down{destructured-type-spec}}

 \auxbnf{simple-type-spec}%

 {\declref{fixnum} | \declref{float} | \declref{t} | \declref{nil}}

 \auxbnf{destructured-type-spec}{\loopref{of-type} \param{d-type-spec}}

 \auxbnf{d-type-spec}%

 {\param{type-specifier} | \f{(\param{d-type-spec} . \param{d-type-spec})}}

 

 \label Arguments and Values::

 

 \param{compound-form}---a \term{compound form}.

 

 \param{name}---a \term{symbol}.

 

 \param{var}, \param{var1}, \param{var2}, \param{other-var}---a \term{symbol}

   (a \term{variable} \term{name}).

 

 \param{form}, \param{form1}, \param{form2}, \param{form3}---a \term{form}.

 

 \issue{LOOP-MISCELLANEOUS-REPAIRS:FIX}

 \param{step-fun}---a \term{form} that evaluates to a \term{function} of one \term{argument}.

 \endissue{LOOP-MISCELLANEOUS-REPAIRS:FIX}

 

 \param{vector}---a \term{form} that evaluates to a \term{vector}.

 

 \param{hash-table}---a \term{form} that evaluates to a \term{hash table}.

 

 \param{package}---a \term{form} that evaluates to a \term{package designator}.

 

 \param{type-specifier}---a \term{type specifier}.

 

 \param{result}---an \term{object}.

 

 \label Description::

 

 %!!! This should be elaborated slightly here.

 For details, \seesection\LoopFacility.

 

 \label Examples::

 

 \code

 ;; An example of the simple form of LOOP.

  (defun sqrt-advisor ()

    (loop (format t "~&Number: ")

	  (let ((n (parse-integer (read-line) :junk-allowed t)))

	    (when (not n) (return))

	    (format t "~&The square root of ~D is ~D.~%" n (sqrt n)))))

 \EV SQRT-ADVISOR

  (sqrt-advisor)

 \OUT Number: \IN{5\CRLF}

 \OUT The square root of 5 is 2.236068.

 \OUT Number: \IN{4\CRLF}

 \OUT The square root of 4 is 2.

 \OUT Number: \IN{done\CRLF}

 \EV NIL

 

 ;; An example of the extended form of LOOP.

  (defun square-advisor ()

    (loop as n = (progn (format t "~&Number: ")

			(parse-integer (read-line) :junk-allowed t))

	  while n

	  do (format t "~&The square of ~D is ~D.~%" n (* n n))))

 \EV SQUARE-ADVISOR

  (square-advisor)

 \OUT Number: \IN{4\CRLF}

 \OUT The square of 4 is 16.

 \OUT Number: \IN{23\CRLF}

 \OUT The square of 23 is 529.

 \OUT Number: \IN{done\CRLF}

 \EV NIL

 

 ;; Another example of the extended form of LOOP.

  (loop for n from 1 to 10

	when (oddp n)

	  collect n)

 \EV (1 3 5 7 9)

 \endcode

  

 \label Affected By:\None.

 

 \label Exceptional Situations:\None.

 

 %!!! Barmar: The description mentions several places where PROGRAM-ERROR is signaled.

 

 \label See Also::

 

 \macref{do}, \macref{dolist}, \macref{dotimes}, 

 \macref{return}, \specref{go}, \specref{throw}

  

 \label Notes::

 

 The simple form of \macref{loop} is related to the extended form

 in the following way:

 

 \code

  (loop \starparam{compound-form}) \EQ (loop do \starparam{compound-form})

 \endcode

 

 \endcom%{loop}

 

 \endchapter

 

 \bye


Test Case:


  N/A


Rationale:


  What was there was utterly broken, so how could we do worse?


Current Practice:


  N/A


Cost to Implementors:


  Hopefully very small.  This is not really supposed to be a change, 

  just a clarification for readability.


Cost to Users:


  Hopefully very small.  This is not really supposed to be a change, 

  just a clarification for readability.


Cost of Non-Adoption:


  A hopelessly messed up description of LOOP's syntax.


Benefits:


  Using LOOP just from the documentation will be possible.


Editorial Impact:


  This affirms work already done.


Aesthetics:


  What was there was so broken that this is unquestionably an improvement.


Discussion:


  Pitman thinks this is just a rubber stamp, and that only editorial changes

  have been made here.  He just wanted the committee to have a chance to 

  double-check this work specially.