From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Ian Price Newsgroups: gmane.lisp.guile.devel Subject: Documenting (system repl server) Date: Mon, 18 Mar 2013 19:01:21 +0000 Message-ID: <87hak8r0qm.fsf@Kagami.home> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: ger.gmane.org 1363633304 28331 80.91.229.3 (18 Mar 2013 19:01:44 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 18 Mar 2013 19:01:44 +0000 (UTC) To: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Mon Mar 18 20:02:09 2013 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1UHfJw-0007h2-92 for guile-devel@m.gmane.org; Mon, 18 Mar 2013 20:02:08 +0100 Original-Received: from localhost ([::1]:53069 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UHfJZ-0007Ee-9n for guile-devel@m.gmane.org; Mon, 18 Mar 2013 15:01:45 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:44576) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UHfJU-0007Dj-7k for guile-devel@gnu.org; Mon, 18 Mar 2013 15:01:43 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UHfJS-0003lG-Id for guile-devel@gnu.org; Mon, 18 Mar 2013 15:01:40 -0400 Original-Received: from plane.gmane.org ([80.91.229.3]:45725) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UHfJS-0003l0-8L for guile-devel@gnu.org; Mon, 18 Mar 2013 15:01:38 -0400 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1UHfJn-0007at-7R for guile-devel@gnu.org; Mon, 18 Mar 2013 20:01:59 +0100 Original-Received: from host86-168-32-87.range86-168.btcentralplus.com ([86.168.32.87]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 18 Mar 2013 20:01:59 +0100 Original-Received: from ianprice90 by host86-168-32-87.range86-168.btcentralplus.com with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 18 Mar 2013 20:01:59 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 104 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: host86-168-32-87.range86-168.btcentralplus.com User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) Cancel-Lock: sha1:0o+CfMIoQZQ+sCr8OXmdlFormkA= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:15925 Archived-At: --=-=-= 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" --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-Document-system-repl-server.patch Content-Description: docs for repl server >From d3efaf09c4b57e3055afb503a6c0fd5c7a115ec8 Mon Sep 17 00:00:00 2001 From: Ian Price 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 --=-=-=--