-
Notifications
You must be signed in to change notification settings - Fork 0
/
documentation.html
528 lines (513 loc) · 40.6 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>CutBox Docs</title>
<link href="docs-support/bootstrap.min.css" rel="stylesheet" />
<link href="docs-support/default.css" rel="stylesheet" />
<link href="docs-support/github.css" rel="stylesheet" />
<link href="docs-support/doc.css" rel="stylesheet" />
<link href="docs-support/docs.css" rel="stylesheet" />
<style>.nav > li > .nav > li > .nav > li > .nav > li {display: none;}</style>
<script src="docs-support/jquery.min.js" type="javascript"></script>
<script src="docs-support/bootstrap.min.js" type="javascript"></script>
</head>
<body id="page-top" class="html-doc">
<!-- Fixed navbar -->
<div class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand doc-title" href="#page-top">CutBox Documentation</a>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
</div><!--/.nav-collapse -->
</div>
</div>
<div id="documentation-container" class="container">
<div class="row">
<div class="col-md-3">
<div class="nav-container">
<div class="nav-inner" id="scroll-spy" style="width: min-content; overflow: auto; top: 60px; bottom: 0; padding 10px 0 10px 0;">
<h1 id="cutbox-help"><a href="https://github.com/cutbox/CutBox/wiki">CutBox</a></h1>
<ul class="nav"><li><a href="#Searching">Search and Paste</a></li><li><a href="#Pasting-multiple-items">Pasting multiple items</a></li><li><a href="#Favorites">Favorites</a><ul class="nav"><li><a href="#Protecting-Favorites">Protecting Favorites</a></li></ul></li><li><a href="#Preferences">Preferences</a></li><li><a href="#Start-CutBox-when-you-login">Start CutBox when you login</a></li><li><a href="#Color-themes">Color themes</a></li><li><a href="#Javascript-support-in-CutBox">Javascript support in CutBox</a><ul class="nav"><li><a href="#Javascript-Examples">Javascript Examples</a></li><li><a href="#cutbox.js-specification">cutbox.js specification</a></li></ul></li></ul><h1 id="download-cutbox"><a href="https://github.com/cutbox/CutBox/releases/latest">Download CutBox</a></h1>
</div>
</div>
</div>
<div class="col-md-9">
<p class="page" id="Searching"></p><h1>Search and Paste</h1>
<p>Searching for items in your history is simple, open CutBox with your preferred shortcut key</p>
<p>(defaults to <kbd><strong>Cmd</strong></kbd> + <kbd><strong>Shift</strong></kbd> + <kbd><strong>V</strong></kbd>)</p>
<p><img src="https://raw.githubusercontent.com/cutbox/CutBox/master/CutBox/CutBox/GraphicAssets/cutbox-search-bar.png" /></p>
<p>In the search bar, begin typing what you want to paste. You'll see matches show up and you'll be able to select the item you want to paste, using the keyboard (<kbd><strong>Enter</strong></kbd>) or mouse (double click).</p>
<p><img src="https://raw.githubusercontent.com/cutbox/CutBox/master/CutBox/CutBox/GraphicAssets/cutbox-search-fuzzy.png" /></p>
<h1 id="switching-between-search-modes">Switching between search modes</h1>
<p>Use <kbd><strong>Cmd</strong></kbd> + <kbd><strong>S</strong></kbd> to switch between search modes. (The current mode is indicated on the search popup and in the CutBox menu.)</p>
<h1 id="fuzzy-match-searching">Fuzzy match searching</h1>
<p>CutBox default search mode uses fuzzy matching, type some characters and CutBox will find them in anything you've copied.</p>
<h1 id="regular-expression-searching">Regular expression searching</h1>
<p>For very specific match/filtering use PCRE (Perl compatible regular expressions), you can select case insensitive and case sensitive matching.</p>
<p class="page" id="Pasting-multiple-items"></p><h1>Pasting multiple items</h1>
<p>You can select multiple pasteboard items and paste them all back at once.</p>
<ol>
<li>Open CutBox with <kbd><strong>Cmd</strong></kbd> + <kbd><strong>Shift</strong></kbd> + <kbd><strong>V</strong></kbd></li>
<li>Search/Select some items with the mouse / keyboard<ul>
<li>The order you select items is preserved</li>
<li>Preview will show you the paste output as you change item selection</li>
</ul>
</li>
<li>Press <kbd><strong>Enter</strong></kbd> to paste what you can see in preview</li>
</ol>
<p>Let's say you had these words in your CutBox history as separate items, copy them one by one to try this out for yourself.</p>
<table>
<thead>
<tr>
<th>Items in CutBox History</th>
</tr>
</thead>
<tbody>
<tr>
<td>Hello</td>
</tr>
<tr>
<td>World</td>
</tr>
<tr>
<td>Foo</td>
</tr>
<tr>
<td>Bar</td>
</tr>
</tbody>
</table>
<p>We'll select them in this order: <strong>Foo</strong>, <strong>Bar</strong>, <strong>Hello</strong>, <strong>World</strong>.</p>
<p>Press <kbd><strong>Enter</strong></kbd> and CutBox will paste:</p>
<pre class="hljs">Foo
Bar
Hello
World</pre><h2 id="join-wrap-options">Join & Wrap options</h2>
<p>Join and wrapping features for multiple items.</p>
<h3 id="join-modes">Join modes</h3>
<p>In Advanced preferences you can set the join mode to <strong>New Line</strong> or <strong>Text</strong></p>
<p>Choose <strong>Text</strong> mode and set the join string to <code>,</code> so that our multiple items are pasted like this:</p>
<pre class="hljs">Foo, Bar, Hello, World</pre><h3 id="wrapping-mode">Wrapping mode</h3>
<p>Enable wrapping in preferences to surround the items with a start and end string. For example let's paste our items like this:</p>
<pre class="hljs">(<span class="hljs-string">"Foo"</span>, <span class="hljs-string">"Bar"</span>, <span class="hljs-string">"Hello"</span>, <span class="hljs-string">"World"</span>)</pre><p>Set wrapping start string to: <code>("</code> and end strings to: <code>")</code> (with Wrapping enabled)</p>
<hr>
<p>If you want to use special text <em>and</em> new lines, use the <code>\n</code> newline character.</p>
<p>e.g. we want to paste our items like this:</p>
<pre class="hljs">Foo,
Bar,
Hello,
World</pre><p>Set the join string to <code>,\n</code> (and enable <strong>Text</strong> join mode.)</p>
<h2 id="join-and-wrap-keyboard-shortcuts">Join and wrap Keyboard shortcuts</h2>
<ul>
<li>Toggle join mode: <kbd>Cmd</kbd> <kbd>-</kbd></li>
<li>Toggle wrapping mode: <kbd>Cmd</kbd> <kbd>[</kbd></li>
</ul>
<hr>
<p>Using join and wrap can paste items in a lot of different ways, it's pretty useful if you're working with lists of items.</p>
<p>If you exhaust the potential of join & wrap, you can always paste through Javascript or shell commands. (see: <a href="#Javascript-support-in-CutBox">Javascript support in CutBox</a>)</p>
<p class="page" id="Favorites"></p><h1>Favorites</h1>
<p>You can mark items as favorites, and filter out everything else. This makes it easy to find things you want to paste over and over again.</p>
<p>Right click on selected item(s) and choose <strong>toggle favorites</strong>, or press Opt/Alt and click selected item(s) to toggle favorites.</p>
<p>Click the magnifier icon on the search bar to switch to favorites only, or press <kbd><strong>Cmd</strong></kbd> + <kbd><strong>F</strong></kbd> to switch between favorites and everything mode. (The magnifier will turn into a star when you are in favorites only mode.</p>
<p class="page" id="Protecting-Favorites"></p><h1>Protecting Favorites</h1>
<p>By default favorites will be cleared if you clear CutBox's history.</p>
<p>You may want to protect your favorites, so CutBox has the option to do that.</p>
<p>Open preferences from CutBox menu and switch on <strong>Protect Favorites</strong>.</p>
<p><img height="450px" src="images/cutbox-menu-preferences.png"></p>
<p class="page" id="Preferences"></p><h1>Preferences</h1>
<h1 id="general-preferences">General Preferences</h1>
<ul>
<li>Setup the main hotkey to toggle CutBox (default <kbd><strong>Cmd</strong></kbd> + <kbd><strong>Shift</strong></kbd> + <kbd><strong>V</strong></kbd>)</li>
<li>Launch on Login (start CutBox every time you login)</li>
<li>Protect favorites (when you clear CutBox favorites are safe)</li>
</ul>
<p><img width="600px" src="images/cutbox-general-prefs.png"></p>
<h1 id="display">Display</h1>
<ul>
<li><p>Compact UI - only show the search bar until you start typing or press <kbd>up</kbd>. Pressing <kbd>Enter</kbd> will paste whatever is at the top of CutBox history (the last thing copied or pasted)</p>
</li>
<li><p>Color theme - select from a few different color themes.</p>
</li>
</ul>
<p><img width="600px" src="images/cutbox-select-theme.png"></p>
<h1 id="advanced">Advanced</h1>
<ul>
<li><p>History Limit - limit how much CutBox stores, by default that's unlimited, so you may find things slowing down if you have too much in the history. (You can see how much space is used by history items here too.)</p>
</li>
<li><p>Join - when you paste from CutBox you can select multiple items and decide how they're joined together. (Newlines by default) When you choose strings, you can use <kbd><strong>Opt</strong></kbd> + <kbd><strong>Enter</strong></kbd> to add newlines.</p>
</li>
<li><p>Wrap - You can also choose to wrap text around your pastes.</p>
</li>
</ul>
<p>If you would like more flexibility for wrapping and joining text you can script CutBox with Javascript...</p>
<p><img width="600px" src="images/cutbox-advanced-prefs.png"></p>
<h1 id="javascript">Javascript</h1>
<p>Use the Javascript REPL to check your <code>~/.cutbox.js</code> is working as you expected (Type <code>help</code> to list some useful commands)</p>
<ul>
<li>Reload your <code>~/.cutbox.js</code> script.</li>
<li>Clear the REPL</li>
</ul>
<p><img width="600px" src="images/cutbox-js-prefs.png"></p>
<p>Read more about Javascript support <a href="#Javascript-support">Javascript-support</a></p>
<p class="page" id="Start-CutBox-when-you-login"></p><h1>Start CutBox when you login</h1>
<p>CutBox can start up every time you start macOS.</p>
<p>Open preferences and select <strong>Launch on Login</strong></p>
<p><img width="600px" src="images/cutbox-preferences-protect-favorites.png"></p>
<p class="page" id="Color-themes"></p><h1>Color themes</h1>
<p>CutBox has several color themes to choose from, use <kbd>Cmd</kbd> + <kbd>t</kbd> to cycle through them or pick one in preferences.</p>
<h1 id="built-in-color-themes">Built in color themes</h1>
<h1 id="standard">Standard</h1>
<p>The new default theme for 1.6.0. The theme for the previous default, Darkness <a href="#darkness-source">is down here</a>.</p>
<p><img src="images/standard.png"></p>
<h1 id="skylight">Skylight</h1>
<p><img src="images/skylight.png"></p>
<h1 id="sandy-beach">Sandy Beach</h1>
<p><img src="images/sandy-beach.png"></p>
<h1 id="darktooth">Darktooth</h1>
<p><img src="images/darktooth.png"></p>
<h1 id="creamsody">Creamsody</h1>
<p><img src="images/creamsody.png"></p>
<h1 id="purple-haze">Purple Haze</h1>
<p><img src="images/purple-haze.png"></p>
<h1 id="verdant">Verdant</h1>
<p><img src="images/verdant.png"></p>
<h1 id="amber-cathode">Amber Cathode</h1>
<p><img src="images/amber-cathode.png"></p>
<h1 id="macos">macOS</h1>
<p><img src="images/macos.png"></p>
<h1 id="macos-graphite">macOS Graphite</h1>
<p><img src="images/macos-graphite.png"></p>
<h1 id="standarddark">StandardDark</h1>
<p><img src="images/standarddark.png"></p>
<a id="darkness-source"></a>
<h1 id="user-created-themes-">User created themes.</h1>
<p>From CutBox v 1.4.18 you can use custom themes. </p>
<p>Themes are in a JSON format and stored in <code>~/.config/cutbox/</code> as files with the extension <code>.cutboxTheme</code>.</p>
<p>You can access the built in themes at <a href="https://github.com/cutbox/CutBox/tree/master/CutBox/CutBox/themes">https://github.com/cutbox/CutBox/tree/master/CutBox/CutBox/themes</a></p>
<p>The JSON format is as follows.</p>
<pre class="hljs">{
<span class="hljs-attr">"name"</span>: <span class="hljs-string">"Darkness"</span>,
<span class="hljs-attr">"popupBackgroundColor"</span>: <span class="hljs-string">"#163242AA"</span>,
<span class="hljs-attr">"searchText"</span>: {
<span class="hljs-attr">"cursorColor"</span>: <span class="hljs-string">"#0E1C20"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#0E1B21"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#ECF3F6"</span>,
<span class="hljs-attr">"placeholderTextColor"</span>: <span class="hljs-string">"#ADC3CC"</span>
},
<span class="hljs-attr">"clip"</span>: {
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#0E1B21"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#ACC0CA"</span>,
<span class="hljs-attr">"highlightColor"</span>: <span class="hljs-string">"#033E60"</span>,
<span class="hljs-attr">"highlightTextColor"</span>: <span class="hljs-string">"#ACC0CA"</span>
},
<span class="hljs-attr">"preview"</span>: {
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#ADC2CC"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#060707"</span>,
<span class="hljs-attr">"selectedTextBackgroundColor"</span>: <span class="hljs-string">"#163242"</span>,
<span class="hljs-attr">"selectedTextColor"</span>: <span class="hljs-string">"#000000"</span>
},
<span class="hljs-attr">"spacing"</span>: <span class="hljs-number">1</span>
}</pre><p>Color values are hex RGB style, hex RGBA is also usable... e.g.</p>
<pre class="hljs"><span class="hljs-meta"># rrggbbaa</span>
<span class="hljs-string">"#163242AA"</span></pre><p>As with the color channels RGB, the A (alpha) channel is set with values from <code>00</code>-<code>FF</code>. (<code>00</code> transparent, <code>FF</code> solid.)</p>
<p>If there are errors in your theme, CutBox will not start up. To debug your theme, start CutBox from the terminal. Pay close attention to JSON formatting (validate with <a href="https://jsonlint.com/">https://jsonlint.com/</a>) and property names.</p>
<p>Spacing values can be floating point or integer, setting them too large will look very bad. Between <code>0</code> and <code>4</code> is ok by me.</p>
<pre class="hljs"><span class="hljs-meta">#</span><span class="bash"> open a terminal window...</span>
/Applications/CutBox/Contents/MacOS/CutBox</pre><p>CutBox will show error messages here. </p>
<h1 id="user-customized-themes">User Customized Themes</h1>
<h3 id="olivetti-lettera">Olivetti-lettera</h3>
<p><img src="images/olivetti-lettera.png"></p>
<pre class="hljs">{
<span class="hljs-attr">"name"</span>: <span class="hljs-string">"Olivetti Lettera"</span>,
<span class="hljs-attr">"popupBackgroundColor"</span>: <span class="hljs-string">"#658487"</span>,
<span class="hljs-attr">"searchText"</span>: {
<span class="hljs-attr">"cursorColor"</span>: <span class="hljs-string">"#77777777"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#000000DD"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#00000011"</span>,
<span class="hljs-attr">"placeholderTextColor"</span>: <span class="hljs-string">"#465C60"</span>
},
<span class="hljs-attr">"clip"</span>: {
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#FFECE3"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#2E3337"</span>,
<span class="hljs-attr">"highlightColor"</span>: <span class="hljs-string">"#658487EE"</span>,
<span class="hljs-attr">"highlightTextColor"</span>: <span class="hljs-string">"#FFFFFFAA"</span>
},
<span class="hljs-attr">"preview"</span>: {
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#FFFFFFCC"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#00000077"</span>,
<span class="hljs-attr">"selectedTextBackgroundColor"</span>: <span class="hljs-string">"#658487EE"</span>,
<span class="hljs-attr">"selectedTextColor"</span>: <span class="hljs-string">"#20252980"</span>
},
<span class="hljs-attr">"spacing"</span>: <span class="hljs-number">0</span>
}</pre><h3 id="aquaman">Aquaman</h3>
<p><img src="images/aquaman.png"></p>
<pre class="hljs">{
<span class="hljs-attr">"name"</span>: <span class="hljs-string">"Aquaman"</span>,
<span class="hljs-attr">"popupBackgroundColor"</span>: <span class="hljs-string">"#332F2EEE"</span>,
<span class="hljs-attr">"searchText"</span>: {
<span class="hljs-attr">"cursorColor"</span>: <span class="hljs-string">"#31EFE277"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#F9E6DDDD"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#332A26"</span>,
<span class="hljs-attr">"placeholderTextColor"</span>: <span class="hljs-string">"#70635E88"</span>
},
<span class="hljs-attr">"clip"</span>: {
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#23211F"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#F9E7DE"</span>,
<span class="hljs-attr">"highlightColor"</span>: <span class="hljs-string">"#0B6F7599"</span>,
<span class="hljs-attr">"highlightTextColor"</span>: <span class="hljs-string">"#F9E7DE"</span>
},
<span class="hljs-attr">"preview"</span>: {
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#31EFE299"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#001A18"</span>,
<span class="hljs-attr">"selectedTextBackgroundColor"</span>: <span class="hljs-string">"#009C9555"</span>,
<span class="hljs-attr">"selectedTextColor"</span>: <span class="hljs-string">"#000000"</span>
},
<span class="hljs-attr">"spacing"</span>: <span class="hljs-number">0</span>
}</pre>
<h3 id="broken">Broken</h3>
<p><img src="images/broken.png"></p>
<pre class="hljs">{
<span class="hljs-attr">"name"</span>: <span class="hljs-string">"Broken"</span>,
<span class="hljs-attr">"popupBackgroundColor"</span>: <span class="hljs-string">"#00000055"</span>,
<span class="hljs-attr">"searchText"</span>: {
<span class="hljs-attr">"cursorColor"</span>: <span class="hljs-string">"#FFFFFF"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#FFFFFF"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#000000"</span>,
<span class="hljs-attr">"placeholderTextColor"</span>: <span class="hljs-string">"#333333"</span>
},
<span class="hljs-attr">"clip"</span>: {
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#111111"</span>,
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#FFFFFF"</span>,
<span class="hljs-attr">"highlightColor"</span>: <span class="hljs-string">"#4175A7AA"</span>,
<span class="hljs-attr">"highlightTextColor"</span>: <span class="hljs-string">"#FFFFFF"</span>
},
<span class="hljs-attr">"preview"</span>: {
<span class="hljs-attr">"textColor"</span>: <span class="hljs-string">"#FFFFFF"</span>,
<span class="hljs-attr">"backgroundColor"</span>: <span class="hljs-string">"#000000DD"</span>,
<span class="hljs-attr">"selectedTextBackgroundColor"</span>: <span class="hljs-string">"#4175A7AA"</span>,
<span class="hljs-attr">"selectedTextColor"</span>: <span class="hljs-string">"#000000"</span>
},
<span class="hljs-attr">"spacing"</span>: <span class="hljs-number">0</span>
}</pre><p class="page" id="Javascript-support-in-CutBox"></p><h1>Javascript support in CutBox</h1>
<h1 id="pasting-through-javascript">Pasting through JavaScript</h1>
<p>(<a href="#using-shell-commands">and other languages!</a>)</p>
<p>CutBox can send your selected item(s) through JavaScript functions before it's pasted. You will need to create <code>~/.cutbox.js</code> first.</p>
<pre class="hljs"><span class="hljs-keyword">touch</span> ~/.cutbox.js</pre><h2 id="add-functions-to-cutbox-js">Add functions to <code>~/.cutbox.js</code></h2>
<p>CutBox will read this file when it starts up.</p>
<p>See an example <code>~/.cutbox.js</code> here... <a href="#Javascript-Examples">Javascript Examples</a></p>
<h2 id="how-do-i-paste-through-javascript-">How do I paste through JavaScript?</h2>
<p>To send your paste through JavaScript, select one or more item(s) in
CutBox and press <strong>Cmd</strong> + <strong>Enter</strong></p>
<p>You'll see a new list showing your function names and preview of their output.</p>
<p>Fuzzy search will filter down the functions by name, move up and down to select a function, pressing enter will paste.</p>
<h2 id="using-shell-commands">Using shell commands</h2>
<p>You can access shell commands through the <code>shellCommand</code> (since CutBox v1.5.4):</p>
<pre class="hljs">shellCommand(<span class="hljs-string">"command args"</span>)</pre><p>for example:</p>
<pre class="hljs"><span class="hljs-keyword">let</span> files = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">dir</span>) </span>{
<span class="hljs-keyword">return</span> shellCommand(<span class="hljs-string">`ls <span class="hljs-subst">${dir}</span>`</span>)
}</pre><p>This example will return the output of <code>ls $dir</code> which will be pasted.</p>
<p>This opens up the use of any programming language to process your selected CutBox items, while pasting them.</p>
<h2 id="using-existing-javascript-libraries">Using existing JavaScript libraries</h2>
<p><code>require</code> any JavaScript file into CutBox.</p>
<p>For example, if you had <code>mustache.js</code> in a folder called: <code>~/.cutbox/</code></p>
<pre class="hljs"><span class="hljs-regexp">//</span> Load the mustache library.
require(<span class="hljs-string">"~/.cutbox/mustache.js"</span>)
<span class="hljs-regexp">//</span> Now we can use Mustache (read more at https:<span class="hljs-regexp">//gi</span>thub.com<span class="hljs-regexp">/janl/mu</span>stache.js/)</pre><h2 id="reloading">Reloading</h2>
<p>(<strong>Reload JavaScript</strong> in CutBox's preferences.)</p>
<p>CutBox will look for functions in an array called (<code>cutboxFunctions</code>).</p>
<p>See below:</p>
<pre class="hljs"><span class="hljs-keyword">var</span> joining = <span class="hljs-function"><span class="hljs-params">items</span> =></span> items.map(<span class="hljs-function"><span class="hljs-params">e</span> =></span> e )
.join(items.length > <span class="hljs-number">0</span> ? <span class="hljs-string">"\n"</span> : <span class="hljs-string">""</span>)
<span class="hljs-comment">// After function definitions...</span>
<span class="hljs-keyword">this</span>.cutboxFunctions = [
{
<span class="hljs-attr">name</span>: <span class="hljs-string">"Join"</span>, <span class="hljs-comment">// Names should be unique (if not the first named fn will win.)</span>
<span class="hljs-attr">fn</span>: joining <span class="hljs-comment">// You can use any function defined in .cutbox.js</span>
},
{
<span class="hljs-attr">name</span>: <span class="hljs-string">"Join spaced"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> i.join(<span class="hljs-string">" "</span>) <span class="hljs-comment">// You can define functions inline</span>
},
]</pre><h2 id="defining-functions">Defining functions</h2>
<p>CutBox expects your JavaScript functions to reduce arrays of strings, to a single string.</p>
<ul>
<li>They must accept a single argument, an array of strings e.g. <code>["item", "item"]</code> or <code>["item"]</code></li>
<li>They must return a string <code>-> String</code> <code>"item\nitem"</code> or <code>"item"</code></li>
</ul>
<p><a href="#CutBox.js-specification">CutBox.js specification</a></p>
<p>Here's a simple example of such a function in Javascript ES6:</p>
<pre class="hljs"><span class="hljs-keyword">var</span> fn = <span class="hljs-function"><span class="hljs-params">items</span> =></span> items.join()</pre><p><code>fn</code> reads items and joins them into a single string.</p>
<h2 id="some-examples">Some examples</h2>
<p>CutBox will let you do anything you want with the text it's about to
paste.</p>
<p><em>Here's a few examples:</em></p>
<p>Squeeze text to just one space between words.</p>
<pre class="hljs"><span class="hljs-keyword">var</span> squeeze = <span class="hljs-function"><span class="hljs-params">items</span> =></span> items.map(<span class="hljs-function"><span class="hljs-params">s</span> =></span> s.replace(<span class="hljs-regexp">/\s+/g</span>, <span class="hljs-string">' '</span>)
.join(items.length > <span class="hljs-number">0</span> ? <span class="hljs-string">"\n"</span> : <span class="hljs-string">""</span>)</pre><p>Turn this:</p>
<pre class="hljs">My example <span class="hljs-built_in">text</span> has too many spaces</pre><p>into this...</p>
<pre class="hljs">My example <span class="hljs-built_in">text</span> has too many spaces</pre><p>Quote selected items</p>
<pre class="hljs"><span class="hljs-keyword">var</span> = <span class="hljs-function"><span class="hljs-params">items</span> =></span> items.map(<span class="hljs-function"><span class="hljs-params">s</span> =></span> <span class="hljs-string">`"<span class="hljs-subst">${s}</span>"`</span>)
.join(items.length > <span class="hljs-number">0</span> ? <span class="hljs-string">"\n"</span> : <span class="hljs-string">""</span>)</pre><p>Turn this:</p>
<pre class="hljs">My <span class="hljs-built_in">text</span></pre><p>into this...</p>
<pre class="hljs"><span class="hljs-string">"My text"</span></pre><p>or turn this:</p>
<pre class="hljs">My selected <span class="hljs-keyword">item</span>
Another <span class="hljs-literal">one</span>
etc</pre><p>into this...</p>
<pre class="hljs"><span class="hljs-string">"My selected item"</span>
<span class="hljs-string">"Another one"</span>
<span class="hljs-string">"etc"</span></pre><p>Quote and comma separate:</p>
<pre class="hljs"><span class="hljs-keyword">var</span> = <span class="hljs-function"><span class="hljs-params">items</span> =></span> (items.map(<span class="hljs-function"><span class="hljs-params">s</span> =></span> <span class="hljs-string">`"<span class="hljs-subst">${s}</span>"`</span>))
.join(items.length > <span class="hljs-number">0</span> ? <span class="hljs-string">", "</span> : <span class="hljs-string">""</span>)</pre><p>turn this:</p>
<pre class="hljs">My selected <span class="hljs-keyword">item</span>
Another <span class="hljs-literal">one</span>
etc</pre><p>into this...</p>
<pre class="hljs"><span class="hljs-string">"My selected item"</span>, <span class="hljs-string">"Another one"</span>, <span class="hljs-string">"etc"</span></pre><p class="page" id="Javascript-Examples"></p><h1>Javascript Examples</h1>
<p>Example <code>~/.cutbox.js</code></p>
<pre class="hljs"><span class="hljs-built_in">require</span>(<span class="hljs-string">"~/.cutbox/basic.js"</span>);</pre><p>This will load from <code>~/.cutbox/basic.js</code>: </p>
<pre class="hljs"><span class="hljs-comment">// Save this to ~/.cutbox/basic.js</span>
<span class="hljs-keyword">var</span> stripTags = <span class="hljs-function"><span class="hljs-params">i</span> =></span> join(i).replace(<span class="hljs-regexp">/<[^>]*>/gm</span>, <span class="hljs-string">""</span>);
<span class="hljs-keyword">var</span> join = <span class="hljs-function"><span class="hljs-params">i</span> =></span> i.join(i.length > <span class="hljs-number">0</span> ? <span class="hljs-string">"\n"</span> : <span class="hljs-string">""</span>);
<span class="hljs-keyword">var</span> squeeze = <span class="hljs-function"><span class="hljs-params">i</span> =></span> join( i.map( <span class="hljs-function"><span class="hljs-params">s</span> =></span> s.replace(<span class="hljs-regexp">/[ \t]+/gm</span>, <span class="hljs-string">" "</span>)));
<span class="hljs-keyword">var</span> operatorSpacing = <span class="hljs-function"><span class="hljs-params">i</span> =></span> join(i.map(<span class="hljs-function"><span class="hljs-params">string</span> =></span>
string
.replace(<span class="hljs-regexp">/\s*([-=+/*%<>])\s*/g</span>,<span class="hljs-string">" $1 "</span>)
.replace(<span class="hljs-regexp">/([-+=/*%<>])\s*([-+=])/g</span>, <span class="hljs-string">"$1$2"</span>)
));
<span class="hljs-keyword">var</span> markdownCodeIndent = <span class="hljs-function"><span class="hljs-params">str</span> =></span> str.replace(<span class="hljs-regexp">/^/mg</span>, <span class="hljs-string">" "</span>);
<span class="hljs-keyword">this</span>.cutboxFunctions = [
{
<span class="hljs-comment">// Acts like shell command: tr -s ' '</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Squeeze"</span>,
<span class="hljs-attr">fn</span>: squeeze,
},
{
<span class="hljs-comment">// Strip XML/HTML tags (naive!)</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Strip Tags"</span>,
<span class="hljs-attr">fn</span>: stripTags,
},
{
<span class="hljs-comment">// Fix up operator spacing</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Operator spacing"</span>,
<span class="hljs-attr">fn</span>: operatorSpacing
},
{
<span class="hljs-comment">// Double quote each selected item</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Double Quoted"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> join(i.map(<span class="hljs-function"><span class="hljs-params">e</span> =></span> <span class="hljs-string">`"<span class="hljs-subst">${e}</span>"`</span>)),
},
{
<span class="hljs-comment">// Single quote each selected item</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Single Quoted"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> join(i.map(<span class="hljs-function"><span class="hljs-params">e</span> =></span> <span class="hljs-string">`'<span class="hljs-subst">${e}</span>'`</span>)),
},
{
<span class="hljs-comment">// Double quote each item and wrap and comma separate as a multi-language array</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Array formatted (quoted)"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> <span class="hljs-string">`[
<span class="hljs-subst">${join(i.map(e => <span class="hljs-string">`"<span class="hljs-subst">${e}</span>",`</span>))}</span>
]`</span>,
},
{
<span class="hljs-comment">// wrap and comma separate as a multi-language array</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Array formatted (unquoted)"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> <span class="hljs-string">`[
<span class="hljs-subst">${join(i.map(e => <span class="hljs-string">`<span class="hljs-subst">${e}</span>,`</span>))}</span>
]`</span>,
},
{
<span class="hljs-comment">// Add a localized key and localized text as a Localizable.strings definition pair.</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Localized Pair"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> <span class="hljs-string">`"<span class="hljs-subst">${i[<span class="hljs-number">0</span>]}</span>" = "<span class="hljs-subst">${i[<span class="hljs-number">1</span>]}</span>";`</span>
},
{
<span class="hljs-comment">// Wrap Markdown code fence around the selection</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Markdown code fenced"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> <span class="hljs-string">`\`\`\`
<span class="hljs-subst">${join(i)}</span>
\`\`\``</span>
},
{
<span class="hljs-comment">// Markdown Code indent the selection </span>
<span class="hljs-comment">// (including at newlines in each item)</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Markdown code indented"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> join(
i.map(<span class="hljs-function"><span class="hljs-params">e</span> =></span> markdownCodeIndent(e) )
)
},
{
<span class="hljs-comment">// Upper case all text in selection</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Upper cased"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> join(i.map(<span class="hljs-function"><span class="hljs-params">e</span> =></span> e.toUpperCase())),
},
{
<span class="hljs-comment">// Lower case all text in selection</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Lower cased"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> join(i.map(<span class="hljs-function"><span class="hljs-params">e</span> =></span> e.toLowerCase())),
},
{
<span class="hljs-comment">// Evalate the selection in the CutBox </span>
<span class="hljs-comment">// Javascript environment. </span>
<span class="hljs-comment">// -------------------------------------</span>
<span class="hljs-comment">// WARN/<span class="hljs-doctag">NOTE:</span> JUST PREVIEWING SELECTED </span>
<span class="hljs-comment">// JS CODE THROUGH THIS WILL FUNC EXECUTE IT!</span>
<span class="hljs-attr">name</span>: <span class="hljs-string">"Eval"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> <span class="hljs-built_in">eval</span>(i.join(<span class="hljs-string">";"</span>))
}
];</pre><h1 id="using-eval">Using Eval</h1>
<p>Eval is an interesting way to use JS with CutBox. You can evaluate arithmetic and immediately paste the result:</p>
<p><code>1 + 2 + 3</code> <strong><code>-></code></strong> Eval <strong><code>-></code></strong> <code>6</code></p>
<p>Which is handy, you can evaluate <strong>any</strong> JS this way, and the objects created in the JS environment will stay there until CutBox is quit.</p>
<p>This makes it very powerful and also a little bit dangerous! </p>
<p>If you manage to crash CutBox doing things with Javascript, I'd like to know about it. Please make sure your bug report describes very clearly how to reproduce the problem.</p>
<p class="page" id="cutbox.js-specification"></p><h1>cutbox.js specification</h1>
<p>This page outlines the specification of <code>$HOME/.cutbox.js</code> (i.e. <code>~/.cutbox.js</code>)</p>
<p><em>NOTE: using javascript + pseudo type hints, function interface syntax inspired by Swift</em></p>
<h1 id="abstract">Abstract</h1>
<p>A JavaScript file which contains an array (<code>cutboxFunctions</code>) of objects containing a function <code>fn</code> and descriptive metadata <code>name</code>.</p>
<p>Note: With subsequent versions of CutBox function description metadata may extend to allow for new features.</p>
<h1 id="1-5-0">1.5.0</h1>
<h1 id="in-a-nutshell">In a nutshell</h1>
<pre class="hljs"><span class="hljs-keyword">this</span>.cutboxFunctions = [
{ <span class="hljs-attr">fn</span>: CutBoxFunction, <span class="hljs-attr">name</span>: <span class="hljs-built_in">String</span> }
...
];</pre><h3 id="cutboxfunction"><code>CutBoxFunction</code></h3>
<p>A JavaScript <code>Function</code> adhering to the interface:</p>
<pre class="hljs">[<span class="hljs-type">String</span>] -> <span class="hljs-type">String</span></pre><p>All functions must accept a single argument, an array of strings, and return a single string.</p>
<p>e.g. <code>strings => strings.join(" ")</code></p>
<h1 id="example">Example</h1>
<p>Any valid JS function, or function reference can be used, providing it adheres to the interface spec above:</p>
<pre class="hljs"><span class="hljs-keyword">let</span> joinWithDashes = <span class="hljs-function"><span class="hljs-params">items</span> =></span> items.join(<span class="hljs-string">" - "</span>)
<span class="hljs-keyword">this</span>.cutboxFunctions = [
{
<span class="hljs-attr">name</span>: <span class="hljs-string">"Join with spaces"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function">(<span class="hljs-params">i</span>) =></span> i.join(<span class="hljs-string">"\n"</span>)
},
{
<span class="hljs-attr">name</span>: <span class="hljs-string">"Join with dashes"</span>,
<span class="hljs-attr">fn</span>: joinWithDashes
},
{
<span class="hljs-attr">name</span>: <span class="hljs-string">"Uppercase"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> i.map( <span class="hljs-function"><span class="hljs-params">s</span> =></span> s.toUpperCase() ).join(<span class="hljs-string">"\n"</span>)
},
{
<span class="hljs-attr">name</span>: <span class="hljs-string">"Lowercase"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-params">i</span> =></span> i.map( <span class="hljs-function">(<span class="hljs-params">s</span>) =></span> {
<span class="hljs-keyword">return</span> s.toLowerCase() ).join(<span class="hljs-string">"\n"</span>)
}
},
{
<span class="hljs-attr">name</span>: <span class="hljs-string">"Join with commas"</span>,
<span class="hljs-attr">fn</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">items</span>)</span>{ <span class="hljs-keyword">return</span> items.join(<span class="hljs-string">", "</span>) }
}
]</pre><p>For further examples, see: <a href="#JavaScript-Examples">JavaScript Examples</a></p>
</div> <!-- /div.col-md-9 -->
</div> <!-- /div.row -->
</div> <!-- /div.container -->
</body>
</html>