From e8d3223ce571973186fff563c0b447a241bb0124 Mon Sep 17 00:00:00 2001
From: Eli Barzilay <eli@barzilay.org>
Date: Mon, 18 Jul 2011 15:23:09 -0400
Subject: [PATCH] Add an example for extending xrepl, the very stupid way.

For the record, a way to do this permanently is to add something like
this to your ~/.racketrc:

  (eval '(begin
           (saved-values-char #\~)
           (defcommand eli "stuff" "eli says" ["Make eli say stuff"]
             (printf "Eli says: ~a\n" (getarg 'line)))
           (defcommand er #f "alias for errortrace" ["Runs errortrace"]
             (run-command 'errortrace)))
        (module->namespace 'xrepl/xrepl))

But this is too stupid even for a section that has "Hacking" in its title.

There should definitely be an organized way to do this.  This will
require several things:

* A decent API for doing these things for user code.  (So the above
  `eval' turns to a `require' for your file which uses this API.)  This
  goes beyond just documenting what's in there -- there are issues to
  resolve like some argument reading protocol (separating the
  declaration of argument types from the command implementation code),
  so a new command can call another with arguments that it reads.

* There should also be some ,set command for customization
  options (reading and changing) and code to use the preference file for
  doing that.  I almost started to do this, but currently there are only
  three values that this could apply to (`saved-values-char', `-number',
  and `wrap-column' (which might be better to dump and use
  `pretty-print-columns' instead)).

* Also, it might be nice to have some command to do the same for simple
  aliases.  (But this might get into shady parsing issues if it's more
  than just "I want `foo' to be an alias for an existing `bar' command".)
(cherry picked from commit 3c1e624916440747144ce17474f668f32a8a8a6b)
---
 collects/xrepl/xrepl.scrbl | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/collects/xrepl/xrepl.scrbl b/collects/xrepl/xrepl.scrbl
index f934492caf..5aed7f00fb 100644
--- a/collects/xrepl/xrepl.scrbl
+++ b/collects/xrepl/xrepl.scrbl
@@ -453,7 +453,7 @@ customize and extend it, but this will be added in the future.
 
 Meanwhile, if you're interested in tweaking XREPL, the @cmd[enter]
 command can be used as usual to go into its implementation.  For
-example:
+example --- change an XREPL parameter:
 @verbatim[#:indent 4]{
     -> ,en xrepl/xrepl
     xrepl/xrepl> ,e
@@ -463,6 +463,14 @@ example:
     123
     -> ~
     123}
+or add a command:
+@verbatim[#:indent 4]{
+  -> ,en xrepl/xrepl
+  xrepl/xrepl> (defcommand eli "stuff" "eli says" ["Make eli say stuff"]
+                 (printf "Eli says: ~a\n" (getarg 'line)))
+  xrepl/xrepl> ,top
+  -> ,eli moo
+  Eli says: moo}
 While this is not intended as @emph{the} way to extend and customize
 XREPL, it is a useful debugging tool should you want to do so.