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

[Arne Babenhauserheide]

Ping :)

(this change adjusts info documentation and adds examples with
additional options for using Guile in shell scripts)

address@hidden writes:

>  doc/ref/guile-invoke.texi   |  15 ++++------
>  doc/ref/scheme-scripts.texi |  62 
> +++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 68 insertions(+), 9 deletions(-)
>
>
> # HG changeset patch
> # User Arne Babenhauserheide <address@hidden>
> # Date 1463602731 -7200
> #      Wed May 18 22:18:51 2016 +0200
> # Node ID e5938da9b89fcee1936487df32fb649135d8a94c
> # Parent  4f269918e38cd48905546c485173c4f9dbfa0717
> doc: describe the -e (module) shorthand as on equal footing with (@ ...)
>
> diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi
> --- a/doc/ref/guile-invoke.texi
> +++ b/doc/ref/guile-invoke.texi
> @@ -102,15 +102,12 @@ that is defined in the script.  It can a
>  @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
> --- 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 @@ 1
>  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

I just spotted a bug here: should be /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"


-- 
Unpolitisch sein
heißt politisch sein
ohne es zu merken

signature.asc
Description: PGP signature