cljs.repl

since v0.0-927

This namespace mainly provides reflection capabilities to assist you in exploring code in a REPL. It comes with macros that are automatically imported into your REPL environment, but you can use them outside of one as well.

These macros allow you to explore code by listing/searching available vars in a namespace and viewing a var's documentation or source.


*cljs-verbose* - dynamic var

*repl-env* - dynamic var

*repl-opts* - dynamic var

add-url - function
(add-url ijs)

analyze-source - function
(analyze-source src-dir)
(analyze-source src-dir opts)
Given a source directory, analyzes all .cljs files. Used to populate
(:cljs.analyzer/namespaces compiler-env) so as to support code reflection.

apropos - macro
(apropos str-or-pattern)
Given a regular expression or stringable thing, return a seq of all
public definitions in all currently-loaded namespaces that match the
str-or-pattern.

compilable? - function
(compilable? input)

decorate-specs - function
(decorate-specs specs)

default-special-fns - var

demunge - function
(demunge fn-name)
Given a string representation of a fn class,
as in a stack trace element, returns a readable version.

dir - macro
(dir ns)
Prints a sorted directory of public vars in a namespace

doc - macro
(doc name)
Prints documentation for a var or special form given its name,
or for a spec if given a keyword

eval-cljs - function
(eval-cljs repl-env env form)
(eval-cljs repl-env env form opts)
Given a REPL evaluation environment, an analysis environment, and a
form, evaluate the form and return the result. The result is always the value
represented as a string.

evaluate - function
(evaluate repl-env filename line js)

evaluate-form - function
(evaluate-form repl-env env filename form)
(evaluate-form repl-env env filename form wrap)
(evaluate-form repl-env env filename form wrap opts)
Evaluate a ClojureScript form in the JavaScript environment. Returns a
string which is the ClojureScript return value. This string may or may
not be readable by the Clojure reader.

ex-str - function
(ex-str {:keys [:clojure.error/phase :clojure.error/source :clojure.error/line :clojure.error/column :clojure.error/symbol :clojure.error/class :clojure.error/cause :clojure.error/spec], :as triage-data})
Returns a string from exception data, as produced by ex-triage.
The first line summarizes the exception phase and location.
The subsequent lines describe the cause.

ex-triage - function
(ex-triage datafied-throwable)
Returns an analysis of the phase, error, cause, and location of an error that occurred
based on Throwable data, as returned by Throwable->map. All attributes other than phase
are optional:
  :clojure.error/phase - keyword phase indicator, one of:
    :read-source :compile-syntax-check :compilation :macro-syntax-check :macroexpansion
    :execution :read-eval-result :print-eval-result
  :clojure.error/source - file name (no path)
  :clojure.error/line - integer line number
  :clojure.error/column - integer column number
  :clojure.error/symbol - symbol being expanded/compiled/invoked
  :clojure.error/class - cause exception class symbol
  :clojure.error/cause - cause exception message
  :clojure.error/spec - explain-data for spec error

file-display - function
(file-display file {:keys [output-dir temp-output-dir?]})

find-doc - macro
(find-doc re-string-or-pattern)
Prints documentation for any var whose documentation or name
contains a match for re-string-or-pattern

initial-prompt - function
(initial-prompt quit-prompt prompt)

js-src->cljs-src - function
(js-src->cljs-src f)
Map a JavaScript output file back to the original ClojureScript source
file (.cljs or .cljc).

known-repl-opts - var

load - function
(load repl-env provides url)

load-file - function
(load-file repl-env f)
(load-file repl-env f opts)

load-namespace - function
(load-namespace repl-env ns)
(load-namespace repl-env ns opts)
Load a namespace and all of its dependencies into the evaluation environment.
The environment is responsible for ensuring that each namespace is
loaded once and only once. Returns the compiled sources.

load-stream - function
(load-stream repl-env filename res)

mapped-stacktrace - function
(mapped-stacktrace stacktrace)
(mapped-stacktrace stacktrace opts)
Given a vector representing the canonicalized JavaScript stacktrace
return the ClojureScript stacktrace. The canonical stacktrace must be
in the form:

 [{:file 
   :function 
   :line 
   :column }*]

:file must be a URL path (without protocol) relative to :output-dir or a
identifier delimited by angle brackets. The returned mapped stacktrace will
also contain :url entries to the original sources if it can be determined
from the classpath.

maybe-install-npm-deps - function
(maybe-install-npm-deps opts)

ns->input - function
(ns->input ns opts)

ns-info - function
(ns-info f)
Given a path to a js source file return the ns info for the corresponding
ClojureScript file if it exists.

(print-mapped-stacktrace stacktrace)
(print-mapped-stacktrace stacktrace opts)
Given a vector representing the canonicalized JavaScript stacktrace
print the ClojureScript stacktrace. See mapped-stacktrace.

pst - macro
(pst)
(pst e)

read-source-map - function
(read-source-map f)
Return the source map for the JavaScript source file.

repl - function
(repl repl-env & opts)
Generic, reusable, read-eval-print loop. By default, reads from *in* using
a c.t.r.reader-types/source-logging-push-back-reader,
writes to *out*, and prints exception summaries to *err*. If you use the
default :read hook, *in* must either be an instance of
c.t.r.reader-types/PushbackReader or duplicate its behavior of both supporting
unread and collapsing CR, LF, and CRLF into a single \newline. Options
are sequential keyword-value pairs. The first argument is the JavaScript
evaluation environment, the second argument is an extended version of the
standard ClojureScript compiler options. In addition to ClojureScript compiler
build options it also take a set of options similar to clojure.main/repl with
adjustments for ClojureScript evalution and compilation model:

