THIS PROJECT HAS BEEN INCLUDED IN MOZLAB, AND DEVELOPMENT CONTINUES
THERE.

MOZLAB PROJECT: http://dev.hyperstruct.net/mozlab
MOZLAB SOURCE: http://repo.hyperstruct.net/mozlab

= MozRepl =

== ...or How To Break Free From The Write/Save/Restart/Test Cycle in One Easy Keybinding ==


MozRepl is a Firefox extension that lets you write Javascript code in Emacs and have it
evaluated in a running browser immediately.  You will be able to:

  * Send lines of code from an interaction buffer.
  * Send regions of code from Javascript sources.
  * Send the block the cursor is in (a function or other brace-delimited area) from Javascript sources.

It was developed while creating the [http://www.sameplace.cc SamePlace] extension and various libraries, so it is oriented more toward coding for Mozilla the platform than for Mozilla the browser (i.e. web pages).


== Typical session ==

  * Start Emacs and Mozilla (tested only with Firefox at this time).
  * In Mozilla, select `Tools/Start MozRepl`.
  * In Emacs, issue `M-x run-mozilla`.  A *mozilla* window will open.
  * In the *mozilla* Emacs window type:

  {{{
  2+2
  }}}

  ...and press `C-RET`; `4` will appear, freshly evaluated from the Javascript interpreter inside Mozilla.

  * In Emacs, open a new buffer, put it in a major mode suitable for Javascript (such as the provided js-mode), add the provided moz-minor-mode, and write:

  {{{
  {
      var x = 2+2;
      alert(x);
  }
  }}}

  * With the cursor anywhere in between the braces, hit `C-c C-c` (or whatever keybinding you've chosen for moz-send-defun, see below) and an alert box will pop up from Mozilla with "4" as the message.
  * To instead save the file and load it, hit `C-c C-l`.  This will gain you line numbers in the stack trace in case of exceptions.
  * To output something from code to your session:

  {{{
  {
      MozRepl_dump('about to calculate 2+2...\n');
      var x = 2+2;
  }
  }}}

  * A line containing `about to calculate 2+2...` will be printed to your session before the result of the evaluation.


== Installation ==

  * Install current package from http://repo.hyperstruct.net/mozrepl.
  * Get chrome://mozrepl/content/moz.el and put it in your Emacs load path.  There is also chrome://mozrepl/content/js-mode.el which fixes some indentation issues I had with java-mode.
  * In your `~/.emacs` add (adjust major mode hook and keybinding if you prefer something different):

  {{{
  (require 'moz)
  (add-hook 'js-mode-hook
            (lambda ()
              (moz-minor-mode 1)
              (define-key java-mode-map "\C-c\C-c" 'moz-send-defun)
              (define-key java-mode-map "\C-c\C-l" 'moz-save-buffer-and-load)))
  }}}

  * You're ready!


== REPL commands ==

Along with javascript code, special commands can be sent to the REPL handler itself, in the form of:

{{{
    <beginning of line>::command arg1 [arg2 arg3 ... argN]
}}}

One such command, used only for testing this feature, is '::echo':

{{{
    function doSomething() {
        // blah blah
        alert(2+2);
    ::echo hello world
        alert(3+3);
    }
}}}

`hello world` will be echoed back to you, while the rest of the code will be evaluated as usual.  The Javascript interpreter never gets to see `::echo hello world`.

Another such command is `::load`:

{{{
    ::load file://localhost/tmp/test.js
}}}

One use of REPL commands is in handling multi-user sessions.  Many people connect to a single REPL and each gives a name to his or her own session:

{{{
    ::name ben
}}}

By default, MozRepl_dump will send output to the first session, but if you specify a second parameter, the output will go to that user's session:

{{{
    MozRepl_dump('hello there!\n', 'alyssa');
}}}

Or, a little easier on the eyes:

{{{
    function tell(whom, what) {
        MozRepl_Dump(what + '\n', whom);
    }

    tell('alyssa', 'hello there!');
}}}

I don't know if that qualifies as social coding. ;-)


== Integration with other packages ==

MozUnit (http://repo.hyperstruct.net/mozunit), a test-driven development framework, allows very tight test/write/test cycles when used in conjunction with MozRepl.


== Status ==

Works.  Mostly.


== Copyright and author ==

(c) 2006 Massimiliano Mirra <bard [at] hyperstruct [dot] net>, released under the GPL2 license.