bug#12341: define does not support lambda shorthand notation, define-public does

[Ian Price <ianprice90@googlemail.com>]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=iso-2022-jp-2, Size: 2785 bytes --]

ludo@gnu.org (Ludovic Court^[$(D+2^[(Bs) writes:

> You now have commit access, so you^[$B!G^[(Bre welcome to commit it by yourself!
> :-)
I have :-)
>
> Please post patches before committing, for a start.  Make sure to always
> rebase before committing, to avoid gratuitous merge commits if somebody
> else pushed changes in the meantime.  If you have any doubts with Git,
> please ask us.
Rebasing is already standard practice when sending patches, so no
trouble there.

>> * doc/ref/Makefile.am(guile_TEXINFOS): Add curried.texi to list
>> * doc/ref/curried.texi: New file.
>> * doc/ref/guile.texi(Guile Modules): Add "Curried Definitions" to menu.
>> * doc/ref/scheme-ideas.texi(Lambda Alternatives): Refer to "Curried Definitions"
>>   from the `define' section.
>
> Please leave a space before opening parentheses.
Fixed.

>> +++ b/doc/ref/curried.texi
>> @@ -0,0 +1,53 @@
>> +@c -*-texinfo-*-
>> +@c This is part of the GNU Guile Reference Manual.
>> +@c Copyright (C)  2012
>> +@c   Free Software Foundation, Inc.
>
> No newline.
Can you tell I just mimicked the nearest file? Fixed.

>> +Prior to guile 2, guile provided a type of definition known colloquially
>
> Should be ^[$B!H^[(BGuile 2.0^[$B!I^[(B.
Fixed.

>> +@deffn {Syntax} define (@dots{} (name args @dots{}) @dots{}) expression @dots{}
>
> It should be {Scheme Syntax}, for consistency with most of the manual.
Fixed.

> Instead of ^[$B!F^[(Bexpression^[$B!G^[(B, what about ^[$B!F^[(Bbody @dots{}^[$B!G^[(B?
Fixed.

> Also, I wonder whether the parentheses should appear at all, since it
> also accepts the flat form.  OTOH, the only things worth describing is
> the parenthesized form.
That was my thinking.

>> +A curried version of the default @code{define}.
>> +@end deffn
>
> Please use a more formal, present-tense description, like ^[$B!H^[(BCreate a
> top-level variable @var{name} bound to the procedure defined by
> @var{args}.  @var{args} may be a list of formal parameters, possibly
> including nested formal parameter lists, in which case a higher-order
> procedure is created, as in the example above.^[$B!I^[(B
I was having a hard time adequately describing it, and thought it was
better to show by example than give a bad formal description. Anyway, I
hope I've met your expectations with this one.

>> +@deffn {Syntax} define* (@dots{} (name args @dots{}) @dots{}) expression @dots{}
>
> Here ^[$B!F^[(Bdeffnx^[$B!G^[(B could be used instead, like:
I was not aware of that options, done.

>> +Prior to guile 2, guile provided an extension to @code{define} syntax
>
> ^[$B!H^[(BGuile 2.0^[$B!I^[(B.
Fixed.

David,
How about you, any feedback on this documentation?

-- 
Ian Price -- shift-reset.com

"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Curried Documentation Mark II --]
[-- Type: text/x-patch, Size: 4659 bytes --]

From 4f4783096d1052e6e7532acfed21616556c9c456 Mon Sep 17 00:00:00 2001
From: Ian Price <ianprice90@googlemail.com>
Date: Thu, 6 Sep 2012 21:21:47 +0100
Subject: [PATCH] Document (ice-9 curried definitions)

* doc/ref/Makefile.am (guile_TEXINFOS): Add curried.texi to list
* doc/ref/curried.texi: New file.
* doc/ref/guile.texi (Guile Modules): Add "Curried Definitions" to menu.
* doc/ref/scheme-ideas.texi (Lambda Alternatives): Refer to "Curried Definitions"
  from the `define' section.
---
 doc/ref/Makefile.am       |    1 +
 doc/ref/curried.texi      |   56 +++++++++++++++++++++++++++++++++++++++++++++
 doc/ref/guile.texi        |    2 +
 doc/ref/scheme-ideas.texi |    5 ++++
 4 files changed, 64 insertions(+), 0 deletions(-)
 create mode 100644 doc/ref/curried.texi

diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index abe9cb9..201ab6b 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -62,6 +62,7 @@ guile_TEXINFOS = preface.texi			\
 		 web.texi			\
 		 expect.texi			\
 		 scsh.texi			\
+		 curried.texi			\
 		 sxml-match.texi		\
 		 scheme-scripts.texi		\
 		 api-overview.texi		\
diff --git a/doc/ref/curried.texi b/doc/ref/curried.texi
new file mode 100644
index 0000000..f12907e
--- /dev/null
+++ b/doc/ref/curried.texi
@@ -0,0 +1,56 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Curried Definitions
+@section Curried Definitions
+
+The macros in this section are provided by
+@lisp
+(use-modules (ice-9 curried-definitions))
+@end lisp
+@noindent
+and replace those provided by default.
+
+Prior to guile 2.0, guile provided a type of definition known colloquially
+as a ``curried definition''. The idea is to extend the syntax of
+@code{define} so that you can conveniently define procedures that return
+procedures, up to any desired depth.
+
+For example,
+@example
+(define ((foo x) y)
+  (list x y))
+@end example
+is a convenience form of
+@example
+(define foo
+  (lambda (x)
+    (lambda (y)
+      (list x y))))
+@end example
+
+@deffn {Scheme Syntax} define (@dots{} (name args @dots{}) @dots{}) body @dots{}
+@deffnx {Scheme Syntax} define* (@dots{} (name args @dots{}) @dots{}) body @dots{}
+@deffnx {Scheme Syntax} define-public (@dots{} (name args @dots{}) @dots{}) body @dots{}
+
+Create a top level variable @var{name} bound to the procedure with
+parameter list @var{args}. If @var{name} is itself a formal parameter
+list, then a higher order procedure is created using that
+formal-parameter list, and returning a procedure that has parameter list
+@var{args}. This nesting may occur to arbitrary depth.
+
+@code{define*} is similar but the formal parameter lists take additional
+options as described in @ref{lambda* and define*}. For example,
+@example
+(define* ((foo #:keys (bar 'baz) (quux 'zot)) frotz #:rest rest)
+  (list bar quux frotz rest))
+
+((foo #:quux 'foo) 1 2 3 4 5)
+@result{} (baz foo 1 (2 3 4 5))
+@end example
+
+@code{define-public} is similar to @code{define} but it also adds
+@var{name} to the list of exported bindings of the current module.
+@end deffn
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index c3da0c3..a1b3fe6 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -370,6 +370,7 @@ available through both Scheme and C interfaces.
 * Expect::			Controlling interactive programs with Guile.
 * sxml-match::                  Pattern matching of SXML.
 * The Scheme shell (scsh)::     Using scsh interfaces in Guile.
+* Curried Definitions::         Extended @code{define} syntax.
 @end menu
 
 @include slib.texi
@@ -387,6 +388,7 @@ available through both Scheme and C interfaces.
 @include sxml-match.texi
 
 @include scsh.texi
+@include curried.texi
 
 @node Standard Library
 @chapter Standard Library
diff --git a/doc/ref/scheme-ideas.texi b/doc/ref/scheme-ideas.texi
index 53f7b61..cbf1a5c 100644
--- a/doc/ref/scheme-ideas.texi
+++ b/doc/ref/scheme-ideas.texi
@@ -476,6 +476,11 @@ The corresponding forms of the alternative @code{define} syntax are:
 @noindent
 For details on how these forms work, see @xref{Lambda}.
 
+Prior to guile 2.0, guile provided an extension to @code{define} syntax
+that allowed you to nest the previous extension up to an arbitrary
+depth. These are no longer provided by default, and instead have been
+moved to @ref{Curried Definitions}
+
 (It could be argued that the alternative @code{define} forms are rather
 confusing, especially for newcomers to the Scheme language, as they hide
 both the role of @code{lambda} and the fact that procedures are values
-- 
1.7.7.6