<commit_before>#+TITLE:     Interactive Development

* Introduction

  Immutant provides two methods for connecting to an application's runtime
  with a REPL: Swank (for emacs & possibly vim if you are feeling adventurous)
  and nREPL (for any nREPL client).

  Each REPL service runs on a unique port, allowing you to have REPLs into
  multiple applications within the same Immutant, or mutltiple REPLs within the
  same application.

  REPL services can be started at application deploy time, or dynamically from
  application code. REPLs started dynamically can be also be shutdown
  dynamically. REPLs started at deploy time and any dynamically started REPLs
  that are not shut down by the application will be shut down when the
  application is undeployed.

** Binding To An Interface
   :PROPERTIES:
   :CUSTOM_ID: interative-binding
   :END:

   AS7 is setup to use multiple network interfaces, and allows you to specify
   different interfaces for your server: /public/, /management/, and /unsecure/.
   By default, these interfaces are all the same - =127.0.0.1=. But you can
   specify different addresses for each named interface, aiding in the security
   setup of your management ports.

   By default, the repl services started by Immutant bind to the /management/
   interface.

* Swank

  Swank is the server protocol for [[http://www.common-lisp.net/project/slime/][SLIME (The Superior Lisp Interactive Mode for Emacs)]],
  and Clojure Swank & SLIME support are provided by [[https://github.com/technomancy/swank-clojure][swank-clojure]] & [[https://github.com/technomancy/clojure-mode][clojure-mode]],
  respectively.

** Starting Swank

   You can start a Swank service using one (or both) of two methods: specifying
   a =:swank-port= option in your configuration, or by calling
   =immutant.repl/start-swank= from application code. No matter which method
   you use, there can only be one Swank service running for an application.

*** Starting Swank Via :swank-port

    To have Immutant start a Swank service on your behalf, you can specify
    an open port for it to bind to using the =:swank-port= configuration
    option. When using this option, Immutant will automatically
    [[#interactive-binding][bind to the management interface]].

*** Starting Swank Programatically

    You can also start a Swank service from your own code, which is useful
    if you need to start it in response to a runtime event or bind to an
    interface other than the [[#interactive-binding][management interface]]. To do so, simply
    call [[./apidoc/immutant.repl-api.html#immutant.repl/start-swank][immutant.repl/start-swank]]:

    #+begin_src clojure
      ;; bind to the given port on the management interface
      (clojure.repl/start-swank 4242)

      ;; bind to the given port and interface
      (clojure.repl/start-swank 4242 "127.0.0.1")
    #+end_src

** Connecting to Swank

*** Connecting via Emacs

    Installing SLIME under emacs to work with Clojure can be a painful and
    confusing process if done manually. The easiest way to do it is to follow
    the [[https://github.com/technomancy/swank-clojure][clojure-jack-in instructions]] from =swank-clojure=, and "jack in" to
    any Leiningen project. This will trigger =clojure-mode= to download and
    install a version of SLIME that is compatible with =swank-clojure=.
    Once you have jacked in at least once, you can then connect to the Swank
    service within your Immutant application via the =slime-connect= emacs
    function (=M-x slime-connect RET=).

    Note that =swank-clojure= is now deprecated in favor of [[#interactive-nrepl-emacs][nrepl.el]].

*** Connecting via Vim

    You can connect to Swank from vim with [[http://www.vim.org/scripts/script.php?script_id%3D2531][SLIMV]]. See the SLIMV installation
    instructions for more details.

** Shutting Down Swank

   Immutant will automatically shutdown the Swank service for you when your
   application is undeployed, but if you need to do so before undeploy you
   can do so using the [[./apidoc/immutant.repl-api.html#immutant.repl/stop-swank][immutant.repl/stop-swank]] function:

   #+begin_src clojure
      ;; no arg needed since only one Swank server can exist for the application
      (clojure.repl/stop-swank)
   #+end_src


* nREPL

  [[https://github.com/clojure/tools.nrepl][nREPL]] is a client/server protocol that provides a Clojure REPL across a network.
  It has several clients that support it.

** Starting nREPL

   You can start a nREPL service using one (or both) of two methods: specifying
   an =:nrepl-port= option in your configuration, or by calling
   =immutant.repl/start-nrepl= from application code.

*** Starting nREPL Via :nrepl-port

    To have Immutant start a nREPL service on your behalf, you can specify
    an open port for it to bind to using the =:nrepl-port= configuration
    option. When using this option, Immutant will automatically
    [[#interactive-binding][bind to the management interface]].

*** Starting nREPL Programatically

    You can also start a nREPL service from your own code, which is useful
    if you need to start it in response to a runtime event or bind to an
    interface other than the [[#interactive-binding][management interface]]. To do so, simply
    call [[./apidoc/immutant.repl-api.html#immutant.repl/start-nrepl][immutant.repl/start-nrepl]]. nREPL allows you to have multiple
    services in the same runtime, so you need to save the return value of
    =start-nrepl= if you want to shut down the nREPL service yourself:

    #+begin_src clojure
      ;; bind to the given port on the management interface, and
      ;; save the service handle for later
      (def nrepl (clojure.repl/start-nrepl 4242))

      ;; bind to the given port and interface
      (clojure.repl/start-swank 4242 "127.0.0.1")
    #+end_src

** Connecting to nREPL
<commit_msg>Fix namespace of start-nrepl and start-swank<commit_after>#+TITLE:     Interactive Development

* Introduction

  Immutant provides two methods for connecting to an application's runtime
  with a REPL: Swank (for emacs & possibly vim if you are feeling adventurous)
  and nREPL (for any nREPL client).

  Each REPL service runs on a unique port, allowing you to have REPLs into
  multiple applications within the same Immutant, or mutltiple REPLs within the
  same application.

  REPL services can be started at application deploy time, or dynamically from
  application code. REPLs started dynamically can be also be shutdown
  dynamically. REPLs started at deploy time and any dynamically started REPLs
  that are not shut down by the application will be shut down when the
  application is undeployed.

** Binding To An Interface
   :PROPERTIES:
   :CUSTOM_ID: interative-binding
   :END:

   AS7 is setup to use multiple network interfaces, and allows you to specify
   different interfaces for your server: /public/, /management/, and /unsecure/.
   By default, these interfaces are all the same - =127.0.0.1=. But you can
   specify different addresses for each named interface, aiding in the security
   setup of your management ports.

   By default, the repl services started by Immutant bind to the /management/
   interface.

* Swank

  Swank is the server protocol for [[http://www.common-lisp.net/project/slime/][SLIME (The Superior Lisp Interactive Mode for Emacs)]],
  and Clojure Swank & SLIME support are provided by [[https://github.com/technomancy/swank-clojure][swank-clojure]] & [[https://github.com/technomancy/clojure-mode][clojure-mode]],
  respectively.

** Starting Swank

   You can start a Swank service using one (or both) of two methods: specifying
   a =:swank-port= option in your configuration, or by calling
   =immutant.repl/start-swank= from application code. No matter which method
   you use, there can only be one Swank service running for an application.

*** Starting Swank Via :swank-port

    To have Immutant start a Swank service on your behalf, you can specify
    an open port for it to bind to using the =:swank-port= configuration
    option. When using this option, Immutant will automatically
    [[#interactive-binding][bind to the management interface]].

*** Starting Swank Programatically

    You can also start a Swank service from your own code, which is useful
    if you need to start it in response to a runtime event or bind to an
    interface other than the [[#interactive-binding][management interface]]. To do so, simply
    call [[./apidoc/immutant.repl-api.html#immutant.repl/start-swank][immutant.repl/start-swank]]:

    #+begin_src clojure
      ;; bind to the given port on the management interface
      (clojure.repl/start-swank 4242)

      ;; bind to the given port and interface
      (clojure.repl/start-swank 4242 "127.0.0.1")
    #+end_src

** Connecting to Swank

*** Connecting via Emacs

    Installing SLIME under emacs to work with Clojure can be a painful and
    confusing process if done manually. The easiest way to do it is to follow
    the [[https://github.com/technomancy/swank-clojure][clojure-jack-in instructions]] from =swank-clojure=, and "jack in" to
    any Leiningen project. This will trigger =clojure-mode= to download and
    install a version of SLIME that is compatible with =swank-clojure=.
    Once you have jacked in at least once, you can then connect to the Swank
    service within your Immutant application via the =slime-connect= emacs
    function (=M-x slime-connect RET=).

    Note that =swank-clojure= is now deprecated in favor of [[#interactive-nrepl-emacs][nrepl.el]].

*** Connecting via Vim

    You can connect to Swank from vim with [[http://www.vim.org/scripts/script.php?script_id%3D2531][SLIMV]]. See the SLIMV installation
    instructions for more details.

** Shutting Down Swank

   Immutant will automatically shutdown the Swank service for you when your
   application is undeployed, but if you need to do so before undeploy you
   can do so using the [[./apidoc/immutant.repl-api.html#immutant.repl/stop-swank][immutant.repl/stop-swank]] function:

   #+begin_src clojure
      ;; no arg needed since only one Swank server can exist for the application
      (clojure.repl/stop-swank)
   #+end_src


* nREPL

  [[https://github.com/clojure/tools.nrepl][nREPL]] is a client/server protocol that provides a Clojure REPL across a network.
  It has several clients that support it.

** Starting nREPL

   You can start a nREPL service using one (or both) of two methods: specifying
   an =:nrepl-port= option in your configuration, or by calling
   =immutant.repl/start-nrepl= from application code.

*** Starting nREPL Via :nrepl-port

    To have Immutant start a nREPL service on your behalf, you can specify
    an open port for it to bind to using the =:nrepl-port= configuration
    option. When using this option, Immutant will automatically
    [[#interactive-binding][bind to the management interface]].

*** Starting nREPL Programatically

    You can also start a nREPL service from your own code, which is useful
    if you need to start it in response to a runtime event or bind to an
    interface other than the [[#interactive-binding][management interface]]. To do so, simply
    call [[./apidoc/immutant.repl-api.html#immutant.repl/start-nrepl][immutant.repl/start-nrepl]]. nREPL allows you to have multiple
    services in the same runtime, so you need to save the return value of
    =start-nrepl= if you want to shut down the nREPL service yourself:

    #+begin_src clojure
      ;; bind to the given port on the management interface, and
      ;; save the service handle for later
      (def nrepl (immutant.repl/start-nrepl 4242))

      ;; bind to the given port and interface
      (immutant.repl/start-swank 4242 "1192.168.3.11")
    #+end_src

** Connecting to nREPL

{'fraction_non_alphanumeric': 0.0748074807480748, 'fraction_numerical': 0.007108403148007108, 'mean_word_length': 3.6308777429467085, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5143696', 'n_tokens_mistral': 3613, 'n_tokens_neox': 3445, 'n_words': 1483}