From: Ian Price <ianprice90@googlemail.com>
To: guile-devel@gnu.org
Subject: Documenting (system repl server)
Date: Mon, 18 Mar 2013 19:01:21 +0000 [thread overview]
Message-ID: <87hak8r0qm.fsf@Kagami.home> (raw)
[-- 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
next reply other threads:[~2013-03-18 19:01 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-03-18 19:01 Ian Price [this message]
2013-03-27 21:10 ` Documenting (system repl server) Ludovic Courtès
2013-03-27 21:35 ` Andy Wingo
2013-03-28 0:32 ` Ian Price
2013-03-28 0:24 ` Ian Price
2013-03-28 16:51 ` Ludovic Courtès
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87hak8r0qm.fsf@Kagami.home \
--to=ianprice90@googlemail.com \
--cc=guile-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).