<type>documentation</type>
<domain>intro</domain>
<id>tutorial-auto-editing</id>
<title>Tutorial: Auto-Editing</title>
<date>$Date: 2013-06-27 19:22:37 -0400 (Thu, 27 Jun 2013) $</date>
<product>pro+</product>

Let's revisit auto-editing, which was introduced before we tried out the debugger. So far
we've seen the editor auto-enter invocation arguments and closing parentheses. There are a
number of other auto-editing operations available as well:

**Applying Characters to a Selection**

If you select a range of text in the editor and press a quote, parenthesis, brace,
bracket, or ``#``, Wing applies that key stroke to the selection.

For example, try selecting a few lines of non-comment code and press ``#``. Wing will
comment out those lines using the comment style configured in the `Editor > Block Comment
Style <script:show_preferences_gui#prefname="gui.block-comment-style">`__ preference.
Pressing ``#`` a second time will remove the comment characters.

Also, selecting some text and pressing ``"`` (double quote) will surround it with double
quotes, or pressing ``(`` open parenthesis will surround it with parentheses. This also
works when typing single quotes, triple quotes, back ticks, brackets, and braces.

Similarly, selecting a string and pressing a different quote character will convert that
string to using the type of quote (either single or double quote). This also works if the
caret is just after the closing quote of a string, within the opening or closing
triple-quote, or one of the quotes is selected.

The ``:`` colon key can also be applied to a selection, in order to create a new
block with one or more selected lines.  The : is entered, the selected lines are
indented following the : and the caret is positioned so that the block type can
be entered.  If ``try`` is entered, the corresponding ``except`` is also auto-entered
and selected to make it easy to convert it to ``finally`` or enter the exception type.

These operations are on by default and may be disabled with the `Editor > Auto-editing >
Apply Quotes to Selection
<script:show_preferences_gui#prefname="edit.auto-edit-quotes">`__, `Editor > Auto-editing
> Apply Comment Key to Selection
<script:show_preferences_gui#prefname="edit.auto-edit-comment">`__, `Editor > Auto-editing
> Apply [], (), and {} to Selection
<script:show_preferences_gui#prefname="edit.auto-edit-parens">`__, and `Editor >
Auto-editing > Apply Colon to Selection
<script:show_preferences_gui#prefname="edit.auto-edit-colon-creates-block">`__
preferences.

**Auto-Entering Spacing**

Wing can also auto-enter spaces as you type code, optionally enforcing `PEP 8
<https://www.python.org/dev/peps/pep-0008/>`__ style spacing. This auto-editing operation
is off by default but can be turned on with the `Editor > Auto-Editing > Auto-Enter Spaces
<script:show_preferences_gui#prefname="edit.auto-edit-spaces">`__ preference. Try turning
this on now and slowly typing the following into an editor:

.. python::

    import os
    if os.environ['TEST'] == 'X' * 3:
        pass
        
Notice that Wing is auto-entering a space after the ``]``, ``=``, and other characters
according to the context in the code. If you press the space anyway, it is ignored.

If you also enable the `Editor > Auto-Editing > Enforce PEP 8 Style Spacing
<script:show_preferences_gui#prefname="edit.auto-edit-spaces-enforce">`__ preference, Wing
will try to enforce `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`__ style spacing as
you type. For example, typing the following disallows extra spaces around ``=``:

.. python::

    x = 'test'

According to PEP 8, spaces should not be used in argument lists. This is also the default
behavior for Wing, whether or not PEP 8 enforcement is on. To override this, enable the
`Editor > Auto-Editing > Spaces Around = in Argument Lists
<script:show_preferences_gui#prefname="edit.auto-edit-spaces-args">`__ preference.

Similarly, enforcement of spacing around ``:`` in type annotations can be enabled
or disabled with the `Editor > Auto-Editing > Spaces Around : in Type Annotations
<script:show_preferences_gui#prefname="edit.auto-edit-spaces-types">`__ preference.

**Managing Blocks with the Colon Key**

This operation automatically sets up new blocks and allows reindenting existing code under
a newly added block. Try this now by typing the following into an editor:

.. python::

  if x == 1:
  
Notice that Wing auto-inserts a new line and indentation as soon as the colon is entered,
so the contents of the block can be typed right away.

Now try typing the following before ``text = None`` on line 38 of ``example1.py``, inside
``ReadPythonNews``:

.. python::

  if force:
  
The first time you press ``:`` Wing shows a status message "Press : again to create a new block".
This is done because it doesn't know if you are trying to type ``if force :=`` or just ``if
force:``. If you press ``:`` a second time, a new line and indent are added as before. 

Next, without moving the caret, press ``:`` again. Wing will move the first following line ``txt =
None`` under the new block so it looks like this:

.. image:: colon1.png
  :width: 407
  :height: 154

Again without moving the caret press ``:`` a fourth time. Wing moves the entire following
block, up until the next blank line or first line indented less than the current one, so
it looks like this:

.. image:: colon2.png
  :width: 420
  :height: 154
  
If you know you're never going to use ``:=`` assignments and don't use type hints in block starts
then you can enable the `Editor > Auto-Editing > Prefer Block Management Over := and Type Hints
<script:show_preferences_gui#prefname="edit.auto-edit-colon-prioritize-blocks">`__ preference and
Wing will immediately introduce a new block after you press ``:`` even in contexts where ``:=`` or a
type hint would be valid.

**Line Continuations**

If you press ``Enter`` inside a comment or a string inside ``()`` and there is text after
the caret, Wing auto-continues the line, placing the necessary comment or quote
characters. For example, pressing ``Enter`` after the word ``code`` on the first line of
``example1.py`` results in the following:

.. image:: continuation.png
  :width: 612
  :height: 88

This is on by default and can be disabled with the `Editor > Auto-Completion > Continue
Comment or String on New Line
<script:show_preferences_gui#prefname="edit.auto-edit-continue">`__ preference.

**Correcting Out-of-Order Typing**

Wing also tries to correct out-of-order typing. For example, type the following in an
editor::

  def y(:)
  
Wing figures out that the colon is misplaced and auto-corrects this to read:

.. python::

  def y():
  
Similarly, if you type the following::

  y()x

Wing figures out that a ``.`` is probably missing and auto-corrects this to read:

.. python::

  y().x
  
By relying on this, it is possible to save key strokes for caret movement when coding.

This auto-editing operation is on by default and can be disabled with the `Editor >
Auto-Completion > Correct Out-of-Order Typing
<script:show_preferences_gui#prefname="edit.auto-edit-fixups">`__ preference.

See the `Auto-editing <ref:edit/auto-editing>`__ documentation page for details.