Available clojure.main/repl style options and their defaults:

   - :init, function of no arguments, initialization hook called with
     bindings for set!-able vars in place.
     default: #()

   - :need-prompt, function of no arguments, called before each
     read-eval-print except the first, the user will be prompted if it
     returns true.
     default: #(if (c.t.r.readers-types/indexing-reader? *in*)
                 (== (c.t.r.reader-types/get-column-number *in*) 1)
                 (identity true))

   - :prompt, function of no arguments, prompts for more input.
     default: repl-prompt

   - :flush, function of no arguments, flushes output
     default: flush

   - :read, function of two arguments, reads from *in*:
       - returns its first argument to request a fresh prompt
         - depending on need-prompt, this may cause the repl to prompt
           before reading again
       - returns its second argument to request an exit from the repl
       - else returns the next object read from the input stream
     default: repl-read

   - :eval, function of one argument, returns the evaluation of its
     argument. The eval function must take repl-env, the JavaScript evaluation
     environment, env, the ClojureScript analysis environment, the form
     and opts, the standard ClojureScript REPL/compiler options.
     default: eval

   - :print, function of one argument, prints its argument to the output
     default: println

   - :caught, function of three arguments, a throwable, called when
     read, eval, or print throws an exception or error default. The second
     argument is the JavaScript evaluation environment this permits context
     sensitive handling if necessary. The third argument is opts, the standard
     ClojureScript REPL/compiler options. In the case of errors or exception
     in the JavaScript target, these will be thrown as
     clojure.lang.IExceptionInfo instances.
     default: repl-caught

   - :reader, the c.t.r reader to use.
     default: c.t.r.reader-types/source-logging-push-back-reader

   - :print-no-newline, print without a newline.
     default: print

   - :source-map-inline, whether inline source maps should be enabled. Most
     useful in browser context. Implies using a fresh reader for each form.
     default: true

repl* - function
(repl* repl-env {:keys [init inits need-prompt quit-prompt prompt flush read eval print caught reader print-no-newline source-map-inline wrap repl-requires :user/fast-initial-prompt? compiler-env bind-err], :or {caught repl-caught, quit-prompt repl-title, eval eval-cljs, print-no-newline print, flush flush, fast-initial-prompt? false, read repl-read, bind-err true, print println, source-map-inline true, prompt repl-prompt, repl-requires (quote [[cljs.repl :refer-macros [source doc find-doc apropos dir pst]] [cljs.pprint :refer [pprint] :refer-macros [pp]]]), reader (fn* [] (readers/source-logging-push-back-reader *in* 1 "")), need-prompt (fn* [] (if (readers/indexing-reader? *in*) (== (readers/get-column-number *in*) 1) (identity true)))}, :as opts})

repl-caught - function
(repl-caught e repl-env opts)

repl-nil? - function
(repl-nil? x)

repl-options - function
(repl-options repl-env)

repl-prompt - function
(repl-prompt)

repl-quit-prompt - function
(repl-quit-prompt)

repl-read - function
(repl-read request-prompt request-exit)
(repl-read request-prompt request-exit opts)
Default :read hook for repl. Reads from *in* which must either be an
instance of LineNumberingPushbackReader or duplicate its behavior of both
supporting .unread and collapsing all of CR, LF, and CRLF into a single
\newline. repl-read:
  - skips whitespace, then
    - returns request-prompt on start of line, or
    - returns request-exit on end of stream, or
    - reads an object from the input stream, then
      - skips the next input character if it's end of line, then
      - returns the object.

repl-special-doc-map - var

repl-title - function
(repl-title)

run-inits - function
(run-inits renv inits)

setup - function
(setup repl-env opts)

skip-if-eol - function
(skip-if-eol s)
If the next character on stream s is a newline, skips it, otherwise
leaves the stream untouched. Returns :line-start, :stream-end, or :body
to indicate the relative location of the next character on s. The stream
must either be an instance of LineNumberingPushbackReader or duplicate
its behavior of both supporting .unread and collapsing all of CR, LF, and
CRLF to a single \newline.

skip-whitespace - function
(skip-whitespace s)
Skips whitespace characters on stream s. Returns :line-start, :stream-end,
or :body to indicate the relative location of the next character on s.
Interprets comma as whitespace and semicolon as comment to end of line.
Does not interpret #! as comment to end of line because only one
character of lookahead is available. The stream must either be an
instance of LineNumberingPushbackReader or duplicate its behavior of both
supporting .unread and collapsing all of CR, LF, and CRLF to a single
\newline.

source - macro
(source n)
Prints the source code for the given symbol, if it can find it.
This requires that the symbol resolve to a Var defined in a
namespace for which the .cljs is in the classpath.

Example: (source filter)

source-fn - function
(source-fn env x)
Returns a string of the source code for the given symbol, if it can
find it.  This requires that the symbol resolve to a Var defined in
a namespace for which the .clj is in the classpath.  Returns nil if
it can't find the source.  For most REPL usage, 'source' is more
convenient.

Example: (source-fn 'filter)

special-doc-map - var

tear-down - function
(tear-down repl-env)

Types and Protocols

IGetError - protocol

IJavaScriptEnv - protocol

IParseError - protocol

IParseStacktrace - protocol

IPrintStacktrace - protocol

IReplEnvOptions - protocol