.. _Indentation:

Indentation
===========

-  **Tabs and Spaces** - Lines are indented using tabs or spaces depending on the preferences configured in :menuselection:`Window --> Preferences --> General --> Editors --> Text Editors`: 
    -  If the **Insert spaces for tabs** (org.eclipse.ui.editors/spacesForTabs) option is enabled, indentation will use space characters, otherwise tabs will be used. 
    -  The **Displayed tab width** (org.eclipse.ui.editors/tabWidth) option controls the size of a tab in spaces.
  
- **Auto-detect indentation** - Controls whether DVT will automatically detect the indentation style of the file opened in the editor. It can be configured from :menuselection:`Window --> Preferences --> DVT --> Editors`.

.. note::
    When the **Auto-detect indentation** (ro.amiq.dvt/format.indent.auto_detect) preference is enabled, the detected values will be displayed in the Inspect View and will have a higher priority over the **Insert spaces for tabs** and **Displayed tab width** settings when the formatter is invoked. You can also trigger a new detection from the Inspect View.

.. figure:: ../../images/sv_eclipse_file_indent_inspect_view.png
	:align: center


- **Optional "begin"** (ro.amiq.vlogdt/format.indent.begin) - Some language constructs, for example the conditional statement *if* or the loop statement *for*, require a *begin - end* block to control the execution of several statements. Such blocks are called **optional "begin"** in order to distinguish them from other cases like *fork begin ... end endfork** or plain *begin ... end* blocks used just for grouping several statements together for readability. This option affects the **optional "begin"** blocks:
    - **Leave as is** (1)
    - **On a new line** (2)- *begin* is moved on a new line
    - **On the same line** (3)- *begin* is moved on the same line with its construct
    - **On a new line and indent** (4) - *begin* is moved on a new line and indented

.. list-table:: 

	* - **Initial code**
	  - **Leave as is** (1)
	  - **On a new line** (2)
	  - **On the same line** (3)
	  - **On a new line and indent** (4)
	* - .. figure:: ../../images/common/optional-begin-same-line.png
	  - .. figure:: ../../images/common/optional-begin-same-line.png
	  - .. figure:: ../../images/common/optional-begin-new-line.png
	  - .. figure:: ../../images/common/optional-begin-same-line.png
	  - .. figure:: ../../images/common/optional-begin-new-line-and-indent.png

- **"else"** (ro.amiq.vlogdt/format.indent.else) - This option affects *else* placement:
    - **Leave as is** (1)
    - **On a new line** (2) - *else* is moved on a new line
    - **On the same line** (3) - if *end* precedes it *else* is moved on the same line with *end*

.. list-table::

	* - **Initial code**
	  - **Leave as is** (1)
	  - **On a new line** (2)
	  - **On the same line** (3)
	* - .. figure:: ../../images/common/else-same-line.png
	  - .. figure:: ../../images/common/else-same-line.png
	  - .. figure:: ../../images/common/else-new-line.png
	  - .. figure:: ../../images/common/else-same-line.png

- **Parameters** (ro.amiq.vlogdt/format.indent.params) - This option affects module ports and parameters, function and task arguments, class parameters:
    - **Leave as is** (1)
    - **One per line (open parenthesis on the same line)** (2) - Each parameter/argument is placed on its own line and the open parentheses is placed on the same line with the parameter/argument receiver
    - **One per line (open parenthesis on the next line)** (3) - Each parameter/argument is placed on its own line and the open parentheses is placed on the next line after the parameter/argument receiver
    - **More per line if less than** (ro.amiq.vlogdt/format.indent.more_per_line_if_less_than_enable) - It controls whether to place parameters on the same line when their number does not exceed a specified value. This option is available only when the *Parameters* preference is set to *One per line (open parenthesis on the same line)* or *One per line (open parenthesis on the next line)*.
    - **More per line** (4) - More parameters are placed on the same line

.. note::
  
  When more parameters get to be placed on a single line and line wrapping is enabled, the parameters may be moved to separate lines as needed to fit within the specified line width.

.. list-table::

  * - **Initial code**
    - **Leave as is** (1)
    - **More per line** (4)
  * - .. figure:: ../../images/common/parameters-more-per-line.png
    - .. figure:: ../../images/common/parameters-more-per-line.png
    - .. figure:: ../../images/common/parameters-more-per-line.png

.. list-table::

  * - **Initial code**
    - **One per line (open parenthesis on the next line)** (3)
    - **One per line (open parenthesis on the next line)** (3) and **More per line if less than** set to **"3"**
    - **One per line (open parenthesis on the next line)** (3) and **More per line if less than** set to **"1"**
  * - .. figure:: ../../images/common/parameters-more-per-line.png
    - .. figure:: ../../images/common/parameters-one-per-line-open-parenthesis-on-the-next-line.png
    - .. figure:: ../../images/common/parameters-open-paren-next-line-more-per-line-if-less-than-within-limit.png
    - .. figure:: ../../images/common/parameters-one-per-line-open-parenthesis-on-the-next-line.png

