I like your decisive summary! On Tuesday, June 2, 2015 at 11:41:41 AM UTC-4, Edward K. Ream wrote: > > As of Rev ac94cab, there are no known serious bugs in the beautifier > commands. > > As previously discussed > <https://groups.google.com/forum/#!topic/leo-editor/TWy8e3d1cxc>, the > beautifier will *just work* for most people. The only setting is @bool > tidy-keep-blank-lines = False. > > This post completes the documentation for Leo's beautify commands, paying > close attention to details. > > *Commands* > > beautify-node: beautifies Python code in a single node. > beautify-tree: beautifies Python code a node and its descendants. > beautify-c: beautifies C code in a node and its descendants. > > These commands skip any nodes for which @language python (or c) is not in > effect. > > The *Python beautifiers* (beautify-tree and beautify-node) are *safe*. > They can never alter the meaning of a program because they compare the > parse trees of the original and beautified code. The code remains unchanged > if there is a mismatch. Such *beautifier errors* produce debugging dumps. > Please report any such errors to me. > > The Python beautifiers work only on syntactically correct code. They > issue a warning and do nothing for syntactically incorrect code. > > The Python beautifies convert *Leonine syntax* (directives, section > references and @doc parts) to comments, possibly with a trailing "pass" > statement. Usually this produces syntactically correct text. As discussed > below, the trailing "pass" can create SyntaxError's. > > *Directives* > > @beautify: enables beautification in a node. > @nobeautify: disables beautification in a node. > > These directives apply to a node and its descendants, until overridden > later in a descendants. > > Both these directives may appear in the same node. Such *ambiguous > directives *do not affect the beautification of descendant nodes. If > both directives appear in a node, the *first *directive determines > whether the node will be beautified. So: > > @beautify > ... > @nobeautify > > beautifies the *entire *node. Otoh, > > @nobeautify > ... > @beautify > > > skips beautification of the *entire *node. Yes, this is less precise than > one could imagine, but it's good enough for now. > > Note: The beautify-c command ignores these directives. > > *Rough edges* > > The following 5 problems are relatively minor. They apply only to the > Python beautifiers. The workaround in most cases is to use @nobeautify. > > *1. Syntax Errors* > > The *pass hack* converts: > > if 1: > << a section >> > > to: > > if 1: > #!!!!! << a section >> > pass > > which is usually, but not always, syntactically correct Python. Here is an > example from Leo's core: > > patterns = [ > << Sherlock patterns for pylint >> > ] > > The pass hack produces syntactically incorrect code: > > patterns = [ > #!!!!! << Sherlock patterns for pylint >> > pass > ] > > *2. Alignment* > > The beautifier eliminates blanks used to align code. For example: > > d = { > key1: value1, > longKey2: value2, > } > > The beautifier might preserve such lines, but there are no plans at > present to do so. > > The regular expression: =([ ])*\{([^}])*$ will discover complex > dictionaries that you may want to protect with @nobeautify. > > *3. Operator priority* > > Pep 8 suggests *considering *eliminating blanks around higher-priority > operators. The beautifier puts blank lines about *all *operators, except > unary operators. > > This is a difficult problem of style, for which no approach works in all > cases. Surprisingly, *retaining *blanks around '*' usually looks best in > Leo's own code. > > *4. @clean & @auto* > > Consider adding @nobeautify for all @auto/@clean nodes, on the theory > that such nodes are not primarily your responsibility. But adding > @nobeautify is completely up to you. > > *5. Extra blank lines* > > The beautifier will sometimes insert extra spaces between class/def lines > and preceding comments. The workaround is to move such comments into the > class or def, including the docstring. This is a minor issue, so it can > usually be ignored. > > *Stand-alone version* > > You may invoke the Python beautifier from the command line. The > stand-alone version of the beautifier is *lightly tested*. > > You can run leoBeautify.py from any directory, provided that a copy of > leoGlobals.py exists in the same directory. > > Run the stand-alone beautifier as follows: > > python -m leoBeautify file1, file2, ... > > To get a usage message, do: > > python -m leoBeautify -h > > This produces: > > Usage: python leoBeautify -m file1, file2, ... > > Options: > -h, --help show this help message and exit > -d, --debug print the list of files and exit > -k, --keep-blank-lines keep-blank-lines > > *Enough is enough* > > This project happened because PythonTidy doesn't work with Python 3 and > autopep8 is too slow, so in some sense it was necessary. And discovering > the new code generator pattern was hugely satisfying. However, it's time > for a break. Please don't ask me to do more now. > > The following could be done only at the cost of more settings and debates > about what the default settings should be. > > - Splitting long lines. > - Improve spacing around operators. > - Moving or indenting comment lines. > > All these involve significant personal judgements and preferences. Pep 8 > *explicitly > allows* various approaches. > > *Maybe* > > On a relatively slow machine, beautify-tree beautifies all files in > LeoPy.leo in 17.4 seconds. I am dithering about adding a setting that > would beautify files automatically when saving an outline. Naturally, > @beautify and @nobeautify would be handled as usual. > > *Summary* > > - For the first time ever, Leo's beautify commands work properly with > Leonine syntax. > - All files in leoPy.leo can now be beautified without fuss. > - Except for spacing around operators, the beautifier mostly leaves > your code *as it is*. > - The beautifier makes no difficult choices. It *will honor your > choices*. > - No further improvements are planned. You are unlikely to convince > me to do more. > > All comments welcome. > > Edward >
-- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
