Re: Documenting (system repl server)

[Ian Price]

address@hidden (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.

>> address@hidden {Scheme Procedure} run-server [server-socket]
>> address@hidden {Scheme Procedure} spawn-server [server-socket]
>> address@hidden 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"

>From 25054bb245b73711298feb37056534c750e721a8 Mon Sep 17 00:00:00 2001
From: Ian Price <address@hidden>
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.
 
address@hidden REPL Servers
address@hidden REPL Servers
+
+The procedures in this section are provided by
address@hidden
+(use-modules (system repl server))
address@hidden 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
address@hidden Options}.
+
address@hidden {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.
address@hidden deffn
+
address@hidden {Scheme Procedure} make-unix-domain-server-socket 
[#:path="/tmp/guile-socket"]
+Return a UNIX domain socket, bound to a given @var{path}.
address@hidden deffn
+
address@hidden {Scheme Procedure} run-server [server-socket]
address@hidden {Scheme Procedure} spawn-server [server-socket]
+Create and run a REPL, making it available over the given
address@hidden  If @var{server-socket} is not provided, it
+defaults to the socket created by calling @code{make-tcp-server-socket}
+with no arguments.
+
address@hidden runs the server in the current thread, whereas
address@hidden runs the server in a new thread.
address@hidden deffn
+
address@hidden {Scheme Procedure} stop-server-and-clients!
+Closes the connection on all running server sockets.
address@hidden deffn
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:
-- 
1.7.7.6