- **Preprocessing** (ro.amiq.vlogdt/format.indent.preproc) - This option affects preprocessing directives:
    - **Leave as is** (1)
    - **Indent** (2) - Indent the preprocessing directives according to the enclosing scope.\`ifdef blocks don't increase the enclosed statements indentation.
    - **Indent and increase indentation level** (3) - Indent the preprocessing directives according to the enclosing scope.\`ifdef blocks increase indentation of its enclosed statements like any other *scope* language construct.
    - **Indent and increase indentation level except first** (5) -  Indent the preprocessing directives according to the enclosing scope.`ifdef blocks increase the enclosed code indentation with the exception of the first level preprocessing block.
    - **Move at first column** (4) - Move the preprocessing directives at line start.\`ifdef blocks don't increase the enclosed statements indentation.

.. list-table::

	* - **Initial code**
	  - **Leave as is** (1)
	  - **Indent** (2)
	  - **Indent and increase indentation level** (3)
	  - **Indent and increase indentation level - except first** (5)
	  - **Move at first column** (4)
	* - .. figure:: ../../images/common/preprocessing-move-at-first-column.png
	  - .. figure:: ../../images/common/preprocessing-move-at-first-column.png
	  - .. figure:: ../../images/common/preprocessing-indent.png
	  - .. figure:: ../../images/common/preprocessing-indent-and-increase-indentation-level.png
	  - .. figure:: ../../images/common/preprocessing-indent-and-increase-indentation-level-except-first.png
	  - .. figure:: ../../images/common/preprocessing-move-at-first-column.png

- **Don't indent single line comments at first column** (ro.amiq.vlogdt/format.indent.preserve_sl_comment_column_zero) - This option affects single line comments that start at column zero. It is useful to disable the indentation for whole regions of code that are *block commented*, for example by using :kbd:`Ctrl+/`. When enabled, single line comments that start at column zero are not indented.

.. list-table::

	* - **Before**
	  - **After**
	* - .. figure:: ../../images/common/before-and-after-do-not-indent-single-line-comments.png
	  - .. figure:: ../../images/common/before-and-after-do-not-indent-single-line-comments.png

- **Indent multi-line comments** (ro.amiq.vlogdt/format.indent.multiline_comments) - This option affects multi-line comments (*\/\* ... \*\/*). When enabled, multi-line comments are indented.

.. list-table::
	
  * - **Before**
    - **After**
  * - .. figure:: ../../images/common/before-indent-multiline-comments.png
    - .. figure:: ../../images/common/after-indent-multiline-comments.png

- **Do not indent multi-line content of assigns** (ro.amiq.vlogdt/format.indent.skip_assigns) - When enabled, the assign lines are not indented such as to preserve an alignment.

.. list-table::

	* - **Before**
	  - **After**
	* - .. figure:: ../../images/common/before-indent-multiline-assigns.png
	  - .. figure:: ../../images/common/after-indent-multiline-assigns.png

- **Do not indent multi-line macro definitions** (ro.amiq.vlogdt/format.indent.skip.ml.macro.definitions) - When enabled, multi-line macro definitions are not indented such as to preserve an alignment. This option is available only when the *Preprocessing* preference is set to *Indent*, *Indent and increase indentation level*, *Indent and increase indentation level except first* or *Move at first column*.

.. list-table::

	* - **Before**
	  - **After**
	* - .. figure:: ../../images/common/before-indent-multiline-macro-definitions.png
	  - .. figure:: ../../images/common/after-indent-multiline-macro-definitions.png

- **Add New Line After Begin And Before End** (ro.amiq.vlogdt/format.indent.add_new_line_after_begin_and_before_end) - Controls whether to add a new line after `begin` and before `end`.

.. list-table::

	* - **Before**
	  - **After**
	* - .. figure:: ../../images/common/before-add-new-line-after-begin-and-before-end.png
	  - .. figure:: ../../images/common/after-add-new-line-after-begin-and-before-end.png

- **Add New Line After End** (ro.amiq.vlogdt/format.indent.add_new_line_after_end) - Controls whether to add a new line after `end`.

.. list-table::

	* - **Before**
	  - **After**
	* - .. figure:: ../../images/common/before-add-new-line-after-end.png
	  - .. figure:: ../../images/common/after-add-new-line-after-end.png

- **Ignore lines starting with** (ro.amiq.vlogdt/format.indent.ignore_lines) - Space separated list of line prefixes. A line starting with one of the prefixes is completely ignored, that is it is not indented, nor it contributes to indentation.

.. list-table::

	* - **Before**
	  - **After**
	* - .. figure:: ../../images/common/before-and-after-ignore-lines-starting-with.png
	  - .. figure:: ../../images/common/before-and-after-ignore-lines-starting-with.png

- **Don't increase the indent Level On** (ro.amiq.vlogdt/format.indent.no_indent_keywords) - By default all *scope* language constructs increase indentation. This option allows you to control which language constructs should increase indentation.

.. list-table::

	* - **Before**
	  - **After ("assert" keyword)**
	* - .. figure:: ../../images/common/before-no-indent-keywords.png
	  - .. figure:: ../../images/common/after-no-indent-keywords.png

- **Implicit semi macros** (ro.amiq.vlogdt/format.indent.implicit_semi_macros) - The code formatting engine depends on detecting some delimiters for properly identifying the proper indentation scope, for example indentation should not increase after *if(a) foo1();*, but it should after *if(a) begin foo();*. Semicolon or *end* is such a delimiter and sometimes it may be encapsulated inside a macro. This option allows you to explicitly list such macros for proper code formatting.

.. list-table::

	* - **Before**
	  - **After**
	* - .. figure:: ../../images/common/before-implicit-semi-macros.png
	  - .. figure:: ../../images/common/after-implicit-semi-macros.png

- **Open scope macros** (ro.amiq.vlogdt/format.indent.open_scope_macros) and **Close scope macros** (/ro.amiq.vlogdt/format.indent.close_scope_macros) - An *open scope macro* increases the indentation level of subsequent code to visualize scoping. A *close scope macro* decreases back the indentation level. Open/close scope macros are paired, for example: *`TEST* and *`ENDTEST*, similar with language keywords like *function* and *endfunction*.

.. list-table::
	
  * - **Before**
    - **After**
  * - .. figure:: ../../images/common/before-close-scope-macros.png
    - .. figure:: ../../images/common/after-close-scope-macros.png

