Documenting (system repl server)

Documenting (system repl server)

[Ian Price]

[-- Attachment #1: Type: text/plain, Size: 805 bytes --]


It isn't much but I've had a stab at documenting (system repl server) so
that I could feel less guilty about suggesting people use it.

Aside from it's sparseness, the two main issues I've had are
1. Under what section of the manual should it be placed, and
2. How to represent complex optional arguments

For now, I have currently placed it in a new subsection of 6.17 (Reading
and Evaluating Scheme Code). I'm not entirely convinced this is the
right place for it, better suggestions welcome.

For 2, I have described the optional in the text, rather than trying to
placing the expression directly in the prototype.

Rough patch is attached.

-- 
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: docs for repl server --]
[-- Type: text/x-patch, Size: 2665 bytes --]

From d3efaf09c4b57e3055afb503a6c0fd5c7a115ec8 Mon Sep 17 00:00:00 2001
From: Ian Price <ianprice90@googlemail.com>
Date: Mon, 18 Mar 2013 18:55:18 +0000
Subject: [PATCH] Document (system repl server)

* doc/ref/api-evaluation.texi (REPL Servers): New Subsection.
---
 doc/ref/api-evaluation.texi |   40 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)

diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 5c932a7..ff76580 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -22,6 +22,7 @@ loading, evaluating, and compiling Scheme code at run time.
 * Delayed Evaluation::          Postponing evaluation until it is needed.
 * Local Evaluation::            Evaluation in a local lexical environment.
 * Local Inclusion::             Compile-time inclusion of one file in another.
+* REPL Servers::                Serving a REPL over a socket.
 @end menu
 
 
@@ -1219,6 +1220,45 @@ the source files for a package (as you should!).  It makes it possible
 to evaluate an installed file from source, instead of relying on the
 @code{.go} file being up to date.
 
