Hide keyboard shortcuts

Hot-keys on this page

r m x p   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 >> 

15 

16def cmd(name): 

17 """Command decorator for the helpCommands class.""" 

18 return g.new_cmd_decorator(name, ['c', 'helpCommands',]) 

19 

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 

32 

33 rst_s = ''' 

34 

35 **Welcome to Leo's help system.** 

36 

37 Alt-0 (vr-toggle) hides this help message. 

38 

39 To learn about ``<Alt-X>`` commands, type:: 

40 

41 <Alt-X>help-for-minibuffer<Enter> 

42 

43 To get a list of help topics, type:: 

44 

45 <Alt-X>help-<tab> 

46 

47 For Leo commands (tab completion allowed), type:: 

48 

49 <Alt-X>help-for-command<Enter> 

50 <a Leo command name><Enter> 

51 

52 To use Python's help system, type:: 

53 

54 <Alt-X>help-for-python<Enter> 

55 <a python symbol><Enter> 

56 

57 For the command bound to a key, type:: 

58 

59 <Alt-X>help-for-keystroke<Enter><any key> 

60 

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 

71 

72 s = r'''\ 

73 

74 About Abbreviations 

75 ------------------- 

76 

77 Alt-0 (vr-toggle) hides this help message. 

78 

79 Leo optionally expands abbreviations as you type. 

80 

81 Abbreviations typically end with something like ";;" so they won't trigger 

82 by accident. 

83 

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:: 

87 

88 @@data abbreviations examples 

89 

90 Abbreviations can simply be shortcuts:: 

91 

92 ncn;;=@nocolor 

93 

94 Abbreviations can span multiple lines. Continued lines start with \\:, like 

95 this:: 

96 

97 form;;=<form action="main_submit" method="get" accept-charset="utf-8"> 

98 \:<p><input type="submit" value="Continue &rarr;"></p> 

99 \:</form>\n 

100 

101 Abbreviations can define templates in which <\|a-field-name\|> denotes a field 

102 to be filled in:: 

103 

104 input;;=<input type="text/submit/hidden/button" 

105 \:name="<|name|>" 

106 \:value="" id="<|id|>">\n 

107 

108 Typing ",," after inserting a template selects the next field. 

109 

110 Abbreviations can execute **abbreviation scripts**, delimited by {\|{ and 

111 }\|}:: 

112 

113 date;;={|{import time ; x=time.asctime()}|} 

114 ts;;={|{import time ; x=time.strftime("%Y%m%d%H%M%S")}|} 

115 

116 For example, typing ts;; gives:: 

117 

118 20131009171117 

119 

120 It's even possible to define a context in which abbreviation scripts execute. 

121 

122 See leoSettings.leo for full details. 

123 

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 

135 

136 s = ''' 

137 

138 About Autocompletion and Calltips 

139 --------------------------------- 

140 

141 Alt-0 (vr-toggle) hides this help message. 

142 

143 This documentation describes both 

144 autocompletion and calltips. 

145 

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. 

152 

153 Autocompletion 

154 ============== 

155 

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. 

165 

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. 

176 

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. 

183 

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. 

192 

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. 

199 

200 Calltips 

201 ======== 

202 

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: 

209 

210 a) g.toUnicode( 

211 gives: 

212 g.toUnicode(s,encoding, reportErrors=False 

213 

214 b) c.widgetWantsFocusNow 

215 gives: 

216 c.widgetWantsFocusNow(w 

217 

218 c) reduce( 

219 gives: 

220 reduce(function, sequence[,initial]) -> value 

221 

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. 

228 

229 Options 

230 ======= 

231 

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 

251 

252 s = ''' 

253 

254 About Key Bindings 

255 ------------------ 

256 

257 Alt-0 (vr-toggle) hides this help message. 

258 

259 A shortcut specification has the form: 

260 

261 command-name = shortcutSpecifier 

262 

263 or 

264 

265 command-name ! pane = shortcutSpecifier 

266 

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: 

272 

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 ==== =============== 

283 

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):: 

290 

291 Shift+ Shift- 

292 Alt+ or Alt- 

293 Control+, Control-, Ctrl+ or Ctrl- 

294 

295 Notes: 

296 

297 1. The case of plain letters is significant: 

298 a is not A. 

