-
Notifications
You must be signed in to change notification settings - Fork 7
/
tutorial_completers.html
705 lines (662 loc) · 58.6 KB
/
tutorial_completers.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
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
<!doctype html>
<html class="no-js" lang="en" data-content_root="./">
<head><meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Tutorial: Write Your Own History Backend" href="tutorial_history_backend.html" /><link rel="prev" title="Tutorial: Events" href="tutorial_events.html" />
<link rel="shortcut icon" href="_static/magic_conch.ico"/><!-- Generated with Sphinx 7.3.7 and Furo 2024.01.29 -->
<title>Tutorial: Programmable Tab-Completion - xonsh 0.16.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=135e06be" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=fd3f3429" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=c8b63bf6" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=36a5483c" />
<style>
body {
--color-code-background: #eeffcc;
--color-code-foreground: black;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
}
</style></head>
<body>
<script>
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
</script>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24">
<title>Light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24">
<title>Dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
</svg>
</symbol>
<symbol id="svg-sun-half" viewBox="0 0 24 24">
<title>Auto light/dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
<circle cx="12" cy="12" r="9" />
<path d="M13 12h5" />
<path d="M13 15h4" />
<path d="M13 18h1" />
<path d="M13 9h4" />
<path d="M13 6h1" />
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation">
<div class="visually-hidden">Hide navigation sidebar</div>
</label>
<label class="overlay toc-overlay" for="__toc">
<div class="visually-hidden">Hide table of contents sidebar</div>
</label>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<div class="visually-hidden">Toggle site navigation sidebar</div>
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="contents.html"><div class="brand">xonsh 0.16.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand" href="contents.html">
<div class="sidebar-logo-container">
<img class="sidebar-logo" src="_static/ascii_conch_part_transparent_tight.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">xonsh 0.16.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<li class="toctree-l1"><a class="reference internal" href="packages.html">Package Manager</a></li>
<li class="toctree-l1"><a class="reference internal" href="appimage.html">AppImage</a></li>
<li class="toctree-l1"><a class="reference internal" href="containers.html">Docker container</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_hist.html">Tutorial: History</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_macros.html">Tutorial: Macros</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_xontrib.html">Tutorial: Extensions (Xontribs)</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_xonsh_projects.html">Tutorial: Xonsh Projects</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_events.html">Tutorial: Events</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Tutorial: Programmable Tab-Completion</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_history_backend.html">Tutorial: Write Your Own History Backend</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_subproc_strings.html">Tutorial: Subprocess Strings</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial_ptk.html">Tutorial: <code class="docutils literal notranslate"><span class="pre">prompt_toolkit</span></code> custom keybindings</a></li>
<li class="toctree-l1"><a class="reference internal" href="bash_to_xsh.html">Bash to Xonsh Translation Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="editors.html">Editor and IDE Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="subproc_types.html">Subprocess Types Table</a></li>
<li class="toctree-l1"><a class="reference internal" href="python_virtual_environments.html">Python Virtual Environments</a></li>
<li class="toctree-l1"><a class="reference internal" href="keyboard_shortcuts.html">Keyboard Shortcuts</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="xonshrc.html">Run Control File</a></li>
<li class="toctree-l1"><a class="reference internal" href="customization.html">Updating and customizing xonsh</a></li>
<li class="toctree-l1"><a class="reference internal" href="envvars.html">Environment Variables</a></li>
<li class="toctree-l1"><a class="reference internal" href="aliases.html">Built-in Aliases</a></li>
<li class="toctree-l1"><a class="reference internal" href="events.html">Core Events</a></li>
<li class="toctree-l1"><a class="reference internal" href="platform-issues.html">Platform-specific tips and tricks</a></li>
</ul>
<ul>
<li class="toctree-l1 has-children"><a class="reference internal" href="api/index.html">Xonsh API</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Xonsh API</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/lang/xonsh.lexer.html">xonsh.lexer</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/lang/xonsh.parser.html">xonsh.parser</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/lang/xonsh.ast.html">xonsh.ast</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/lang/xonsh.execer.html">xonsh.execer</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/lang/xonsh.imphooks.html">xonsh.imphooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.built_ins.html">xonsh.built_ins</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.environ.html">xonsh.environ</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.aliases.html">xonsh.aliases</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.dirstack.html">xonsh.dirstack</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.jobs.html">xonsh.jobs</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/cmd/xonsh.procs.html">xonsh.procs</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of xonsh.procs</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.procs.pipelines.html">xonsh.procs.pipelines</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.procs.posix.html">xonsh.procs.posix</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.procs.proxies.html">xonsh.procs.proxies</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.procs.readers.html">xonsh.procs.readers</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.procs.specs.html">xonsh.procs.specs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.inspectors.html">xonsh.inspectors</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/cmd/xonsh.history.html">xonsh.history</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of xonsh.history</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.history.base.html">xonsh.history.base</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.history.dummy.html">xonsh.history.dummy</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.history.json.html">xonsh.history.json</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.history.main.html">xonsh.history.main</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.history.sqlite.html">xonsh.history.sqlite</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completer.html">xonsh.completer</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.html">xonsh.completers</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle navigation of xonsh.completers</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.base.html">xonsh.completers.base</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.bash.html">xonsh.completers.bash</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.bash_completion.html">xonsh.completers.bash_completion</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.commands.html">xonsh.completers.commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.completer.html">xonsh.completers.completer</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.dirs.html">xonsh.completers.dirs</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.environment.html">xonsh.completers.environment</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.imports.html">xonsh.completers.imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.init.html">xonsh.completers.init</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.man.html">xonsh.completers.man</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.path.html">xonsh.completers.path</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.python.html">xonsh.completers.python</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.tools.html">xonsh.completers.tools</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.html">xonsh.prompt</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle navigation of xonsh.prompt</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.base.html">xonsh.prompt.base</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.cwd.html">xonsh.prompt.cwd</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.env.html">xonsh.prompt.env</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.gitstatus.html">xonsh.prompt.gitstatus</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.job.html">xonsh.prompt.job</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.times.html">xonsh.prompt.times</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.prompt.vc.html">xonsh.prompt.vc</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.shell.html">xonsh.shell</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.base_shell.html">xonsh.base_shell</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.readline_shell.html">xonsh.readline_shell</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/cmd/xonsh.ptk_shell.html">xonsh.ptk_shell</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle navigation of xonsh.ptk_shell</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.ptk_shell.completer.html">xonsh.ptk_shell.completer</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.ptk_shell.formatter.html">xonsh.ptk_shell.formatter</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.ptk_shell.history.html">xonsh.ptk_shell.history</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.ptk_shell.key_bindings.html">xonsh.ptk_shell.key_bindings</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.ptk_shell.shell.html">xonsh.ptk_shell.shell</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.ptk_shell.updator.html">xonsh.ptk_shell.updator</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.pretty.html">xonsh.pretty</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/cmd/xonsh.diff_history.html">xonsh.diff_history</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.html">xonsh.xoreutils</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle navigation of xonsh.xoreutils</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.cat.html">xonsh.xoreutils.cat</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.echo.html">xonsh.xoreutils.echo</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.pwd.html">xonsh.xoreutils.pwd</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.tee.html">xonsh.xoreutils.tee</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.tty.html">xonsh.xoreutils.tty</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.ulimit.html">xonsh.xoreutils.ulimit</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.umask.html">xonsh.xoreutils.umask</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.uname.html">xonsh.xoreutils.uname</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.uptime.html">xonsh.xoreutils.uptime</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.util.html">xonsh.xoreutils.util</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.which.html">xonsh.xoreutils.which</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/cmd/xonsh.xoreutils.yes.html">xonsh.xoreutils.yes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.events.html">xonsh.events</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lib.html">xonsh.lib</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle navigation of xonsh.lib</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lib.collections.html">xonsh.lib.collections</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lib.itertools.html">xonsh.lib.itertools</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lib.modules.html">xonsh.lib.modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lib.os.html">xonsh.lib.os</a></li>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lib.subprocess.html">xonsh.lib.subprocess</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.tools.html">xonsh.tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.platform.html">xonsh.platform</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.jsonutils.html">xonsh.jsonutils</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lazyjson.html">xonsh.lazyjson</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.lazyasd.html">xonsh.lazyasd</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.openpy.html">xonsh.openpy</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.foreign_shells.html">xonsh.foreign_shells</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.commands_cache.html">xonsh.commands_cache</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.tracer.html">xonsh.tracer</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.main.html">xonsh.main</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.color_tools.html">xonsh.color_tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.pyghooks.html">xonsh.pyghooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.dumb_shell.html">xonsh.dumb_shell</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.wizard.html">xonsh.wizard</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.xonfig.html">xonsh.xonfig</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.xontribs.html">xonsh.xontribs</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.codecache.html">xonsh.codecache</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/_autosummary/helpers/xonsh.contexts.html">xonsh.contexts</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="api/_autosummary/xontribs/xontrib.html">xontrib</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle navigation of xontrib</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="api/_autosummary/xontribs/xontrib.coreutils.html">xontrib.coreutils</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="advanced_events.html">Advanced Events</a></li>
<li class="toctree-l1"><a class="reference internal" href="devguide.html">Developer’s Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Xonsh Change Log</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="todo.html">Wishlist & To-Dos</a></li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<div class="main">
<div class="content">
<div class="article-container">
<a href="#" class="back-to-top muted-link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
</svg>
<span>Back to top</span>
</a>
<div class="content-icon-container">
<div class="edit-this-page">
<a class="muted-link" href="https://github.com/xonsh/xonsh/edit/main/docs/tutorial_completers.rst" title="Edit this page">
<svg aria-hidden="true" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
<path d="M4 20h4l10.5 -10.5a1.5 1.5 0 0 0 -4 -4l-10.5 10.5v4" />
<line x1="13.5" y1="6.5" x2="17.5" y2="10.5" />
</svg>
<span class="visually-hidden">Edit this page</span>
</a>
</div><div class="theme-toggle-container theme-toggle-content">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
<article role="main">
<section id="tutorial-programmable-tab-completion">
<span id="tutorial-completers"></span><h1>Tutorial: Programmable Tab-Completion<a class="headerlink" href="#tutorial-programmable-tab-completion" title="Link to this heading">¶</a></h1>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading">¶</a></h2>
<p>As with many other shells, xonsh ships with the ability to complete
partially-specified arguments upon hitting the “tab” key.</p>
<p>In Python-mode, pressing the “tab” key will complete based on the variable
names in the current builtins, globals, and locals, as well as xonsh language
keywords & operators, files & directories, and environment variable names. In
subprocess-mode, xonsh additionally completes based on the names of any
executable files on your $PATH, alias keys, and full Bash completion for the
commands themselves.</p>
<p>xonsh also provides a mechanism by which the results of a tab completion can be
customized (i.e., new completions can be generated, or a subset of the built-in
completions can be ignored).</p>
<p>This page details the internal structure of xonsh’s completion system and
includes instructions for implementing new tab completion functions.</p>
</section>
<section id="structure">
<h2>Structure<a class="headerlink" href="#structure" title="Link to this heading">¶</a></h2>
<p>xonsh’s built-in completers live in the <code class="docutils literal notranslate"><span class="pre">xonsh.completers</span></code> package, and they
are managed through an instance of <code class="docutils literal notranslate"><span class="pre">OrderedDict</span></code> (<code class="docutils literal notranslate"><span class="pre">__xonsh__.completers</span></code>)
that maps unique identifiers to completion functions.</p>
<p>The completers are divided to <strong>exclusive</strong> completers and <strong>non-exclusive</strong> completers.
Non-exclusive completers are used for completions that are relevant but don’t cover the whole completions needed
(e.g. completions for the built-in commands <code class="docutils literal notranslate"><span class="pre">and</span></code>/<code class="docutils literal notranslate"><span class="pre">or</span></code>).</p>
<p>When the “tab” key is pressed, xonsh loops over the completion functions in
order, calling each one in turn and collecting its output until it reaches an <strong>exclusive</strong> one that returns a non-empty
set of completions for the current line. The collected completions are then displayed to the
user.</p>
</section>
<section id="listing-active-completers">
<h2>Listing Active Completers<a class="headerlink" href="#listing-active-completers" title="Link to this heading">¶</a></h2>
<p>A list of the active completers can be viewed by running the
<code class="docutils literal notranslate"><span class="pre">completer</span> <span class="pre">list</span></code> command. This command will display names and descriptions
of the currently-active completers, in the order in which they will be
checked.</p>
</section>
<section id="writing-a-new-completer">
<h2>Writing a New Completer<a class="headerlink" href="#writing-a-new-completer" title="Link to this heading">¶</a></h2>
<p>Completers are implemented as Python functions that take a <code class="xref py py-class docutils literal notranslate"><span class="pre">Completion</span> <span class="pre">Context</span></code> object.
Examples for the context object:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># ls /tmp/<TAB></span>
<span class="n">CompletionContext</span><span class="p">(</span>
<span class="n">command</span><span class="o">=</span><span class="n">CommandContext</span><span class="p">(</span>
<span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">CommandArg</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">'ls'</span><span class="p">),),</span>
<span class="n">arg_index</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'/tmp/'</span><span class="p">,</span>
<span class="p">),</span>
<span class="n">python</span><span class="o">=</span><span class="n">PythonContext</span><span class="p">(</span><span class="n">multiline_code</span><span class="o">=</span><span class="s2">"ls /tmp/"</span><span class="p">,</span> <span class="n">cursor_index</span><span class="o">=</span><span class="mi">8</span><span class="p">,</span> <span class="n">ctx</span><span class="o">=</span><span class="p">{</span><span class="o">...</span><span class="p">})</span>
<span class="p">)</span>
<span class="c1"># ls $(whic<TAB> "python") -l</span>
<span class="n">CompletionContext</span><span class="p">(</span>
<span class="n">command</span><span class="o">=</span><span class="n">CommandContext</span><span class="p">(</span>
<span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">CommandArg</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">'python'</span><span class="p">,</span> <span class="n">opening_quote</span><span class="o">=</span><span class="s1">'"'</span><span class="p">,</span> <span class="n">closing_quote</span><span class="o">=</span><span class="s1">'"'</span><span class="p">),),</span>
<span class="n">arg_index</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'whic'</span><span class="p">,</span> <span class="n">subcmd_opening</span><span class="o">=</span><span class="s1">'$('</span><span class="p">,</span>
<span class="p">),</span>
<span class="n">python</span><span class="o">=</span><span class="kc">None</span>
<span class="p">)</span>
<span class="c1"># echo @(sys.exe<TAB>)</span>
<span class="n">CompletionContext</span><span class="p">(</span>
<span class="n">command</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">python</span><span class="o">=</span><span class="n">PythonContext</span><span class="p">(</span>
<span class="n">multiline_code</span><span class="o">=</span><span class="s2">"sys.exe"</span><span class="p">,</span> <span class="n">cursor_index</span><span class="o">=</span><span class="mi">7</span><span class="p">,</span>
<span class="n">is_sub_expression</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">ctx</span><span class="o">=</span><span class="p">{</span><span class="o">...</span><span class="p">},</span>
<span class="p">)</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Xonsh still supports legacy completers - see <a class="reference internal" href="#legacy-completers-support">Legacy Completers Support</a>.
For backwards-compatibility, contextual completers need to be marked (as seen in the examples).</p>
</div>
<p>This function should return a python set of possible completions for <code class="docutils literal notranslate"><span class="pre">command.prefix</span></code>
in the current context. If the completer should not be used in this case, it
should return <code class="docutils literal notranslate"><span class="pre">None</span></code> or an empty set, which will cause xonsh to move on and
try to use the next completer.</p>
<p>Occasionally, completers will need to return a match that does not actually
start with <code class="docutils literal notranslate"><span class="pre">prefix</span></code>. In this case, a completer should instead return a tuple
<code class="docutils literal notranslate"><span class="pre">(completions,</span> <span class="pre">prefixlength)</span></code>, where <code class="docutils literal notranslate"><span class="pre">completions</span></code> is the set of
appropriate completions, and <code class="docutils literal notranslate"><span class="pre">prefixlength</span></code> is the number of characters in
<code class="docutils literal notranslate"><span class="pre">line</span></code> that should be treated as part of the completion.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Further completion customizations can be made using the <code class="docutils literal notranslate"><span class="pre">RichCompletion</span></code> object - see <a class="reference internal" href="#advanced-completions">Advanced Completions</a>.</p>
</div>
<p>The docstring of a completer should contain a brief description of its
functionality, which will be displayed by <code class="docutils literal notranslate"><span class="pre">completer</span> <span class="pre">list</span></code>.</p>
<p>Some simple examples follow. For more examples, see the source code of the completers
xonsh actually uses, in the <code class="docutils literal notranslate"><span class="pre">xonsh.completers</span></code> module.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Helper decorators for completers:</span>
<span class="kn">from</span> <span class="nn">xonsh.completers.tools</span> <span class="kn">import</span> <span class="o">*</span>
<span class="nd">@contextual_completer</span>
<span class="k">def</span> <span class="nf">dummy_completer</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="w"> </span><span class="sd">'''</span>
<span class="sd"> Completes everything with options "lou" and "carcolh",</span>
<span class="sd"> regardless of the value of prefix.</span>
<span class="sd"> '''</span>
<span class="k">return</span> <span class="p">{</span><span class="s2">"lou"</span><span class="p">,</span> <span class="s2">"carcolh"</span><span class="p">}</span>
<span class="nd">@non_exclusive_completer</span>
<span class="nd">@contextual_completer</span>
<span class="k">def</span> <span class="nf">nx_dummy_completer</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="w"> </span><span class="sd">'''</span>
<span class="sd"> Like dummy_completer but its results are ADDED to the other completions.</span>
<span class="sd"> '''</span>
<span class="k">return</span> <span class="p">{</span><span class="s2">"lou"</span><span class="p">,</span> <span class="s2">"carcolh"</span><span class="p">}</span>
<span class="nd">@contextual_completer</span>
<span class="k">def</span> <span class="nf">python_context_completer</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="w"> </span><span class="sd">'''</span>
<span class="sd"> Completes based on the names in the current Python environment</span>
<span class="sd"> '''</span>
<span class="k">if</span> <span class="n">context</span><span class="o">.</span><span class="n">python</span><span class="p">:</span>
<span class="n">last_name</span> <span class="o">=</span> <span class="n">context</span><span class="o">.</span><span class="n">python</span><span class="o">.</span><span class="n">prefix</span><span class="o">.</span><span class="n">split</span><span class="p">()[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="k">return</span> <span class="p">{</span><span class="n">i</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">context</span><span class="o">.</span><span class="n">python</span><span class="o">.</span><span class="n">ctx</span> <span class="k">if</span> <span class="n">i</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">last_name</span><span class="p">)}</span>
<span class="nd">@contextual_completer</span>
<span class="k">def</span> <span class="nf">unbeliever_completer</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="w"> </span><span class="sd">'''</span>
<span class="sd"> Replaces "lou carcolh" with "snail" if tab is pressed after at least</span>
<span class="sd"> typing the "lou " part.</span>
<span class="sd"> '''</span>
<span class="k">if</span> <span class="p">(</span>
<span class="c1"># We're completing a command</span>
<span class="n">context</span><span class="o">.</span><span class="n">command</span> <span class="ow">and</span>
<span class="c1"># We're completing the second argument</span>
<span class="n">context</span><span class="o">.</span><span class="n">command</span><span class="o">.</span><span class="n">arg_index</span> <span class="o">==</span> <span class="mi">1</span> <span class="ow">and</span>
<span class="c1"># The first argument is 'lou'</span>
<span class="n">context</span><span class="o">.</span><span class="n">command</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">value</span> <span class="o">==</span> <span class="s1">'lou'</span> <span class="ow">and</span>
<span class="c1"># The prefix startswith 'carcolh' (may be empty)</span>
<span class="s1">'carcolh'</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">command</span><span class="o">.</span><span class="n">prefix</span><span class="p">)</span>
<span class="p">):</span>
<span class="k">return</span> <span class="p">{</span><span class="s1">'snail'</span><span class="p">},</span> <span class="nb">len</span><span class="p">(</span><span class="s1">'lou '</span><span class="p">)</span> <span class="o">+</span> <span class="nb">len</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">command</span><span class="o">.</span><span class="n">prefix</span><span class="p">)</span>
<span class="c1"># Save boilerplate with this helper decorator:</span>
<span class="nd">@contextual_command_completer_for</span><span class="p">(</span><span class="s2">"lou"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">better_unbeliever_completer</span><span class="p">(</span><span class="n">command</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Like unbeliever_completer but with less boilerplate"""</span>
<span class="k">if</span> <span class="n">command</span><span class="o">.</span><span class="n">arg_index</span> <span class="o">==</span> <span class="mi">1</span> <span class="ow">and</span> <span class="s1">'carcolh'</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">command</span><span class="o">.</span><span class="n">prefix</span><span class="p">):</span>
<span class="k">return</span> <span class="p">{</span><span class="s1">'snail'</span><span class="p">},</span> <span class="nb">len</span><span class="p">(</span><span class="s1">'lou '</span><span class="p">)</span> <span class="o">+</span> <span class="nb">len</span><span class="p">(</span><span class="n">command</span><span class="o">.</span><span class="n">prefix</span><span class="p">)</span>
</pre></div>
</div>
<p>To understand how xonsh uses completers and their return values try
to set <a class="reference internal" href="envvars.html#xonsh-trace-completions"><span class="std std-ref">$XONSH_TRACE_COMPLETIONS</span></a> to <code class="docutils literal notranslate"><span class="pre">True</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">>>> $XONSH_TRACE_COMPLETIONS = True</span>
<span class="go">>>> pip c<TAB></span>
<span class="go">TRACE COMPLETIONS: Getting completions with context:</span>
<span class="go">CompletionContext(command=CommandContext(args=(CommandArg(value='pip', opening_quote='', closing_quote=''),), arg_index=1, prefix='c', suffix='', opening_quote='', closing_quote='', is_after_closing_quote=False, subcmd_opening=''), python=PythonContext('pip c', 5, is_sub_expression=False))</span>
<span class="go">TRACE COMPLETIONS: Got 3 results from exclusive completer 'pip':</span>
<span class="go">{RichCompletion('cache', append_space=True),</span>
<span class="go"> RichCompletion('check', append_space=True),</span>
<span class="go"> RichCompletion('config', append_space=True)}</span>
</pre></div>
</div>
</section>
<section id="registering-a-completer">
<h2>Registering a Completer<a class="headerlink" href="#registering-a-completer" title="Link to this heading">¶</a></h2>
<p>Once you have created a completion function, you can add it to the list of
active completers via the <code class="docutils literal notranslate"><span class="pre">completer</span> <span class="pre">add</span></code> command or <code class="docutils literal notranslate"><span class="pre">xonsh.completers.completer.add_one_completer</span></code> function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Usage</span><span class="p">:</span>
<span class="n">completer</span> <span class="n">add</span> <span class="n">NAME</span> <span class="n">FUNC</span> <span class="p">[</span><span class="n">POS</span><span class="p">]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">NAME</span></code> is a unique name to use in the listing</p>
<p><code class="docutils literal notranslate"><span class="pre">FUNC</span></code> is the name of a completer function to use.</p>
<p><code class="docutils literal notranslate"><span class="pre">POS</span></code> (optional) is a position into the list of completers at which the new completer should be added. It can be one of the following values:</p>
<ul class="simple">
<li><dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">"start"</span></code> indicates that the completer should be added to the start of the list of completers (</dt><dd><p>it should be run before all other exclusive completers)</p>
</dd>
</dl>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">"end"</span></code> indicates that the completer should be added to the end of the list of completers (it should be run after all others)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">">KEY"</span></code>, where <code class="docutils literal notranslate"><span class="pre">KEY</span></code> is a pre-existing name, indicates that this should be added after the completer named <code class="docutils literal notranslate"><span class="pre">KEY</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">"<KEY"</span></code>, where <code class="docutils literal notranslate"><span class="pre">KEY</span></code> is a pre-existing name, indicates that this should be added before the completer named <code class="docutils literal notranslate"><span class="pre">KEY</span></code></p></li>
</ul>
<p>If <code class="docutils literal notranslate"><span class="pre">POS</span></code> is not provided, it defaults to <code class="docutils literal notranslate"><span class="pre">"end"</span></code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It is also possible to manipulate <code class="docutils literal notranslate"><span class="pre">__xonsh__.completers</span></code> directly,
but this is the preferred method.</p>
</div>
</section>
<section id="removing-a-completer">
<h2>Removing a Completer<a class="headerlink" href="#removing-a-completer" title="Link to this heading">¶</a></h2>
<p>To remove a completer from the list of active completers, run
<code class="docutils literal notranslate"><span class="pre">completer</span> <span class="pre">remove</span> <span class="pre">NAME</span></code>, where <code class="docutils literal notranslate"><span class="pre">NAME</span></code> is the unique identifier associated
with the completer you wish to remove.</p>
</section>
<section id="advanced-completions">
<h2>Advanced Completions<a class="headerlink" href="#advanced-completions" title="Link to this heading">¶</a></h2>
<p>To provide further control over the completion, a completer can return a <a class="reference internal" href="api/_autosummary/cmd/xonsh.completers.tools.html#xonsh.completers.tools.RichCompletion" title="xonsh.completers.tools.RichCompletion"><code class="xref py py-class docutils literal notranslate"><span class="pre">RichCompletion</span></code></a> object.
Using this class, you can:</p>
<ul class="simple">
<li><p>Provide a specific prefix length per completion (via <code class="docutils literal notranslate"><span class="pre">prefix_len</span></code>)</p></li>
<li><dl class="simple">
<dt>Control how the completion looks in prompt-toolkit (via <code class="docutils literal notranslate"><span class="pre">display</span></code>, <code class="docutils literal notranslate"><span class="pre">description</span></code> and <code class="docutils literal notranslate"><span class="pre">style</span></code>) -</dt><dd><p>use the <code class="docutils literal notranslate"><span class="pre">jedi</span></code> xontrib to see it in action.</p>
</dd>
</dl>
</li>
<li><p>Append a space after the completion (<code class="docutils literal notranslate"><span class="pre">append_space=True</span></code>)</p></li>
</ul>
<section id="completing-closed-string-literals">
<h3>Completing Closed String Literals<a class="headerlink" href="#completing-closed-string-literals" title="Link to this heading">¶</a></h3>
<p>When the cursor is appending to a closed string literal (i.e. cursor at the end of <code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">"/usr/"</span></code>), the following happens:</p>
<ol class="arabic simple">
<li><dl class="simple">
<dt>The closing quote will be appended to all completions.</dt><dd><p>I.e the completion <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code> will turn into <code class="docutils literal notranslate"><span class="pre">/usr/bin"</span></code>.
To prevent this behavior, a completer can return a <code class="docutils literal notranslate"><span class="pre">RichCompletion</span></code> with <code class="docutils literal notranslate"><span class="pre">append_closing_quote=False</span></code>.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>If not specified, lprefix will cover the closing prefix.</dt><dd><p>I.e for <code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">"/usr/"</span></code>, the default lprefix will be 6 to include the closing quote.
To prevent this behavior, a completer can return a different lprefix or specify it inside <code class="docutils literal notranslate"><span class="pre">RichCompletion</span></code>.</p>
</dd>
</dl>
</li>
</ol>
<p>So if you want to change/remove the quotes from a string, the following completer can be written:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@contextual_command_completer</span>
<span class="k">def</span> <span class="nf">remove_quotes</span><span class="p">(</span><span class="n">command</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""</span>
<span class="sd"> Return a completer that will remove the quotes, i.e:</span>
<span class="sd"> which "python"<TAB> -> which python</span>
<span class="sd"> echo "hi<TAB> -> echo hi</span>
<span class="sd"> ls "file with spaces"<TAB> -> ls file with spaces</span>
<span class="sd"> """</span>
<span class="n">raw_prefix_len</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">command</span><span class="o">.</span><span class="n">raw_prefix</span><span class="p">)</span> <span class="c1"># this includes the closing quote if it exists</span>
<span class="k">return</span> <span class="p">{</span><span class="n">RichCompletion</span><span class="p">(</span><span class="n">command</span><span class="o">.</span><span class="n">prefix</span><span class="p">,</span> <span class="n">prefix_len</span><span class="o">=</span><span class="n">raw_prefix_len</span><span class="p">,</span> <span class="n">append_closing_quote</span><span class="o">=</span><span class="kc">False</span><span class="p">)}</span>
</pre></div>
</div>
</section>
</section>
<section id="legacy-completers-support">
<h2>Legacy Completers Support<a class="headerlink" href="#legacy-completers-support" title="Link to this heading">¶</a></h2>
<p>Before completion context was introduced, xonsh had a different readline-like completion API.
While this legacy API is not recommended, xonsh still supports it.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The legacy completers are less robust than the contextual system in many situations, for example:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">$(which<TAB></span></code> completes with the prefix <code class="docutils literal notranslate"><span class="pre">$(which</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">'a</span> <span class="pre">file<TAB></span></code> completes with the prefix <code class="docutils literal notranslate"><span class="pre">file</span></code> (instead of <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">file</span></code>)</p></li>
</ul>
<p>See <a class="reference external" href="https://github.com/xonsh/xonsh/pull/4017">Completion Context PR</a> for more information.</p>
</div>
<p>Legacy completers are python functions that aren’t marked by <code class="docutils literal notranslate"><span class="pre">@contextual_completer</span></code> and receive the following arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">prefix</span></code>: the string to be matched (the last whitespace-separated token in the current line)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">line</span></code>: a string representing the entire current line</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">begidx</span></code>: the index at which <code class="docutils literal notranslate"><span class="pre">prefix</span></code> starts in <code class="docutils literal notranslate"><span class="pre">line</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">endidx</span></code>: the length of the <code class="docutils literal notranslate"><span class="pre">prefix</span></code> in <code class="docutils literal notranslate"><span class="pre">line</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ctx</span></code>: the current Python environment, as a dictionary mapping names to values</p></li>
</ul>
<p>Their return value can be any of the variations of the contextual completers’.</p>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="next-page" href="tutorial_history_backend.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Tutorial: Write Your Own History Backend</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="tutorial_events.html">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Tutorial: Events</div>
</div>
</a>
</div>
<div class="bottom-of-page">
<div class="left-details">
<div class="copyright">
Copyright © 2015, Anthony Scopatz
</div>
Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
<a href="https://github.com/pradyunsg/furo">Furo</a>
</div>
<div class="right-details">
</div>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
On this page
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Tutorial: Programmable Tab-Completion</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#structure">Structure</a></li>
<li><a class="reference internal" href="#listing-active-completers">Listing Active Completers</a></li>
<li><a class="reference internal" href="#writing-a-new-completer">Writing a New Completer</a></li>
<li><a class="reference internal" href="#registering-a-completer">Registering a Completer</a></li>
<li><a class="reference internal" href="#removing-a-completer">Removing a Completer</a></li>
<li><a class="reference internal" href="#advanced-completions">Advanced Completions</a><ul>
<li><a class="reference internal" href="#completing-closed-string-literals">Completing Closed String Literals</a></li>
</ul>
</li>
<li><a class="reference internal" href="#legacy-completers-support">Legacy Completers Support</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=ecbec2ee"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=32e29ea5"></script>
<script src="_static/runthis-client.min.js?v=ad2a40d9"></script>
</body>
</html>