<type>documentation</type>
<domain>edit</domain>
<id>auto-editing</id>
<title>Auto-Editing</title>
<date>$Date: 2011-05-04 11:47:03 -0400 (Wed, 04 May 2011) $</date>
<version>$Revision: 24521 $</version>
<product>pro+</product>

Wing Pro's auto-editing operations help to reduce the amount of typing needed to write
code by auto-entering text or making corrections as you type. The following operations are
available and may be enabled or disabled in the `Auto-editing
<script:show_preferences_gui(prefname="edit.auto-edit-enabled")>`__ preferences group:

**Auto-Close Characters** enters matching closing quotes, parentheses, brackets, braces,
and comment characters. When this is enabled Wing also (1) skips over existing closing
characters if they are typed anyway, and (2) auto-enters opening parentheses, brackets, and
braces when an unmatched closing character is typed in Python code.

This operation is disabled selectively when working within strings, comments, and in other
contexts where the auto-edit is more likely to interfere than assist. For example, quotes
are only auto-closed at the end of a line or clause, most auto-closing is disabled within
single-quoted strings, auto-closing is disabled if there is a matching unclosed character,
auto-closing parentheses is disabled before a symbol, and some operations are omitted
while auto-entering invocation arguments.

**Auto-Enter Invocation Args** enters the default arguments for a function or method
invocation.  ``Tab`` or ``Comma`` can be used to move among the arguments. Argument entry
ends when moving past the last argument, or pressing ``')'`` at the last argument. Unaltered
default arguments are automatically removed when argument entry ends. When this is
enabled, the following options are available:
  
  **Auto-wrap Arguments** automatically re-wraps all the arguments to the configured
  `Reformatting Wrap Column <script:show_preferences_gui#prefname="edit.text-wrap-column">`__ 
  after auto-invocation ends.
    
  **Invoke After Completion** starts auto-invocation automatically after
  completion of a callable name.  If invocation is not wanted, such as when
  passing a function or method as an argument, you will need to press 
  ``Delete`` twice.
  
**Apply Quotes to Selection** surrounds a non-empty selection with quotes when the quote
character is typed.  Pressing quote repeatedly produces a triple-quoted string.

**Mutate Adjacent Quotes** changes the style of quotes around a string in Python code when a quote 
character is pressed while the editor caret is adjacent to an existing quote character 
(either single or double quote) or a whole string is selected.  This converts all the quotes
in triple-quoted string delimiters.

**Apply Comment Key to Selection** will comment or uncomment the currently selected lines,
using the style configured in the `Editor > Block Comment Style
<script:show_preferences_gui(prefname="gui.block-comment-style")>`__ preference. This
operation only works with single-key comment characters such as ``'#'``.  Otherwise,
use ``Toggle Block Comment`` in the ``Source`` menu.
  
**Apply (), [], and {} to Selection** surrounds the currently selected text when an open
parenthesis, bracket, or brace is typed.

**Apply Colon to Selection** creates a new block out of a range of selected lines and
places the caret for entry of the block type (``if``, ``try``, ``for``,
``with``, etc). When ``try`` is entered, Wing auto-enters the matching
``except`` block. In this case, ``except`` is selected so it can be changed into
``finally``. Pressing the ``Tab`` key moves into the ``except`` or ``finally`` block.

**Auto-Enter Spaces** adds spaces in Python code when typing operators or punctuation and
refuses to enter redundant spaces in contexts where spacing is being enforced. For some
cases, for example when typing ``==``, spacing will be adjusted differently after the
first and second keys are pressed. Some associated characters may also be entered, such as
``','`` after a dict item when ``':'`` is pressed. The following options are available:
  
  **Auto-Space After Keywords** auto-enters spaces after Python keyword names. No space
  is added when the keyword name matches a snippet in the auto-completer, so that 
  the auto-completer is not hidden and snippets can still be used.
    
  **Enforce PEP 8 Style Spacing** prevents use of auto-spacing that does not adhere to
  `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`__ style spacing.
  See `PEP 8 Auto-formatting <ref:edit/pep8>`__ for other PEP 8 formatting options.
  
  **Spaces Around = in Argument Lists** overrides PEP 8 conventions and places
  spaces around equals signs in argument lists.
  
  **Spaces Elsewhere in Argument Lists** enables auto-spacing also in all other places
  in argument lists.
  
  **Spaces After : in Type Annotations** auto-enters spaces after ``':'`` when 
  it is used in `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`__ and 
  `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`__ style type hints.
    
**Manage Blocks on Repeated Colon Key Presses** creates new blocks automatically when the
colon key is pressed. When the start of a new Python block is typed and ``':'`` is pressed,
this auto-indents the current line, adds ``EOL`` (end-of-line), and auto-indents the newly
created line.

Pressing ``':'`` a second time will remove the new line and instead indent the following 
existing line of code under the new block.

Pressing ``':'`` a third time will instead indent the next contiguous block of lines under
the new block, up to any blank line or line that belongs to an enclosing block.

In order to allow for adjustment of indentation before continuing, no ``EOL`` will be inserted
after ``else``, ``elif``, ``except``, and ``finally`` if the indentation position for that
statement is ambigious due to the presence of multiple matching starting blocks. In that
case, pressing ``':'`` repeatedly will toggle the indentation between the possible positions.

The following option is available to control how block management works:

  **Prefer Block Management Over := and Type Hints** causes Wing to immediately manage blocks when ``':'``
  is pressed even in contexts where a ``:=`` (Python 3.8+) or ``var:type`` type hint (Python 3.6+ )
  could be used.  When this is disabled, pressing ``':'`` a second time, after an existing colon, 
  triggers block management.
  
**Continue Comment or String on New Line** auto-enters comment or string delimiters when
``Enter`` is pressed within the text of an existing comment or a string. This operation
does not apply to triple-quoted strings.

**Correct Out-of-Order Typing** corrects common typos. For example, ``x(.)`` is replaced
with ``x().``, ``x(:)`` is replaced with ``x():``, and Wing will add ``'.'`` when it is
missing in ``x().d``.