299 

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-( 

306 

307 3. The case of letters prefixed by 

308 Ctrl-, Alt-, Key- or Shift- is *not* 

309 significant. 

310 

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:: 

316 

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 

324 

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. 

335 

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 = '''\ 

391 

392 ++++++++++++++++++++++++ 

393 About Leo's help command 

394 ++++++++++++++++++++++++ 

395 

396 Invoke Leo's help-for-command as follows:: 

397 

398 <F1> 

399 <Alt-X>help-for-command<return> 

400 

401 Next, type the name of one of Leo's commands. 

402 You can use tab completion. Examples:: 

403 

404 <F1><tab> shows all commands. 

405 <F1>help-for<tab> shows all help-for- commands. 

406 

407 Here are the help-for commands:: 

408 

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 

419 

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 

452 

453 s = r''' 

454 

455 Creating External Files 

456 ------------------------- 

457 

458 This help discusses only @file nodes. 

459 For other ways of creating external files, see:: 

460 

461 http://leoeditor.com/tutorial-programming.html or 

462 http://leoeditor.com/directives.html 

463 

464 Leo creates external files in an unusual way. 

465 Please fee free to ask for help:: 

466 

467 https://groups.google.com/forum/#!forum/leo-editor or 

468 http://webchat.freenode.net/?channels=%23leo&uio=d4 

469 

470 Overview 

471 ======== 

472 

473 Leo creates **external files** (files on your file system) from 

474 **@file nodes** and *all the descendants* of the @file node. 

475 Examples:: 

476 

477 @file spam.py 

478 @file ../foo.c 

479 @file ~/bar.py 

480 

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). 

484 

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. 

487 

488 Markup 

489 ====== 

490 

491 Section references and the \\@all and \\@others directives tell 

492 Leo how to create external files. 

493 

494 - A **section name** is any text of the form:: 

495 

496 <\\< any text >\\> (>> must not appear in "any text".) 

497 

498 - A **section definition node** is any node whose headline starts with a section name. 

499 

500 - A **section reference** is a section name that appears in body text. 

501 

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**: 

505 

506 - Leo replaces \\@all by the *unexpanded* body text of *all* nodes. 

507 

508 - Leo replaces \\@others with the *expansion* of all descendant nodes 

509 **except** section definition nodes. That's how \\@others got its name. 

510 

511 - Leo replaces section references by the *expansion* of the body text of 

512 the corresponding section definition node. 

513 

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:: 

518 

519 if 1: 

520 <\\< a section >\\> 

521 if 0: 

522 \\@others 

523 

524 **Notes**: 

525 

526 - Any node may contain a single \\@others directive. No node may contain more 

527 than one \@others directive. 

528 

529 - Nodes that *aren't* section definition nodes are included in the expansion 

530 of the *nearest* ancestor node containing an @others directive. 

531 

532 **Example 1**: The body of the @file node for a typical Python module will 

533 look something like:: 

534 

535 '\\''A docstring.'\\'' 

536 <\\< imports >\\> 

537 \@others 

538 if __name__ == '__main__': 

539 main() 

540 

541 **Example 2**: Here is a typical Python class definition in Leo:: 

542 

543 class MyClass: 

544 '\\''A docstring.'\\'' 

545 \@others 

546 

547 \@first and @last 

548 ================= 

549 

550 The @first directive forces lines to appear before the first sentinel of a 

551 external file. For example:: 

552 

553 @first #! /usr/bin/env python 

554 @first # -*- coding: utf-8 -*- 

555 

556 Similarly, @last forces lines to appear after the last sentinel. 

557 

558 \\@path 

559 ======= 

560 

561 Rather than specifying long paths in @file nodes, you can specify a path in 

562 an ancestor @path node. 

563 

564 For example, suppose three nodes have the following headlines:: 

565 

566 @path a 

567 @path b 

568 @file c/d.py 

569 

570 The @file node creates the file a/b/c/d.py 

571 

572 Within @path and @<file> paths, {{exp}} gets evaluated with the following 

573 predefined symbols: c, g, p, os and sys. For example:: 

574 

575 @file {{os.path.abspath(os.curdir)}}/abc.py 

576 

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 

589 

590 s = ''' 

591 

592 About Debugging Commands 

593 ------------------------ 

594 

595 Alt-0 (vr-toggle) hides this help message. 

596 

597 The following commands are useful for debugging:: 

598 

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. 

607 

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 

620 

621 s = ''' 

622 

623 About Drag and Drop 

624 =================== 

625 

626 Nodes 

627 ----- 

628 

629 You may drag nodes from within a Leo outline or between Leo outlines, 

630 including nodes from separately running copies of Leo. 

631 

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. 

634 

635 Files 

636 ----- 

637 

638 You may also drag one or more files from a file folder over a headline. 

639 

640 For text files, Leo will create @auto, @edit or @file nodes as appropriate. 

641 

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:: 

645 

646 From <name of .leo file> 

647 

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 

658 

659 s = ''' 

660 

661 About Dynamic Abbreviations 

662 --------------------------- 

663 

664 Alt-0 (vr-toggle) hides this help message. 

665 

666 .. Description taken from http://www.emacswiki.org/emacs/DynamicAbbreviations 

667 

668 A dynamic abbreviation (dabbrev) is like a normal abbreviation except: 

669 

670 - You do not have to define it(!) 

671 - You expand it with Alt-/ (dabbrev-expand) or Alt-Ctrl-/ (dabbrev-completion) 

672 

673 For example, suppose the text aLongIvarName appears anywhere in the 

674 outline. To type this name again type:: 

675 

676 aLong<Alt-/> 

677 

678 You will see a list of possible completions in the log pane. 

679 

680 Alt-Ctrl-/ (dabbrev-completion) inserts the longest prefix of all 

681 completions immediately. For instance, suppose the following appear in text:: 

682 

683 aVeryLongIvarName 

684 aVeryLongMethodName 

685 

686 Typing:: 

687 

688 aVery<Alt-Ctrl-/> 

689 

690 will immediately extend the typing to:: 

691 

692 aVeryLong 

693 

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 

704 

705 s = ''' 

