Re: [PATCH] doc: describe the -e (module) shorthand as on equal footing with (@ ...)

[Arne Babenhauserheide]

Andy Wingo writes:

> On Wed 06 Jul 2016 23:14, Arne Babenhauserheide <address@hidden> writes:
>
>> Does the following suffice as ChangeLog entry?
>>
>>
>> 2016-05-18  Arne Babenhauserheide  <address@hidden>
>>
>>      * doc/ref/guile-invoke.texi, doc/ref/scheme-scripts.texi:
>>      describe the -e (module) shorthand as on equal footing with (@ ...)
>>
>>
>> It’s mostly generated with hg log --template changelog -r tip.
>
> Hi,
>
> In Guile we work with git :) If you would like a patch applied, please
> attach it in git-format-patch format, with the commit log in the
> standard format.  Check the git logs for examples.  It's easy: just do
> "git commit -a", paste in your change log with the summary line and no
> indentation, then "git format-patch HEAD^".

Sorry for answering late. I missed your answer again (just noticed the
unresolved todo in my agenda and checked explicitly).

I now essentially typed in your commands, plus some manual patch -p1 to
use my own patch :)

Is this OK?

From 4751b9c4c85152281f0d57eda6a1c4ce50166ad4 Mon Sep 17 00:00:00 2001
From: Arne Babenhauserheide <address@hidden>
Date: Thu, 29 Sep 2016 17:11:26 +0200
Subject: [PATCH] describe the -e (module) shorthand as on equal footing with
 (@ ...)

* doc/ref/guile-invoke.texi, doc/ref/scheme-scripts.texi:
describe the -e (module) shorthand as on equal footing with (@ ...)
---
 doc/ref/guile-invoke.texi   | 15 +++++------
 doc/ref/scheme-scripts.texi | 62 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 9 deletions(-)

diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi
index bc33ce0..e25960a 100644
--- a/doc/ref/guile-invoke.texi
+++ b/doc/ref/guile-invoke.texi
@@ -102,15 +102,12 @@ that is defined in the script.  It can also be of the 
form @code{(@@
 @var{module-name} @var{symbol})}, and in that case, the symbol is
 looked up in the module named @var{module-name}.
 
-For compatibility with some versions of Guile 1.4, you can also use the
-form @code{(symbol ...)} (that is, a list of only symbols that doesn't
-start with @code{@@}), which is equivalent to @code{(@@ (symbol ...)
-main)}, or @code{(symbol ...)  symbol} (that is, a list of only symbols
-followed by a symbol), which is equivalent to @code{(@@ (symbol ...)
-symbol)}.  We recommend to use the equivalent forms directly since they
-correspond to the @code{(@@ ...)}  read syntax that can be used in
-normal code.  See @ref{Using Guile Modules} and @ref{Scripting
-Examples}.
+As a shorthand you can use the form @code{(symbol ...)}, that is, a
+list of only symbols that doesn't start with @code{@@}. It is
+equivalent to @code{(@@ @var{module-name}  main)} with @code{(symbol ...)}
+the @var{module-name}.  To use a different function than @var{main},
+you can use the form @code{(symbol ...)  function}.  See @ref{Using
+Guile Modules} and @ref{Scripting Examples}.
 
 @item -ds
 Treat a final @option{-s} option as if it occurred at this point in the
diff --git a/doc/ref/scheme-scripts.texi b/doc/ref/scheme-scripts.texi
index 7552dba..4999a47 100644
--- a/doc/ref/scheme-scripts.texi
+++ b/doc/ref/scheme-scripts.texi
@@ -293,6 +293,11 @@ and exit.
 Load the file @file{/u/jimb/ex4}, and then call the function
 @code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
 
address@hidden guile -e '(ex4)' -s /u/jimb/ex4.scm foo
+Load the file @file{/u/jimb/ex4.scm}, and then call the function
address@hidden from the module '(ex4)', passing it the list
address@hidden("/u/jimb/ex4" "foo")}.
+
 @item guile -l first -ds -l last -s script
 Load the files @file{first}, @file{script}, and @file{last}, in that
 order.  The @code{-ds} switch says when to process the @code{-s}
@@ -402,6 +407,63 @@ $ ./choose 50 100
 100891344545564193334812497256
 @end example
 
+To execute the function main from a module, we can use the special form
address@hidden(@@ (module) function)}:
address@hidden
+#!/usr/local/bin/guile \
+-l fact -e (@@ (fac) main) -s
+!#
+(define-module (fac)
+  #:export (main))
+
+(define (choose n m)
+  (/ (fact m) (* (fact (- m n)) (fact n))))
+
+(define (main args)
+  (let ((n (string->number (cadr args)))
+        (m (string->number (caddr args))))
+    (display (choose n m))
+    (newline)))
address@hidden example
+
+We can use @code{@@@@} to run non-exported functions. For exported
+functions, we can simplify this call with the shorthand @code{(module)}:
address@hidden
+#!/usr/local/bin/guile \
+-l fact -e (fac) -s
+!#
+(define-module (fac)
+  #:export (main))
+
+(define (choose n m)
+  (/ (fact m) (* (fact (- m n)) (fact n))))
+
+(define (main args)
+  (let ((n (string->number (cadr args)))
+        (m (string->number (caddr args))))
+    (display (choose n m))
+    (newline)))
address@hidden example
+
+For maximum portability among *nixes, we can use the shell to
address@hidden guile with specified command line arguments. Here we need to
+take care to quote the command arguments correctly:
address@hidden
+#!/usr/bin env sh
+exec guile -l fact -e '(@@ (fac) main)' -s "$0" "$@"
+!#
+(define-module (fac)
+  #:export (main))
+
+(define (choose n m)
+  (/ (fact m) (* (fact (- m n)) (fact n))))
+
+(define (main args)
+  (let ((n (string->number (cadr args)))
+        (m (string->number (caddr args))))
+    (display (choose n m))
+    (newline)))
address@hidden example
 
 @c Local Variables:
 @c TeX-master: "guile.texi"
-- 
2.7.3


Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein
ohne es zu merken

signature.asc
Description: PGP signature