1 | # replpad [![build status](https://secure.travis-ci.org/thlorenz/replpad.png)](http://next.travis-ci.org/thlorenz/replpad)
|
2 |
|
3 | Pipes content of files to a node repl whenever they change to enable a highly interactive coding experience.
|
4 |
|
5 | Adds keymaps, doc access, vim binding and maps and prints highlighted source of functions right in the repl.
|
6 |
|
7 | ![tty](https://github.com/thlorenz/replpad/raw/master/assets/tty.jpg)
|
8 |
|
9 | Check out the [replpad home page](http://thlorenz.github.com/replpad/) for demos and tutorials.
|
10 |
|
11 | ## Features
|
12 |
|
13 | - **watches all `*.js` files** inside `root` and all subdirectories and sources a file to the repl once it changes
|
14 | - **highlights source code** and **shows location of function definition** where possible, i.e. `require('fs').readFile.src`
|
15 | - **access core module docs in the repl** via the `dox()` function that is added to every core function, i.e. `fs.readdir.dox()`
|
16 | - **[scriptie-talkie](https://github.com/thlorenz/scriptie-talkie) support** (see `.talk` command)
|
17 | - **adds commands and keyboard shortcuts**
|
18 | - **vim key bindings**
|
19 | - **key map support**
|
20 | - **parens matching** via match token plugin
|
21 | - **appends code entered in repl back to file** via keyboard shortcut or `.append` command
|
22 | - **adjusts `__filename`, `__dirname` and `require`** to work for the file that is being sourced
|
23 | - ensures sourced code is parsable on a line by line basis before sending to repl by rewriting it
|
24 | - exposes `module.exports` of last sourced file as `$`
|
25 | - exposes the underlying repl as `$repl` in order to allow further customizations
|
26 |
|
27 | **Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
|
28 |
|
29 | - [Installation](#installation)
|
30 | - [Usage](#usage)
|
31 | - [Commands](#commands)
|
32 | - [Keyboard Shortcuts](#keyboard-shortcuts)
|
33 | - [Smart Append](#smart-append)
|
34 | - [Plugins ](#plugins)
|
35 | - [Vim](#vim)
|
36 | - [Vim Bindings](#vim-bindings)
|
37 | - [Vim like key maps](#vim-like-key-maps)
|
38 | - [Limitations](#limitations)
|
39 | - [match token](#match-token)
|
40 | - [Using replpad with the Vim Editor](#using-replpad-with-the-vim-editor)
|
41 | - [Configuring replpad](#configuring-replpad)
|
42 | - [Roadmap](#roadmap)
|
43 |
|
44 | ## Installation
|
45 |
|
46 | npm install -g replpad
|
47 |
|
48 | ## Usage
|
49 |
|
50 | replpad [path/to/root]
|
51 |
|
52 | If `path/to/root` is omitted then no files are watched.
|
53 |
|
54 | **Example:** `replpad .` watches current directory and all sub directories.
|
55 |
|
56 |
|
57 | ## Commands
|
58 |
|
59 | Some commands were added to the built in `repl` commands. Here is a list of all of them:
|
60 |
|
61 | ```
|
62 | pad > .help
|
63 | .append Appends the last entered parsable chunk of code or the last line to the last file that was sourced in the repl
|
64 |
|
65 | .clear Break, and also clear the local context
|
66 |
|
67 | .compact [on] Toggles if code is compacted before being sourced to the repl
|
68 |
|
69 | .depth [2] Sets the depth to which an object is traversed when printed to the repl
|
70 |
|
71 | .exit Exit the repl
|
72 |
|
73 | .help Show this list of repl commands
|
74 |
|
75 | .hidden [off] Set whether hidden properties are included during traversal of an object that is printed to the repl
|
76 |
|
77 | .highlight [off] Toggles if syntax highlighted code is printed to the repl before being sourced
|
78 |
|
79 | .load Load JS from a file into the REPL session
|
80 |
|
81 | .save Save all evaluated commands in this REPL session to a file
|
82 |
|
83 | .talk [off] Toggles whether the file content is evaluated with scriptie-talkie when it is piped to the repl
|
84 | ```
|
85 |
|
86 | **Note:** commands that toggle a setting like `.compact` take a second parameter: `on|off`. If it is ommitted the state
|
87 | is toggled, i.e if it was `on` it is turned `off` and vice versa.
|
88 |
|
89 | **Note:** when code is syntax highlighted, it is still followed by the compacted code which is necessary in order to
|
90 | have the repl evaluate it.
|
91 |
|
92 | You can add commands to the repl in real time via `$repl.defineCommand`
|
93 |
|
94 | ```js
|
95 | $repl.define('sayhi', {
|
96 | help: 'Says hi via .sayhi'
|
97 | , action: function () { console.log('Hi!') }
|
98 | })
|
99 | ```
|
100 |
|
101 | ## Keyboard Shortcuts
|
102 |
|
103 | - `Ctrl-L` clears the terminal
|
104 | - `Ctrl-D` exits replpad
|
105 | - `Ctrl-A` Appends the **last entered** parsable chunk of code or the last line to the **last file** that was sourced in the repl.
|
106 |
|
107 | ## Smart Append
|
108 |
|
109 | When the `.append` command or the append keyboard shortcut is executed, `replpad` will attempt to find a parsable chunk
|
110 | of code to append. If the last line is parsable or no parsable chunk is found, it will append the last line.
|
111 |
|
112 | **Example:**
|
113 |
|
114 | Assume we entered:
|
115 | ```js
|
116 | 2 + 3
|
117 | function foo() {
|
118 | var a = 2;
|
119 | return a;
|
120 | }
|
121 | ```
|
122 |
|
123 | The first valid JavaScript are the last 4 lines combined. Therefore the entire function `foo` will be appended. This is
|
124 | makes more sense than appending just `}` for instance.
|
125 |
|
126 | Additionally the code is reformatted with 2 space indents.
|
127 |
|
128 | ## Plugins
|
129 |
|
130 | Plugins can be enabled/disabled in the lower portion of the replpad config file
|
131 | ([default](https://github.com/thlorenz/replpad/blob/master/config/default-config.js).
|
132 |
|
133 | The following plugins are available.
|
134 |
|
135 | ### Vim
|
136 |
|
137 | #### Vim Bindings
|
138 |
|
139 | If enabled, a subset of vim bindings are added to `replpad` via [readline-vim](https://github.com/thlorenz/readline-vim).
|
140 |
|
141 | Consult its readme for [available vim bindings](https://github.com/thlorenz/readline-vim#vim-bindings).
|
142 |
|
143 | #### Vim like key maps
|
144 |
|
145 | `replpad` allows you to specify keymaps.
|
146 |
|
147 | `imap` is used to map keys in **insert** mode and `nmap` to map keys in **normal** mode.
|
148 |
|
149 | ```js
|
150 | // map 'ctrl-t' to 'esc', allowing to switch to normal mode via 'ctrl-t'
|
151 | $repl.imap('ctrl-t', 'esc');
|
152 |
|
153 | // go forward in history via 'ctrl-space' in normal mode
|
154 | $repl.nmap('ctrl-space', 'j')
|
155 | ```
|
156 | You can list all registered mappings via: `$repl.maps`.
|
157 |
|
158 | These are handled by [readline-vim](https://github.com/thlorenz/readline-vim), so in order to learn more please read
|
159 | [this section](https://github.com/thlorenz/readline-vim#mappings).
|
160 |
|
161 | You can also declare mappings to be applied at startup by including them inside the map section of your config file as
|
162 | explained in [configuring replpad](#configuring-replpad).
|
163 |
|
164 | #### Limitations
|
165 |
|
166 | Mappings are limited by what the underlying nodejs `readline` supports. Consult [this
|
167 | section](https://github.com/thlorenz/stringify-key#limitations) for more information.
|
168 |
|
169 | In general I found that only a few mappings in `normal` mode have the desired effect. In `insert` mode things are
|
170 | somewhat better.
|
171 |
|
172 | ### match token
|
173 |
|
174 | If enabled, it will match parens, braces, brackets and quotes by jumping the cursor to the matching token [emacs
|
175 | style](http://www.delorie.com/gnu/docs/emacs/emacs_284.html).
|
176 |
|
177 | ## Using replpad with the Vim Editor
|
178 |
|
179 | - in order to auto update your file whenever you append a repl line to it, you need to `:set autoread`
|
180 | - in case you are using terminal vim, autoread is not working great, so you should add the
|
181 | [WatchFile](http://vim.wikia.com/wiki/Have_Vim_check_automatically_if_the_file_has_changed_externally) script to your
|
182 | vim configuration
|
183 |
|
184 | ## Configuring replpad
|
185 |
|
186 | `replpad` is fully configurable.
|
187 |
|
188 | When launched for the first time it creates a config file at `~/.config/replpad/config.js`. Initially this is a copy of
|
189 | the [default-config](https://github.com/thlorenz/replpad/blob/master/config/default-config.js), but you can edit it to
|
190 | change these defaults.
|
191 |
|
192 | Reading the comments in that file should give you enough information to tweak it.
|
193 |
|
194 | ## Roadmap
|
195 |
|
196 | - more vim bindings
|
197 | - only pipe part of a file enclosed by `start/stop` comments
|
198 | - jsdoc support
|
199 | - pause/resume feeding files via command
|
200 | - list an object's properties by type (i.e. `Function`, `Object`, `String`)
|
201 |
|