706 

707 Finding & replacing text 

708 ------------------------ 

709 

710 Alt-0 (vr-toggle) hides this help message. 

711 

712 **Ctrl-F** (start-search) shows the Find pane 

713 and puts focus in the find box. 

714 

715 Enter the find text and the replacement text if desired:: 

716 

717 Tab switches focus from widget to widget. 

718 Return executes the find-next command. 

719 

720 When Leo selects the found text you can do:: 

721 

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 :-) 

728 

729 You can Leo's commands toggle check boxes and radio buttons. 

730 These commands are listed in the Search menu. 

731 

732 You can execute these commands (and see their key bindings) 

733 using the minibuffer:: 

734 

735 <Alt-X>tog<tab>f<tab> or 

736 <Alt-X>set<tab>f<tab> 

737 

738 Incremental searching 

739 --------------------- 

740 

741 Incremental search is done only from the minibuffer:: 

742 

743 Alt-I (isearch forward) 

744 Alt-R (isearch backward) 

745 BackSpace retracts the search 

746 All other characters extend the search 

747 

748 During an incremental search:: 

749 

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 

787 

788 s = '''\ 

789 

790 About the Minibuffer 

791 -------------------- 

792 

793 Alt-0 (vr-toggle) hides this help message. 

794 

795 The mini-buffer is intended to be like the Emacs buffer: 

796 

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. 

800 

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. 

803 

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. 

807 

808 keyboard-quit (default shortcut: Ctrl-g) Exits any minibuffer mode and puts 

809 the focus in the body pane. 

810 

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 

822 

823 # Using raw string is essential. 

824 

825 s = r''' 

826 

827 About regular expressions 

828 ------------------------- 

829 

830 Alt-0 (vr-toggle) hides this help message. 

831 

832 Python's regular expressions, http://docs.python.org/library/re.html, 

833 are valid in find patterns:: 

834 

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. 

882 

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 

893 

894 s = ''' 

895 

896 Summary of Leo Scripting 

897 ------------------------- 

898 

899 Overview 

900 ======== 

901 

902 Any Leo node may contain a Python script. 

903 

904 Ctrl-B (execute-script) executes the body text of the presently selected node. 

905 

906 execute-script creates the script using @others and section references: 

907 **you can create complex scripts from a node and its descendants.** 

908 

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: 

911 

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. 

916 

917 *Tip*: use Alt-1 (toggle-autocompleter) and Alt-2 (toggle-calltips) as aids to memory and to speed typing. 

918 

919 Predefined symbols 

920 ================== 

921 

922 The execute-script command predefines three variables:: 

923 

924 c: The commander of the present outline. 

925 g: The leo.core.leoGlobals module. 

926 p: The presently selected position, c.p. 

927 

928 Commands class 

929 ============== 

930 

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:: 

934 

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) 

939 

940 Here is a partial list of the **official ivars** of any commander c: 

941 

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. 

951 

952 VNode class 

953 =========== 

954 

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:: 

958 

959 v.b: v's body text. 

960 v.h: v's headline text. 

961 v.u: v.unknownAttributes, a persistent Python dictionary. 

962 

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. 

966 

967 Position class 

968 ============== 

969 

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. 

972 

973 Properties of the position class:: 

974 

975 p.b: same as p.v.b. 

976 p.h: same as p.v.h. 

977 p.u: same as p.v.u. 

978 

979 Getter methods of the position class:: 

980 

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() 

1011 

1012 Setter methods of the position class:: 

1013 

1014 p.setDirty() 

1015 p.setMarked() 

1016 

1017 Methods that operate on nodes:: 

1018 

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() 

1031 

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:: 

1035 

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) 

1048 

1049 Generators 

1050 ========== 

1051 

1052 The following Python generators return positions:: 

1053 

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() 

1063 

1064 The leo.core.leoGlobals module 

1065 ============================== 

1066 

1067 **g vars**:: 

1068 

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. 

1074 

1075 **g decorator**:: 

1076 

1077 @g.command(command-name) 

1078 

1079 **g functions** (the most interesting: there are many more in leoGlobals.py):: 

1080 

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) 

1098 

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 

1109 

1110 # Using raw string is essential. 

1111 

1112 s = r''' 

1113 

1114 About settings 

1115 --------------- 

1116 

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. 

1121 

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. 

1127 

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: 

1138 

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. 

1152 

1153 The outline retains the organization of all active settings files. 

1154 

1155 See #852: https://github.com/leo-editor/leo-editor/issues/852 

1156 """ 

1157 

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) 

1167 

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