The indent module

This module provides Indenter to indent a Document.

To use the Indenter: instantiate one and call its indent() method with a Cursor describing the text range to indent. For example:

>>> from parce import Document, Cursor
>>> from parce.indent import Indenter
>>> from parce.lang.css import Css
>>> i = Indenter()
>>> i.indent_string = "    " # use four spaces by default
>>> d = Document(Css.root, "h1 {\ncolor: red;\n     }\n")
>>> c = Cursor(d).select_all()
>>> i.indent(c)
>>> d.text()
'h1 {\n    color: red;\n}\n'

Indenter uses per-language Indent classes which define the indenting behaviour. You can add them manually to Indenter, but it can also find Indent classes automatically by looking in the language’s module and finding there an Indent subclass with the same name, with “Indent” appended.

To further adapt the indenting behaviour, you can implement the indent_events() method of the Indenter. Or the Indent.indent_events() method of the language-specific indenter.

The following events can be yielded (simply module constants):

BLANK:

this is a blank line, the current indent level is not changed.

CURRENT_INDENT, string:

the current indent string this line has.

INDENT

next line should be indented a level.

NO_INDENT:

the indent of this line may not be changed at all, e.g. because it is part of a multiline string.

DEDENT:

next line should be dedented a level. (If this event occurs before INDENT or NO_DEDENT, the current line can be dedented.)

NO_DEDENT:

further DEDENT events will not dedent the current line anymore, but rather affect the indentation of the next line.

PREFER_INDENT, string:

use this indent for the current line, but do not change the indent level or the current indent for the next line.

NO_STRIP:

trailing whitespace should not be stripped off this line.

ALIGN, string:

The last INDENT event should use the specified string for alignment instead of the default indent (relatively to the start of the text in the current line excluding the current indent).

class IndentInfo(block)

Bases: object

Contains information about how to indent a block.

Created by AbstractIndenter.indent_info() and used within AbstractIndenter.indent().

block

the Block

indents

the indent events (None or string)

dedents_start

the number of dedents at the start of the line

dedents_end

the number of dedents later in the line

indent

the current indent

prefer_indent

a preferred, special case indent

property allow_indent

Whether the indent of this line may be changed.

property allow_strip

Whether trailing whitespace may be stripped of this line.

property is_blank

class AbstractIndenter

Bases: object

Indents (part of) a Document.

The indenting preferences can be set using some instance attributes.

indent_string = '  '

the string to indent each level with, defaulting to two spaces.

indent_blank_lines = True

whether to also indent blank lines

indent(cursor)

Indent all the lines in the cursor’s range.

This method scans the document always from the beginning, although it doesn’t change lines before the start of the cursor’s range. To re-indent a full document, select all text in the cursor (i.e. pos is 0, end is None).

auto_indent(cursor)

Adjust the indent of the single block at the Cursor’s pos.

increase_indent(cursor)

Increase the indent in the Cursor’s lines.

decrease_indent(cursor)

Decrease the indent in the Cursor’s lines.

strip_trailing_blanks(cursor, chars=None)

Strip trailing blanks off the selected lines.

Lines that don’t allow changing the indent are skipped. The chars argument is passed on to the Python strip() method.

indent_info(block, prev_indents=())

Return an IndentInfo object for the specified block.

indent_events(block, prev_indents=())

Implement this method to yield indenting events for the block.

class Indenter

Bases: AbstractIndenter

Indenter that uses Language-specific indenters if available.

This can only be used on documents that have TreeDocument mixed in, i.e. have a tree available.

indent_name_template = '{}Indent'

This format string creates the name to look for when searching a suitable Indent class in a Language module space (see find_indent()).

New in version 0.28.0.

indent_events(block, prev_indents=())

Implemented to use Indent subclasses for the specified language.

get_indent(language)

Return a Indent class instance for the specified language.

add_indent(language, indent)

Add a Indent instance for the specified language.

find_indent(language)

If no Indent was added, try to find a predefined one.

This is done by looking for a Indent subclass in the language’s module, with the same name as the language with “Indent” appended. So for a language class named “Css”, this method tries to find a Indent in the same module with the name “CssIndent”.

If no Indent is found for the language, the language’s base classes are also tried.

class Indent

Bases: object

The base class for language-specific indenters.

events(block, tokens, prev_indents)

Implement this to yield indent events for the tokens.