* Documenting (system repl server)
@ 2013-03-18 19:01 Ian Price
2013-03-27 21:10 ` Ludovic Courtès
0 siblings, 1 reply; 6+ messages in thread
From: Ian Price @ 2013-03-18 19:01 UTC (permalink / raw
To: guile-devel
[-- 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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: Documenting (system repl server)
2013-03-18 19:01 Documenting (system repl server) Ian Price
@ 2013-03-27 21:10 ` Ludovic Courtès
2013-03-27 21:35 ` Andy Wingo
2013-03-28 0:24 ` Ian Price
0 siblings, 2 replies; 6+ messages in thread
From: Ludovic Courtès @ 2013-03-27 21:10 UTC (permalink / raw
To: guile-devel
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’.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Documenting (system repl server)
2013-03-27 21:10 ` Ludovic Courtès
@ 2013-03-27 21:35 ` Andy Wingo
2013-03-28 0:32 ` Ian Price
2013-03-28 0:24 ` Ian Price
1 sibling, 1 reply; 6+ messages in thread
From: Andy Wingo @ 2013-03-27 21:35 UTC (permalink / raw
To: Ludovic Courtès; +Cc: guile-devel
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Documenting (system repl server)
2013-03-27 21:35 ` Andy Wingo
@ 2013-03-28 0:32 ` Ian Price
0 siblings, 0 replies; 6+ messages in thread
From: Ian Price @ 2013-03-28 0:32 UTC (permalink / raw
To: Andy Wingo; +Cc: guile-devel
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"
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Documenting (system repl server)
2013-03-27 21:10 ` Ludovic Courtès
2013-03-27 21:35 ` Andy Wingo
@ 2013-03-28 0:24 ` Ian Price
2013-03-28 16:51 ` Ludovic Courtès
1 sibling, 1 reply; 6+ messages in thread
From: Ian Price @ 2013-03-28 0:24 UTC (permalink / raw
To: Ludovic Courtès; +Cc: guile-devel
[-- 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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: Documenting (system repl server)
2013-03-28 0:24 ` Ian Price
@ 2013-03-28 16:51 ` Ludovic Courtès
0 siblings, 0 replies; 6+ messages in thread
From: Ludovic Courtès @ 2013-03-28 16:51 UTC (permalink / raw
To: Ian Price; +Cc: guile-devel
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’.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2013-03-28 16:51 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-03-18 19:01 Documenting (system repl server) Ian Price
2013-03-27 21:10 ` 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
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).