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.