+@node REPL Servers
+@subsection REPL Servers
+
+The procedures in this section are provided by
+@lisp
+(use-modules (system repl server))
+@end lisp
+
+When an application is written in Guile, it is often convenient to
+allow the user to be able to interact with it by evaluating Scheme
+expressions in a REPL.
+
+@deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
+                          [#:addr] [#:port=37146]
+Returns a stream socket bound to a given address @var{addr} and port
+number @var{port}. If the @var{host} is given, and @var{addr} is not,
+then the @var{host} string is converted to an address. If neither is
+given, we use the loopback address.
+@end deffn
+
+@deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"]
+Returns a UNIX domain socket, bound to a given @var{path}.
+@end deffn
+
+@deffn {Scheme Procedure} run-server [server-socket]
+@deffnx {Scheme Procedure} spawn-server [server-socket]
+@code{run-server} creates and runs a repl, making it available over
+the given @var{server-socket}. If @var{server-socket} is not provided,
+it defaults to the socket created by calling
+@code{make-tcp-server-socket} with no arguments.
+
+@code{spawn-server} is similar, but it runs the server in a new
+thread, rather than the existing one.
+@end deffn
+
+@deffn {Scheme Procedure} stop-server-and-clients!
+Closes the connection on all running server sockets.
+@end deffn
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:
-- 
1.7.7.6

Re: Documenting (system repl server)

[Ludovic Courtès]

Ian Price <ianprice90@googlemail.com> skribis:

> For now, I have currently placed it in a new subsection of 6.17 (Reading
> and Evaluating Scheme Code). I'm not entirely convinced this is the
> right place for it, better suggestions welcome.

Sounds good to me.

> For 2, I have described the optional in the text, rather than trying to
> placing the expression directly in the prototype.

This has been discussed recently, but I think what you wrote it OK.

> +@node REPL Servers
> +@subsection REPL Servers
> +
> +The procedures in this section are provided by
> +@lisp
> +(use-modules (system repl server))
> +@end lisp
> +
> +When an application is written in Guile, it is often convenient to
> +allow the user to be able to interact with it by evaluating Scheme
> +expressions in a REPL.

I would add something like “The procedures of this module allow you to
spawn a @dfn{REPL server}, which permits interaction over a local or TCP
connection.”

Also, what about mentioning --listen, with a xref, as an example use?

> +@deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
> +                          [#:addr] [#:port=37146]
> +Returns a stream socket bound to a given address @var{addr} and port

Should be “Return”.

> +@deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"]
> +Returns a UNIX domain socket, bound to a given @var{path}.

Ditto.

> +@deffn {Scheme Procedure} run-server [server-socket]
> +@deffnx {Scheme Procedure} spawn-server [server-socket]
> +@code{run-server} creates and runs a repl, making it available over

Rather “Create and run a REPL” (“REPL” always uppercase).

Also, two spaces after an end-of-sentence period (info "(texinfo) Not
Ending a Sentence").  :-)

Thanks for working on this!

Ludo’.

Re: Documenting (system repl server)

[Andy Wingo]

On Wed 27 Mar 2013 22:10, ludo@gnu.org (Ludovic Courtès) writes:

> Thanks for working on this!

Indeed.

Incidentally I think it would be a good idea to default to using named
pipes.  Not sure we can change that in 2.0, but having a locally open
TCP port to a shell is a security risk if you run a web browser on that
same machine:

  http://wingolog.org/archives/2013/02/04/knocking-on-private-back-doors-with-the-web-browser

Andy
-- 
http://wingolog.org/

Re: Documenting (system repl server)

[Ian Price]

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

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

> I would add something like ^[$B!H^[(BThe procedures of this module allow you to
> spawn a @dfn{REPL server}, which permits interaction over a local or TCP
> connection.^[$B!I^[(B
Added.

> Also, what about mentioning --listen, with a xref, as an example use?
I had intended to, but it managed to slip my mind.

>> +Returns a stream socket bound to a given address @var{addr} and port
>
> Should be ^[$B!H^[(BReturn^[$B!I^[(B.
Fixed.

>> +@deffn {Scheme Procedure} run-server [server-socket]
>> +@deffnx {Scheme Procedure} spawn-server [server-socket]
>> +@code{run-server} creates and runs a repl, making it available over
>
> Rather ^[$B!H^[(BCreate and run a REPL^[$B!I^[(B (^[$B!H^[(BREPL^[$B!I^[(B always uppercase).
Fixed.

-- 
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: (system repl server) documentation --]
[-- Type: text/x-patch, Size: 2908 bytes --]

From 25054bb245b73711298feb37056534c750e721a8 Mon Sep 17 00:00:00 2001
From: Ian Price <ianprice90@googlemail.com>
Date: Mon, 18 Mar 2013 18:55:18 +0000
Subject: [PATCH] Document (system repl server)

* doc/ref/api-evaluation.texi (REPL Servers): New Subsection.
---
 doc/ref/api-evaluation.texi |   45 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 45 insertions(+), 0 deletions(-)

diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 5c932a7..9544a74 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -22,6 +22,7 @@ loading, evaluating, and compiling Scheme code at run time.
 * Delayed Evaluation::          Postponing evaluation until it is needed.
 * Local Evaluation::            Evaluation in a local lexical environment.
 * Local Inclusion::             Compile-time inclusion of one file in another.
+* REPL Servers::                Serving a REPL over a socket.
 @end menu
 
 
@@ -1219,6 +1220,50 @@ the source files for a package (as you should!).  It makes it possible
 to evaluate an installed file from source, instead of relying on the
 @code{.go} file being up to date.
 
+@node REPL Servers
+@subsection REPL Servers
+
+The procedures in this section are provided by
+@lisp
+(use-modules (system repl server))
+@end lisp
+
+When an application is written in Guile, it is often convenient to
+allow the user to be able to interact with it by evaluating Scheme
+expressions in a REPL.
+
+The procedures of this module allow you to spawn a @dfn{REPL server},
+which permits interaction over a local or TCP connection.  Guile itself
+uses them internally to implement the @option{--listen} switch, see
+@ref{Command-line Options}.
+
+@deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
+                          [#:addr] [#:port=37146]
+Return a stream socket bound to a given address @var{addr} and port
+number @var{port}. If the @var{host} is given, and @var{addr} is not,
+then the @var{host} string is converted to an address.  If neither is
+given, we use the loopback address.
+@end deffn
+
+@deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"]
+Return a UNIX domain socket, bound to a given @var{path}.
+@end deffn
+
+@deffn {Scheme Procedure} run-server [server-socket]
+@deffnx {Scheme Procedure} spawn-server [server-socket]
+Create and run a REPL, making it available over the given
+@var{server-socket}.  If @var{server-socket} is not provided, it
+defaults to the socket created by calling @code{make-tcp-server-socket}
+with no arguments.
+
+@code{run-server} runs the server in the current thread, whereas
+@code{spawn-server} runs the server in a new thread.
+@end deffn
+
+@deffn {Scheme Procedure} stop-server-and-clients!
+Closes the connection on all running server sockets.
+@end deffn
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:
-- 
1.7.7.6

Re: Documenting (system repl server)

[Ian Price]

Andy Wingo <wingo@pobox.com> writes:

> Incidentally I think it would be a good idea to default to using named
> pipes.  Not sure we can change that in 2.0, but having a locally open
> TCP port to a shell is a security risk if you run a web browser on that
> same machine:

On one hand, it wasn't documented, so you could argue there was no
stable api for people to use (--listen excluded). On the other, I, and
probably others, have used and suggested it to others.

We could add a note to the docs saying that the named pipe interface
should be preferred, but it does feel a little at odds with having TCP
be the default. Hmmmmm.

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

Re: Documenting (system repl server)

[Ludovic Courtès]

Ian Price <ianprice90@googlemail.com> skribis:

> +The procedures of this module allow you to spawn a @dfn{REPL server},

Add “@cindex REPL server” just above.

> +which permits interaction over a local or TCP connection.  Guile itself
> +uses them internally to implement the @option{--listen} switch, see
> +@ref{Command-line Options}.

Remove “see”.

Other than that, OK to push.

Thanks!

Ludo’.