From c5f30c4cba204114008b8ddc8ecea5a081be69b7 Mon Sep 17 00:00:00 2001
From: Andy Wingo <wingo@pobox.com>
Date: Wed, 9 Feb 2011 20:54:22 +0100
Subject: [PATCH] add define-once

* module/ice-9/boot-9.scm (define-once): New syntax.

* doc/ref/api-binding.texi (Top Level):
* NEWS: Add notes about define-once.
---
 NEWS                     |  5 +++++
 doc/ref/api-binding.texi | 19 ++++++++++++++++++-
 module/ice-9/boot-9.scm  |  5 +++++
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index 27b52ae75..7912259c3 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,11 @@ latest prerelease, and a full NEWS corresponding to 1.8 -> 2.0.
 
 Changes since the 1.9.15 prerelease:
 
+** New syntax: define-once
+
+`define-once' is like Lisp's `defvar': it creates a toplevel binding,
+but only if one does not exist already.
+
 ** Improved exactness handling for complex number parsing
 
 When parsing non-real complex numbers, exactness specifiers are now
diff --git a/doc/ref/api-binding.texi b/doc/ref/api-binding.texi
index 60af45680..c97ae7390 100644
--- a/doc/ref/api-binding.texi
+++ b/doc/ref/api-binding.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -88,6 +88,23 @@ longer visible.
 Attention: Scheme definitions inside local binding constructs
 (@pxref{Local Bindings}) act differently (@pxref{Internal Definitions}).
 
+Many people end up in a development style of adding and changing
+definitions at runtime, building out their program without restarting
+it.  (You can do this using @code{reload-module}, the @code{reload} REPL
+command, the @code{load} procedure, or even just pasting code into a
+REPL.)  If you are one of these people, you will find that sometimes you
+there are some variables that you @emph{don't} want to redefine all the
+time.  For these, use @code{define-once}.
+
+@fnindex defvar
+@deffn {Scheme Syntax} define-once name value
+Create a top level variable named @var{name} with value @var{value}, but
+only if @var{name} is not already bound in the current module.
+@end deffn
+
+Old Lispers probably know @code{define-once} under its Lisp name,
+@code{defvar}.
+
 
 @node Local Bindings
 @subsection Local Variable Bindings
diff --git a/module/ice-9/boot-9.scm b/module/ice-9/boot-9.scm
index fe7f2b296..f706a716b 100644
--- a/module/ice-9/boot-9.scm
+++ b/module/ice-9/boot-9.scm
@@ -473,6 +473,11 @@ If there is no handler at all, Guile prints an error and then exits."
        (with-syntax ((s (datum->syntax x (syntax-source x))))
          #''s)))))
 
+(define-syntax define-once
+  (syntax-rules ()
+    ((_ sym val)
+     (define sym
+       (if (module-locally-bound? (current-module) 'sym) sym val)))))