Coverage for C:\leo.repo\leo-editor\leo\commands\helpCommands.py: 39%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2#@+leo-ver=5-thin
3#@+node:ekr.20150514040138.1: * @file ../commands/helpCommands.py
4#@@first
5"""Leo's help commands."""
6#@+<< imports >>
7#@+node:ekr.20150514050337.1: ** << imports >> (helpCommands.py)
8import io
9import re
10import sys
11import textwrap
12from leo.core import leoGlobals as g
13from leo.commands.baseCommands import BaseEditCommandsClass
14#@-<< imports >>
16def cmd(name):
17 """Command decorator for the helpCommands class."""
18 return g.new_cmd_decorator(name, ['c', 'helpCommands',])
20#@+others
21#@+node:ekr.20160514121110.1: ** class HelpCommandsClass
22class HelpCommandsClass(BaseEditCommandsClass):
23 """A class to load files into buffers and save buffers to files."""
24 #@+others
25 #@+node:ekr.20150514063305.373: *3* help
26 @cmd('help')
27 def help_command(self, event=None):
28 """Prints an introduction to Leo's help system."""
29 #@+<< define rst_s >>
30 #@+node:ekr.20150514063305.374: *4* << define rst_s >> (F1)
31 #@@language rest
33 rst_s = '''
35 **Welcome to Leo's help system.**
37 Alt-0 (vr-toggle) hides this help message.
39 To learn about ``<Alt-X>`` commands, type::
41 <Alt-X>help-for-minibuffer<Enter>
43 To get a list of help topics, type::
45 <Alt-X>help-<tab>
47 For Leo commands (tab completion allowed), type::
49 <Alt-X>help-for-command<Enter>
50 <a Leo command name><Enter>
52 To use Python's help system, type::
54 <Alt-X>help-for-python<Enter>
55 <a python symbol><Enter>
57 For the command bound to a key, type::
59 <Alt-X>help-for-keystroke<Enter><any key>
61 '''
62 #@-<< define rst_s >>
63 self.c.putHelpFor(rst_s)
64 #@+node:ekr.20150514063305.375: *3* helpForAbbreviations
65 @cmd('help-for-abbreviations')
66 def helpForAbbreviations(self, event=None):
67 """Prints a discussion of abbreviations."""
68 #@+<< define s >>
69 #@+node:ekr.20150514063305.376: *4* << define s >> (helpForAbbreviations)
70 #@@language rest
72 s = r'''\
74 About Abbreviations
75 -------------------
77 Alt-0 (vr-toggle) hides this help message.
79 Leo optionally expands abbreviations as you type.
81 Abbreviations typically end with something like ";;" so they won't trigger
82 by accident.
84 You define abbreviations in @data abbreviations nodes or @data
85 global-abbreviations nodes. None come predefined, but leoSettings.leo
86 contains example abbreviations in the node::
88 @@data abbreviations examples
90 Abbreviations can simply be shortcuts::
92 ncn;;=@nocolor
94 Abbreviations can span multiple lines. Continued lines start with \\:, like
95 this::
97 form;;=<form action="main_submit" method="get" accept-charset="utf-8">
98 \:<p><input type="submit" value="Continue →"></p>
99 \:</form>\n
101 Abbreviations can define templates in which <\|a-field-name\|> denotes a field
102 to be filled in::
104 input;;=<input type="text/submit/hidden/button"
105 \:name="<|name|>"
106 \:value="" id="<|id|>">\n
108 Typing ",," after inserting a template selects the next field.
110 Abbreviations can execute **abbreviation scripts**, delimited by {\|{ and
111 }\|}::
113 date;;={|{import time ; x=time.asctime()}|}
114 ts;;={|{import time ; x=time.strftime("%Y%m%d%H%M%S")}|}
116 For example, typing ts;; gives::
118 20131009171117
120 It's even possible to define a context in which abbreviation scripts execute.
122 See leoSettings.leo for full details.
124 '''
125 #@-<< define s >>
126 self.c.putHelpFor(s)
127 #@+node:ekr.20150514063305.377: *3* helpForAutocompletion
128 @cmd('help-for-autocompletion')
129 def helpForAutocompletion(self, event=None):
130 """Prints a discussion of autocompletion."""
131 #@+<< define s >>
132 #@+node:ekr.20150514063305.378: *4* << define s >> (helpForAutocompletion)
133 # @pagewidth 40
134 #@@language rest
136 s = '''
138 About Autocompletion and Calltips
139 ---------------------------------
141 Alt-0 (vr-toggle) hides this help message.
143 This documentation describes both
144 autocompletion and calltips.
146 Typing a period when @language python is
147 in effect starts autocompletion. Typing
148 '(' during autocompletion shows the
149 calltip. Typing Return or Control-g
150 (keyboard-quit) exits autocompletion or
151 calltips.
153 Autocompletion
154 ==============
156 Autocompletion shows what may follow a
157 period in code. For example, after
158 typing g. Leo will show a list of all
159 the global functions in leoGlobals.py.
160 Autocompletion works much like tab
161 completion in the minibuffer. Unlike the
162 minibuffer, the presently selected
163 completion appears directly in the body
164 pane.
166 A leading period brings up 'Autocomplete
167 Modules'. (The period goes away.) You
168 can also get any module by typing its
169 name. If more than 25 items would appear
170 in the Autocompleter tab, Leo shows only
171 the valid starting characters. At this
172 point, typing an exclamation mark shows
173 the complete list. Thereafter, typing
174 further exclamation marks toggles
175 between full and abbreviated modes.
177 If x is a list 'x.!' shows all its
178 elements, and if x is a Python
179 dictionary, 'x.!' shows list(x.keys()).
180 For example, 'sys.modules.!' Again,
181 further exclamation marks toggles
182 between full and abbreviated modes.
184 During autocompletion, typing a question
185 mark shows the docstring for the object.
186 For example: 'g.app?' shows the
187 docstring for g.app. This doesn't work
188 (yet) directly for Python globals, but
189 '__builtin__.f?' does. Example:
190 '__builtin__.pow?' shows the docstring
191 for pow.
193 Autocompletion works in the Find tab;
194 you can use <Tab> to cycle through the
195 choices. The 'Completion' tab appears
196 while you are doing this; the Find tab
197 reappears once the completion is
198 finished.
200 Calltips
201 ========
203 Calltips appear after you type an open
204 parenthesis in code. Calltips shows the
205 expected arguments to a function or
206 method. Calltips work for any Python
207 function or method, including Python's
208 global function. Examples:
210 a) g.toUnicode(
211 gives:
212 g.toUnicode(s,encoding, reportErrors=False
214 b) c.widgetWantsFocusNow
215 gives:
216 c.widgetWantsFocusNow(w
218 c) reduce(
219 gives:
220 reduce(function, sequence[,initial]) -> value
222 The calltips appear directly in the text
223 and the argument list is highlighted so
224 you can just type to replace it. The
225 calltips appear also in the status line
226 for reference after you have started to
227 replace the args.
229 Options
230 =======
232 Both autocompletion and calltips are
233 initially enabled or disabled by the
234 enable_autocompleter_initially and
235 enable_calltips_initially settings in
236 leoSettings.leo. You may enable or
237 disable these features at any time with
238 these commands: enable-autocompleter,
239 enable-calltips, disable-autocompleter
240 and disable-calltips. '''
241 #@-<< define s >>
242 self.c.putHelpFor(s)
243 #@+node:ekr.20150514063305.379: *3* helpForBindings
244 @cmd('help-for-bindings')
245 def helpForBindings(self, event=None):
246 """Prints a discussion of keyboard bindings."""
247 #@+<< define s >>
248 #@+node:ekr.20150514063305.380: *4* << define s >> (helpForBindings)
249 # @pagewidth 40
250 #@@language rest
252 s = '''
254 About Key Bindings
255 ------------------
257 Alt-0 (vr-toggle) hides this help message.
259 A shortcut specification has the form:
261 command-name = shortcutSpecifier
263 or
265 command-name ! pane = shortcutSpecifier
267 The first form creates a binding for all
268 panes except the minibuffer. The second
269 form creates a binding for one or more
270 panes. The possible values for 'pane'
271 are:
273 ==== ===============
274 pane bound panes
275 ==== ===============
276 all body,log,tree
277 body body
278 log log
279 mini minibuffer
280 text body,log
281 tree tree
282 ==== ===============
284 You may use None as the specifier.
285 Otherwise, a shortcut specifier consists
286 of a head followed by a tail. The head
287 may be empty, or may be a concatenation
288 of the following: (All entries in each
289 row are equivalent)::
291 Shift+ Shift-
292 Alt+ or Alt-
293 Control+, Control-, Ctrl+ or Ctrl-
295 Notes:
297 1. The case of plain letters is significant:
298 a is not A.
300 2. The Shift- (or Shift+) prefix can be
301 applied *only* to letters or
302 multi-letter tails. Leo will ignore
303 (with a warning) the shift prefix
304 applied to other single letters,
305 e.g., Ctrl-Shift-(
307 3. The case of letters prefixed by
308 Ctrl-, Alt-, Key- or Shift- is *not*
309 significant.
311 The following table illustrates these
312 rules. In each row, the first entry is
313 the key (for k.bindingsDict) and the
314 other entries are equivalents that the
315 user may specify in leoSettings.leo::
317 a, Key-a, Key-A
318 A, Shift-A
319 Alt-a, Alt-A
320 Alt-A, Alt-Shift-a, Alt-Shift-A
321 Ctrl-a, Ctrl-A
322 Ctrl-A, Ctrl-Shift-a, Ctrl-Shift-A
323 !, Key-!,Key-exclam,exclam
325 '''
326 #@-<< define s >>
327 self.c.putHelpFor(s)
328 #@+node:ekr.20150514063305.381: *3* helpForCommand & helpers
329 @cmd('help-for-command')
330 def helpForCommand(self, event):
331 """Prompts for a command name and prints the help message for that command."""
332 c, k = self.c, self.c.k
333 s = '''\
334 Alt-0 (vr-toggle) hides this help message.
336 Type the name of the command, followed by Return.
337 '''
338 c.putHelpFor(s)
339 c.minibufferWantsFocusNow()
340 k.fullCommand(event, help=True, helpHandler=self.helpForCommandFinisher)
341 #@+node:ekr.20150514063305.382: *4* getBindingsForCommand
342 def getBindingsForCommand(self, commandName):
343 k = self.c.k
344 data = []
345 n1, n2 = 4, 20
346 d = k.bindingsDict
347 for stroke in sorted(d):
348 assert g.isStroke(stroke), repr(stroke)
349 aList = d.get(stroke, [])
350 for bi in aList:
351 if bi.commandName == commandName:
352 pane = '' if bi.pane == 'all' else f" {bi.pane}:"
353 s1 = pane
354 s2 = k.prettyPrintKey(stroke)
355 s3 = bi.commandName
356 n1 = max(n1, len(s1))
357 n2 = max(n2, len(s2))
358 data.append((s1, s2, s3),)
359 data.sort(key=lambda x: x[1])
360 return ','.join([f"{z1} {z2}" for z1, z2, z3 in data]).strip()
361 #@+node:ekr.20150514063305.383: *4* helpForCommandFinisher
362 def helpForCommandFinisher(self, commandName):
363 c, s = self.c, None
364 if commandName and commandName.startswith('help-for-'):
365 # Execute the command itself.
366 c.k.simulateCommand(commandName)
367 else:
368 if commandName:
369 bindings = self.getBindingsForCommand(commandName)
370 func = c.commandsDict.get(commandName)
371 s = g.getDocStringForFunction(func)
372 if s:
373 s = self.replaceBindingPatterns(s)
374 else:
375 s = 'no docstring available'
376 # Create the title.
377 s2 = f"{commandName} ({bindings})" if bindings else commandName
378 underline = '+' * len(s2)
379 title = f"{s2}\n{underline}\n\n"
380 if 1: # 2015/03/24
381 s = title + textwrap.dedent(s)
382 else:
383 # Fixes bug 618570:
384 s = title + ''.join([
385 line.lstrip() if line.strip() else '\n'
386 for line in g.splitLines(s)])
387 else:
388 #@+<< set s to about help-for-command >>
389 #@+node:ekr.20150514063305.384: *5* << set s to about help-for-command >>
390 s = '''\
392 ++++++++++++++++++++++++
393 About Leo's help command
394 ++++++++++++++++++++++++
396 Invoke Leo's help-for-command as follows::
398 <F1>
399 <Alt-X>help-for-command<return>
401 Next, type the name of one of Leo's commands.
402 You can use tab completion. Examples::
404 <F1><tab> shows all commands.
405 <F1>help-for<tab> shows all help-for- commands.
407 Here are the help-for commands::
409 help-for-abbreviations
410 help-for-autocompletion
411 help-for-bindings
412 help-for-command
413 help-for-debugging-commands
414 help-for-dynamic-abbreviations
415 help-for-find-commands
416 help-for-minibuffer
417 help-for-python
418 help-for-regular-expressions
420 '''
421 #@-<< set s to about help-for-command >>
422 c.putHelpFor(s)
423 #@+node:ekr.20150514063305.385: *4* replaceBindingPatterns
424 def replaceBindingPatterns(self, s):
425 """
426 For each instance of the pattern !<command-name>! in s,
427 replace the pattern by the key binding for command-name.
428 """
429 c = self.c
430 pattern = re.compile(r'!<(.*)>!')
431 while True:
432 m = pattern.search(s, 0)
433 if m is None:
434 break
435 name = m.group(1)
436 junk, aList = c.config.getShortcut(name)
437 for bi in aList:
438 if bi.pane == 'all':
439 key = c.k.prettyPrintKey(bi.stroke.s)
440 break
441 else:
442 key = f"<Alt-X>{name}<Return>"
443 s = s[: m.start()] + key + s[m.end() :]
444 return s
445 #@+node:ekr.20150514063305.386: *3* helpForCreatingExternalFiles
446 @cmd('help-for-creating-external-files')
447 def helpForCreatingExternalFiles(self, event=None):
448 """Prints a discussion of creating external files."""
449 #@+<< define s >>
450 #@+node:ekr.20150514063305.387: *4* << define s >> (helpForCreatingExternalFiles)
451 #@@language rest
453 s = r'''
455 Creating External Files
456 -------------------------
458 This help discusses only @file nodes.
459 For other ways of creating external files, see::
461 http://leoeditor.com/tutorial-programming.html or
462 http://leoeditor.com/directives.html
464 Leo creates external files in an unusual way.
465 Please fee free to ask for help::
467 https://groups.google.com/forum/#!forum/leo-editor or
468 http://webchat.freenode.net/?channels=%23leo&uio=d4
470 Overview
471 ========
473 Leo creates **external files** (files on your file system) from
474 **@file nodes** and *all the descendants* of the @file node.
475 Examples::
477 @file spam.py
478 @file ../foo.c
479 @file ~/bar.py
481 A single Leo outline may contain many @file nodes. As a result, Leo
482 outlines function much like project files in other IDE's (Integrated
483 development environments).
485 Within an @file tree, simple text markup (discussed next) tells Leo how
486 to create the external file from the @file node and its descendants.
488 Markup
489 ======
491 Section references and the \\@all and \\@others directives tell
492 Leo how to create external files.
494 - A **section name** is any text of the form::
496 <\\< any text >\\> (>> must not appear in "any text".)
498 - A **section definition node** is any node whose headline starts with a section name.
500 - A **section reference** is a section name that appears in body text.
502 Leo creates external files containing \\@others directives by writing the
503 *expansion* of the @file node. The **expansion** of *any* node is the
504 node's body text after making these text **substitutions**:
506 - Leo replaces \\@all by the *unexpanded* body text of *all* nodes.
508 - Leo replaces \\@others with the *expansion* of all descendant nodes
509 **except** section definition nodes. That's how \\@others got its name.
511 - Leo replaces section references by the *expansion* of the body text of
512 the corresponding section definition node.
514 Whitespace is significant before \\@others and section references. Leo adds
515 the leading whitespace appearing before each \\@others directive or section
516 reference to every line of their expansion. As a result, Leo can generate
517 external files even for Python. The following cute trick works::
519 if 1:
520 <\\< a section >\\>
521 if 0:
522 \\@others
524 **Notes**:
526 - Any node may contain a single \\@others directive. No node may contain more
527 than one \@others directive.
529 - Nodes that *aren't* section definition nodes are included in the expansion
530 of the *nearest* ancestor node containing an @others directive.
532 **Example 1**: The body of the @file node for a typical Python module will
533 look something like::
535 '\\''A docstring.'\\''
536 <\\< imports >\\>
537 \@others
538 if __name__ == '__main__':
539 main()
541 **Example 2**: Here is a typical Python class definition in Leo::
543 class MyClass:
544 '\\''A docstring.'\\''
545 \@others
547 \@first and @last
548 =================
550 The @first directive forces lines to appear before the first sentinel of a
551 external file. For example::
553 @first #! /usr/bin/env python
554 @first # -*- coding: utf-8 -*-
556 Similarly, @last forces lines to appear after the last sentinel.
558 \\@path
559 =======
561 Rather than specifying long paths in @file nodes, you can specify a path in
562 an ancestor @path node.
564 For example, suppose three nodes have the following headlines::
566 @path a
567 @path b
568 @file c/d.py
570 The @file node creates the file a/b/c/d.py
572 Within @path and @<file> paths, {{exp}} gets evaluated with the following
573 predefined symbols: c, g, p, os and sys. For example::
575 @file {{os.path.abspath(os.curdir)}}/abc.py
577 '''
578 #@-<< define s >>
579 s = s.replace('\\', '')
580 self.c.putHelpFor(s)
581 #@+node:ekr.20150514063305.388: *3* helpForDebuggingCommands
582 @cmd('help-for-debugging-commands')
583 def helpForDebuggingCommands(self, event=None):
584 """Prints a discussion of of Leo's debugging commands."""
585 #@+<< define s >>
586 #@+node:ekr.20150514063305.389: *4* << define s >> (helpForDebuggingCommands)
587 # @pagewidth 40
588 #@@language rest
590 s = '''
592 About Debugging Commands
593 ------------------------
595 Alt-0 (vr-toggle) hides this help message.
597 The following commands are useful for debugging::
599 debug: Start an external debugger in another process.
600 dump-node: Dump c.p.v, including gnx, uA's, etc.
601 gc-collect-garbage: Invoke the garbage collector.
602 gc-dump-all-objects: Print a summary of all Python objects.
603 gc-show-summary: Print a brief summary of Python objects.
604 pdb: Start Python's debugger.
605 show-focus: Print information about the requested focus.
606 show-stats: Print statistics about existing Python objects.
608 Leo's --trace command-line arg can enable traces.
609 '''
610 #@-<< define s >>
611 self.c.putHelpFor(s)
612 #@+node:ekr.20150514063305.390: *3* helpForDragAndDrop
613 @cmd('help-for-drag-and-drop')
614 def helpForDragAndDrop(self, event=None):
615 """Prints a discussion of of Leo's debugging commands."""
616 #@+<< define s >>
617 #@+node:ekr.20150514063305.391: *4* << define s >> (helpForDragAndDrop
618 # @pagewidth 40
619 #@@language rest
621 s = '''
623 About Drag and Drop
624 ===================
626 Nodes
627 -----
629 You may drag nodes from within a Leo outline or between Leo outlines,
630 including nodes from separately running copies of Leo.
632 To drag, click and hold on a headline and drag it over another headline.
633 Control-drags create clones; regular drags move the node.
635 Files
636 -----
638 You may also drag one or more files from a file folder over a headline.
640 For text files, Leo will create @auto, @edit or @file nodes as appropriate.
642 Dragging .leo files from a file folder to a Leo outline works like the
643 open-outline command. Control-dragging .leo files copies all nodes of the
644 .leo file to the receiving outline, under a single node called::
646 From <name of .leo file>
648 '''
649 #@-<< define s >>
650 self.c.putHelpFor(s)
651 #@+node:ekr.20150514063305.392: *3* helpForDynamicAbbreviations
652 @cmd('help-for-dynamic-abbreviations')
653 def helpForDynamicAbbreviations(self, event=None):
654 """Prints a discussion of abbreviations."""
655 #@+<< define s >>
656 #@+node:ekr.20150514063305.393: *4* << define s >> (helpForDynamicAbbreviations)
657 #@@language rest
659 s = '''
661 About Dynamic Abbreviations
662 ---------------------------
664 Alt-0 (vr-toggle) hides this help message.
666 .. Description taken from http://www.emacswiki.org/emacs/DynamicAbbreviations
668 A dynamic abbreviation (dabbrev) is like a normal abbreviation except:
670 - You do not have to define it(!)
671 - You expand it with Alt-/ (dabbrev-expand) or Alt-Ctrl-/ (dabbrev-completion)
673 For example, suppose the text aLongIvarName appears anywhere in the
674 outline. To type this name again type::
676 aLong<Alt-/>
678 You will see a list of possible completions in the log pane.
680 Alt-Ctrl-/ (dabbrev-completion) inserts the longest prefix of all
681 completions immediately. For instance, suppose the following appear in text::
683 aVeryLongIvarName
684 aVeryLongMethodName
686 Typing::
688 aVery<Alt-Ctrl-/>
690 will immediately extend the typing to::
692 aVeryLong
694 '''
695 #@-<< define s >>
696 self.c.putHelpFor(s)
697 #@+node:ekr.20150514063305.394: *3* helpForFindCommands
698 @cmd('help-for-find-commands')
699 def helpForFindCommands(self, event=None):
700 """Prints a discussion of of Leo's find commands."""
701 #@+<< define s >>
702 #@+node:ekr.20150514063305.395: *4* << define s >> (help-for-find-commands)
703 #@@language rest
705 s = '''
707 Finding & replacing text
708 ------------------------
710 Alt-0 (vr-toggle) hides this help message.
712 **Ctrl-F** (start-search) shows the Find pane
713 and puts focus in the find box.
715 Enter the find text and the replacement text if desired::
717 Tab switches focus from widget to widget.
718 Return executes the find-next command.
720 When Leo selects the found text you can do::
722 Ctrl-equal (replace)
723 Ctrl-minus (replace-then-find)
724 F3 (find-next)
725 F2 (find-previous)
726 Ctrl-G (keyboard-quit)
727 anything else :-)
729 You can Leo's commands toggle check boxes and radio buttons.
730 These commands are listed in the Search menu.
732 You can execute these commands (and see their key bindings)
733 using the minibuffer::
735 <Alt-X>tog<tab>f<tab> or
736 <Alt-X>set<tab>f<tab>
738 Incremental searching
739 ---------------------
741 Incremental search is done only from the minibuffer::
743 Alt-I (isearch forward)
744 Alt-R (isearch backward)
745 BackSpace retracts the search
746 All other characters extend the search
748 During an incremental search::
750 Enter or Ctrl-G stops the search.
751 Alt-S finds the search string again.
752 Alt-R ditto for reverse searches.
753 '''
754 #@-<< define s >>
755 self.c.putHelpFor(s)
756 #@+node:ekr.20150628161341.1: *3* helpForKeystroke
757 @cmd('help-for-keystroke')
758 def helpForKeystroke(self, event):
759 """Prompts for any key and prints the bindings for that key."""
760 c, k = self.c, self.c.k
761 state_name = 'help-for-keystroke'
762 state = k.getState(state_name)
763 if state == 0:
764 k.setLabelBlue('Enter any key: ')
765 k.setState(state_name, 1, self.helpForKeystroke)
766 c.minibufferWantsFocus()
767 else:
768 d = k.bindingsDict
769 k.clearState()
770 result = []
771 for bi in d.get(event.stroke, []): # a list of BindingInfo objects.
772 pane, cmd = bi.pane, bi.commandName
773 result.append(cmd if pane == 'all' else f"{pane}: {cmd}")
774 s = f"{event.stroke.s}: {','.join(result)}"
775 k.showStateAndMode()
776 c.frame.putStatusLine(s, bg='blue', fg='white')
777 c.bodyWantsFocus()
778 #@+node:ekr.20150514063305.396: *3* helpForMinibuffer
779 @cmd('help-for-minibuffer')
780 def helpForMinibuffer(self, event=None):
781 """Print a messages telling you how to get started with Leo."""
782 # A bug in Leo: triple quotes puts indentation before each line.
783 c = self.c
784 #@+<< define s >>
785 #@+node:ekr.20150514063305.397: *4* << define s >> (helpForMinibuffer)
786 #@@language rest
788 s = '''\
790 About the Minibuffer
791 --------------------
793 Alt-0 (vr-toggle) hides this help message.
795 The mini-buffer is intended to be like the Emacs buffer:
797 full-command: (default shortcut: Alt-x) Puts the focus in the minibuffer. Type a
798 full command name, then hit <Return> to execute the command. Tab completion
799 works, but not yet for file names.
801 quick-command-mode (default shortcut: Alt-x). Like Emacs Control-C. This mode is
802 defined in leoSettings.leo. It is useful for commonly-used commands.
804 universal-argument (default shortcut: Alt-u). Like Emacs Ctrl-u. Adds a repeat
805 count for later command. Ctrl-u 999 a adds 999 a's. Many features remain
806 unfinished.
808 keyboard-quit (default shortcut: Ctrl-g) Exits any minibuffer mode and puts
809 the focus in the body pane.
811 Use the help-for-command command to see documentation for a particular command.
812 '''
813 #@-<< define s >>
814 c.putHelpFor(s)
815 #@+node:ekr.20150514063305.398: *3* helpForRegularExpressions
816 @cmd('help-for-regular-expressions')
817 def helpForRegularExpressions(self, event=None):
818 """Prints a discussion of of Leo's find commands."""
819 #@+<< define s >>
820 #@+node:ekr.20150514063305.399: *4* << define s >> (helpForRegularExpressions)
821 #@@language rest
823 # Using raw string is essential.
825 s = r'''
827 About regular expressions
828 -------------------------
830 Alt-0 (vr-toggle) hides this help message.
832 Python's regular expressions, http://docs.python.org/library/re.html,
833 are valid in find patterns::
835 . Matches any character (including newline if DOTALL flag specified).
836 ^ Matches start of the string (of every line in MULTILINE mode).
837 $ Matches end of the string (of every line in MULTILINE mode).
838 * 0 or more of preceding regular expression (as many as possible).
839 + 1 or more of preceding regular expression (as many as possible).
840 ? 0 or 1 occurrence of preceding regular expression.
841 *?, +?, ?? Same as *, + and ? but matches as few characters as possible.
842 {m,n} Matches from m to n repetitions of preceding RE.
843 {m,n}? Same as {m,n}, but attempting to match as few repetitions as possible.
844 [ ] Defines character set: e.g. '[a-zA-Z]' to match all letters (see also \w \S).
845 [^ ] Defines complemented character set: matches if char is NOT in set.
846 \ Escapes special chars '*?+&$|()' and introduces special sequences (see below).
847 If not using a raw string, write as '\\' in the pattern string.
848 \\ Matches a literal '\'.
849 | Specifies alternative: 'foo|bar' matches 'foo' or 'bar'.
850 (...) Matches any RE inside (), and delimits a group.
851 (?:...) Mathces RE inside (), but doesn't delimit a group.
852 (?P<name>...) Matches any RE inside (), and delimits a named group.
853 r'(?P<id>[a-zA-Z_]\w*)' defines a group named id.
854 (?P=name) Matches whatever text was matched by the earlier group named name.
855 (?=...) Matches if ... matches next, but doesn't consume any of the string
856 'Isaac (?=Asimov)' matches 'Isaac' only if followed by 'Asimov'.
857 (?!...) Matches if ... doesn't match next. Negative of (?=...).
858 (?<=...) Matches if the current position in the string is preceded by a match
859 for ... that ends at the current position.
860 This is called a positive lookbehind assertion.
861 (?<!...) Matches if the current position in the string is not preceded by a match for ...
862 This is called a negative lookbehind assertion.
863 (?(group)A|B) Group is either a numeric group ID or a group name defined with (?Pgroup...)
864 earlier in the expression.
865 If the specified group matched, the regular expression pattern A will be tested
866 against the string; if the group didn't match, the pattern B will be used instead.
867 (?#...) A comment; ignored.
868 (?letters) Each letter is in 'ilmsux' and sets the corresponding flag.
869 re.I, re.L, re.M, re.S, re.U, re.X.
870 \number Matches content of the group of the same number.
871 \A Matches only at the start of the string.
872 \b Empty str at beginning or end of word:
873 '\bis\b' matches 'is', but not 'his'.
874 \B Empty str NOT at beginning or end of word.
875 \d Any decimal digit: [0-9]
876 \D Any non-decimal digit char [^0-9]).
877 \s Any whitespace char [ \t\n\r\f\v]
878 \S Any non-whitespace char [^ \t\n\r\f\v]
879 \w Any alphaNumeric char (depends on LOCALE flag).
880 \W Any non-alphaNumeric char (depends on LOCALE flag).
881 \Z Matches only at the end of the string.
883 '''
884 #@-<< define s >>
885 self.c.putHelpFor(s)
886 #@+node:ekr.20150514063305.400: *3* helpForScripting
887 @cmd('help-for-scripting')
888 def helpForScripting(self, event=None):
889 """Prints a discussion of Leo scripting."""
890 #@+<< define s >>
891 #@+node:ekr.20150514063305.401: *4* << define s >> (helpForScripting)
892 #@@language rest
894 s = '''
896 Summary of Leo Scripting
897 -------------------------
899 Overview
900 ========
902 Any Leo node may contain a Python script.
904 Ctrl-B (execute-script) executes the body text of the presently selected node.
906 execute-script creates the script using @others and section references:
907 **you can create complex scripts from a node and its descendants.**
909 As discussed below, execute-script predefines three variables: c, g and p.
910 Using these variables, scripts may easily do any of the following:
912 - Gain access to all data contained in any Leo outline.
913 - Traverse the data in any outline.
914 - Use utility classes and function in the leo.core.leoGlobals module.
915 - Execute any code in Leo's own code base.
917 *Tip*: use Alt-1 (toggle-autocompleter) and Alt-2 (toggle-calltips) as aids to memory and to speed typing.
919 Predefined symbols
920 ==================
922 The execute-script command predefines three variables::
924 c: The commander of the present outline.
925 g: The leo.core.leoGlobals module.
926 p: The presently selected position, c.p.
928 Commands class
929 ==============
931 A commander is an instance of the Commands class in leo.core.leoCommands.
932 A commander represents all outline data and most of Leo's source code.
933 Here are the most important ivars of the Commands class::
935 c.frame c's outer frame, a LeoFrame instance.
936 c.user_dict a temporary dict for use of scripts and plugins.
937 c.redraw()
938 c.positionExists(p)
940 Here is a partial list of the **official ivars** of any commander c:
942 c.frame The frame containing the log,body,tree, etc.
943 c.frame.body The body pane.
944 c.frame.body.widget The gui widget for the body pane.
945 c.frame.body.wrapper The high level interface for the body widget.
946 c.frame.iconBar The icon bar.
947 c.frame.log The log pane.
948 c.frame.log.widget The gui widget for the log pane.
949 c.frame.log.wrapper The high-level inteface for the log pane.
950 c.frame.tree The tree pane.
952 VNode class
953 ===========
955 All data in Leo outlines resides in vnodes.
956 All clones of the same node share the same VNode.
957 Here are the most important ivars and properties of the VNode class::
959 v.b: v's body text.
960 v.h: v's headline text.
961 v.u: v.unknownAttributes, a persistent Python dictionary.
963 v.u (uA's or unknownAttributes or userAttributes) allow plugins or scripts
964 to associate persistent data with vnodes. For details see the section about
965 userAttributes in the Customizing Leo chapter.
967 Position class
968 ==============
970 A position represents the state of a traversal of an outline.
971 Because of clones, the same VNode may appear multiple times during a traversal.
973 Properties of the position class::
975 p.b: same as p.v.b.
976 p.h: same as p.v.h.
977 p.u: same as p.v.u.
979 Getter methods of the position class::
981 p.back()
982 p.children()
983 p.firstChild()
984 p.hasBack()
985 p.hasChildren()
986 p.hasNext()
987 p.hasParent()
988 p.hasThreadBack()
989 p.hasThreadNext()
990 p.isAncestorOf(p2)
991 p.isAnyAtFileNode()
992 p.isAt...Node()
993 p.isCloned()
994 p.isDirty()
995 p.isExpanded()
996 p.isMarked()
997 p.isRoot()
998 p.isVisible()
999 p.lastChild()
1000 p.level()
1001 p.next()
1002 p.nodeAfterTree()
1003 p.nthChild()
1004 p.numberOfChildren()
1005 p.parent()
1006 p.parents()
1007 p.threadBack()
1008 p.threadNext()
1009 p.visBack()
1010 p.visNext()
1012 Setter methods of the position class::
1014 p.setDirty()
1015 p.setMarked()
1017 Methods that operate on nodes::
1019 p.clone()
1020 p.contract()
1021 p.doDelete(new_position)
1022 p.expand()
1023 p.insertAfter()
1024 p.insertAsNthChild(n)
1025 p.insertBefore()
1026 p.moveAfter(p2)
1027 p.moveToFirstChildOf(parent,n)
1028 p.moveToLastChildOf(parent,n)
1029 p.moveToNthChildOf(parent,n)
1030 p.moveToRoot()
1032 The following position methods move positions *themselves*: they change the
1033 node to which a position refers. They do *not* change outline structure in
1034 any way! Use these when generators are not flexible enough::
1036 p.moveToBack()
1037 p.moveToFirstChild()
1038 p.moveToLastChild()
1039 p.moveToLastNode()
1040 p.moveToNext()
1041 p.moveToNodeAfterTree(p2)
1042 p.moveToNthChild(n))
1043 p.moveToParent()
1044 p.moveToThreadBack()
1045 p.moveToThreadNext()
1046 p.moveToVisBack(c)
1047 p.moveToVisNext(c)
1049 Generators
1050 ==========
1052 The following Python generators return positions::
1054 c.all_positions()
1055 c.all_unique_positions()
1056 p.children()
1057 p.parents()
1058 p.self_and_parents()
1059 p.self_and_siblings()
1060 p.following_siblings()
1061 p.subtree()
1062 p.self_and_subtree()
1064 The leo.core.leoGlobals module
1065 ==============================
1067 **g vars**::
1069 g.app
1070 g.app.gui
1071 g.app.windowlist
1072 g.unitTesting
1073 g.user_dict # a temporary dict for use of scripts and plugins.
1075 **g decorator**::
1077 @g.command(command-name)
1079 **g functions** (the most interesting: there are many more in leoGlobals.py)::
1081 g.angleBrackets()
1082 g.app.commanders()
1083 g.app.gui.guiName()
1084 g.es(*args,**keys)
1085 g.es_print(*args,**keys)
1086 g.es_exception()
1087 g.getScript(c,p,
1088 useSelectedText=True,
1089 forcePythonSentinels=True,
1090 useSentinels=True)
1091 g.openWithFileName(fileName,old_c=None,gui=None)
1092 g.os_path_... # Wrappers for os.path methods.
1093 g.pdb(message='')
1094 g.toEncodedString(s,encoding='utf-8',reportErrors=False)
1095 g.toUnicode(s, encoding='utf-8',reportErrors=False)
1096 g.trace(*args,**keys)
1097 g.warning(*args,**keys)
1099 '''
1100 #@-<< define s >>
1101 self.c.putHelpFor(s)
1102 #@+node:ekr.20170823084423.1: *3* helpForSettings
1103 @cmd('help-for-settings')
1104 def helpForSettings(self, event=None):
1105 """Prints a discussion of of Leo's find commands."""
1106 #@+<< define s >>
1107 #@+node:ekr.20170823084456.1: *4* << define s >> (helpForSettings)
1108 #@@language rest
1110 # Using raw string is essential.
1112 s = r'''
1114 About settings
1115 ---------------
1117 **@settings trees** specify settings. The headline of each node indicates
1118 its type. The body text of most nodes contain comments. However, the body
1119 text of \@data, \@font, \@item and \@shortcuts nodes may contain data. For
1120 more information about the format of \@settings trees, see leoSettings.leo.
1122 leoSettings.leo is Leo's main settings file. myLeoSettings.leo contains
1123 your personal settings. Settings in myLeoSettings.leo override the settings
1124 in leoSettings.leo. Put myLeoSettigns.leo in your home `~` directory or in
1125 the `~/.leo` directory. Any other .leo file may contain an \@settings tree.
1126 Such settings apply only to that file.
1128 '''
1129 #@-<< define s >>
1130 self.c.putHelpFor(s)
1131 #@+node:ekr.20150514063305.402: *3* help.showSettings
1132 @cmd('show-settings')
1133 def showSettings(self, event=None):
1134 """
1135 Prints the value of every setting, except key bindings and commands and
1136 open-with tables. The following shows where the active setting came
1137 from:
1139 - leoSettings.leo,
1140 - @ @button, @command, @mode.
1141 - [D] default settings.
1142 - [F] indicates the file being loaded,
1143 - [M] myLeoSettings.leo,
1144 - [T] theme .leo file.
1145 """
1146 self.c.config.printSettings()
1147 #@+node:ekr.20190831025811.1: *3* help.showSettingsOutline (new: #852)
1148 @cmd('show-settings-outline')
1149 def showSettingsOutline(self, event=None):
1150 """
1151 Create and open an outline, summarizing all presently active settings.
1153 The outline retains the organization of all active settings files.
1155 See #852: https://github.com/leo-editor/leo-editor/issues/852
1156 """
1158 self.c.config.createActivesSettingsOutline()
1159 #@+node:ekr.20150514063305.403: *3* pythonHelp
1160 @cmd('help-for-python')
1161 def pythonHelp(self, event=None):
1162 """Prompt for a arg for Python's help function, and put it to the VR pane."""
1163 c, k = self.c, self.c.k
1164 c.minibufferWantsFocus()
1165 k.setLabelBlue('Python help: ')
1166 k.get1Arg(event, handler=self.pythonHelp1)
1168 def pythonHelp1(self, event):
1169 c, k = self.c, self.c.k
1170 k.clearState()
1171 k.resetLabel()
1172 s = k.arg.strip()
1173 if not s:
1174 return ''
1175 old = sys.stdout
1176 try:
1177 sys.stdout = io.StringIO()
1178 # If the argument is a string, the string is looked up as a name...
1179 # and a help page is printed on the console.
1180 help(str(s))
1181 s2 = sys.stdout.getvalue() # #2165
1182 finally:
1183 sys.stdout = old
1184 if not s2:
1185 return ''
1186 # Send it to the vr pane as a <pre> block
1187 s2 = '<pre>' + s2 + '</pre>'
1188 c.putHelpFor(s2)
1189 return s2 # For unit tests.
1190 #@-others
1191#@-others
1192#@-leo