Rule Selection
--------------

This section will detail the guidelines followed for creating and organizing rules.

.. jcl - fill this section out with some more text

.. NOTE:: VSG can not fully classify a VHDL file, this will place limitations on the ability to write rules.

Goals
=====

The VHDL Language Reference Manual (LRM) will be the basis used when determining rule creation, naming and the organization of rules.


Guidelines
==========

* [naming_001] Rule naming shall be of the form :code:`{identifier}_{number}`.
* [naming_002] The identifier shall be the *left-hand side* of VHDL production.
* [naming_003] The number shall be three digits.
* [naming_004] The rule number shall indicate which phase the rule is executed.
* [naming_005] An identifier and number pair shall never be re-used.

* [scoping_001] Rules shall be scoped to a VHDL production

Example
=======

The following production shows the structure of an architecture.

.. code-block:: text

   architecture_body ::=
       *architecture* identifier *of* entity_name *is*
           architecture_declarative_part
       *begin*
           architecture_statement_part
       *end* [ *architecture* ] [ architecture_simple_name ] ;

The VHDL keywords are enclosed with asterisks, :code:`architecture`, :code:`of`, :code:`is`, :code:`begin` and :code:`end`.
Everything else is another production:

.. code-block:: text

   identifier ::=
       basic_identifier | extended_identifier

   name ::=
       simple_name
     | operator_symbol
     | character_literal
     | selected_name
     | indexed_name
     | slice_name
     | attribute_name
     | external_name

   architecture_declarative_part ::=
       { block_declarative_item }

   architecture_statement_part ::=
       { concurrent_statement }




Rules targeting the :code:`architecture_body` will only include those elements at that level of the production.

For example:

* architecture_body_100 = **architecture** on it's own line
* architecture_body_101 = identifier on same line as **architecture**
* architecture_body_102 = **of** on same line as identifier
* architecture_body_103 = entity_name on same line as **of** keyword
* architecture_body_104 = **is** on same line as entity_name


* architecture_body_105 = no code after **is** keyword
* architecture_body_106 = **begin** on it's own line
* architecture_body_107 = no code after **begin** keyword
* architecture_body_108 = **end** on it's own line
* architecture_body_109 = **architecture** on same line as **end**
* architecture_body_110 = architecture_simple_name on same line as **end**
* architecture_body_111 = semicolon on same line as **end**
* architecture_body_112 = no code after semicolon
* architecture_body_120 = add/remove optional keyword **architecture**
* architecture_body_121 = add/remove optional architecture_simple_name

* architecture_body_200 = whitespace between **architecture** and identifier
* architecture_body_201 = whitespace between identifier and **of** keyword
* architecture_body_202 = whitespace between **of** and entity_name
* architecture_body_203 = whitespace between entity_name and **is** keyword
* architecture_body_204 = whitespace between **end** and **architecture** keyword
* architecture_body_205 = whitespace between **architecture** and architecture_simple_name
* architecture_body_206 = whitespace between architecture_simple_name and semicolon

* architecture_body_400 = indent of **architecture** keyword
* architecture_body_401 = indent of **begin** keyword
* architecture_body_402 = indent of **end** keyword

* architecture_body_600 = case of **architecture** keyword
* architecture_body_601 = case of identifier
* architecture_body_602 = case of **of** keyword
* architecture_body_603 = case of entity_name
* architecture_body_604 = case of **is** keyword
* architecture_body_605 = case of **begin** keyword
* architecture_body_606 = case of **end** keyword
* architecture_body_607 = case of ending **architecture** keyword
* architecture_body_608 = case of architecture_simple_name

* architecture_body_700 = naming restrictions on identifier and architecture_simple_name

One question to answer are blank lines.
Are they part of :code:`architecture_body` or the next production?

Expanding the :code:`architecture_declarative_part` production shows:

.. code-block:: text

   block_declarative_item ::=
       subprogram_declaration
     | subprogram_body
     | subprogram_instantiation_declaration
     | package_declaration
     | package_body
     | package_instantiation_declaration
     | type_declaration
     | subtype_declaration
     | constant_declaration
     | signal_declaration
     | shared_variable_declaration
     | file_declaration
     | alias_declaration
     | component_declaration
     | attribute_declaration
     | attribute_specification
     | configuration_specification
     | disconnection_specification
     | use_clause
     | group_template_declaration
     | group_declaration
     | PSL_Property_Declaration
     | PSL_Sequence_Declaration
     | PSL_Clock_Declaration

Vertical spacing between these elements will be performed by rules in the :code:`block_declarative_part` group.
This will eliminate the issue where multiple blank line rules could collide.

* block_declarative_part_300 = blank line at beginning of block_declarative part
* block_declarative_part_301 = blank line at end of block_declarative part
* block_declarative_part_302 = blank line before block_declarative_item (could be configurable) (could also conflict with block_declarative_item_001)
* etc...

The block_declarative_part can include from 0 to N block_declarative_items.
Alignment rules between block_declarative_items, e.g. colon alignment in signal_declaration and constant_declaration, will also be performed at this level.

* block_declarative_part_500 = align identifiers in file, constant and signal declarations
* block_declarative_part_501 = align : in constant and signal declarations
* etc...

Other structural rules could be created:

* block_declarative_part_100 = all constants defined at top of block_declarative_part (maybe this is out of scope of VSG though)

Taking the next step down to the signal_declaration level:

.. code-block:: text

   signal_declaration ::=
       signal identifier_list : subtype_indication [ signal_kind ] [ := expression ] ;

The following rules would be generated:

* signal_declaration_100 = **signal** keyword on it's own line
* signal_declaration_101 = identifier_list on same line as **signal** keyword
* signal_declaration_102 = colon on same line as identifier_list
* signal_declaration_103 = subtype_indication on same line as colon
* signal_declaration_104 = signal_kind on same line as subtype_indication
* signal_declaration_105 = := on same line as signal_kind
* signal_declaration_106 = expression on same line as :=
* signal_declaration_107 = semicolon on same line as expression
* signal_declaration_108 = no code after semicolon

* signal_declaration_200 = whitespace between signal keyword and identifier_list
* signal_declaration_200 = whitespace between identifier_list and colon
* signal_declaration_200 = whitespace between colon and subtype_indication
* signal_declaration_200 = whitespace between subtype_indication and signal_kind
* signal_declaration_200 = whitespace between signal_kind and :=
* signal_declaration_200 = whitespace between := and expression

* signal_declaration_400 = indent of signal keyword

* signal_declaration_600 = case of signal keyword
* signal_declaration_601 = case of identifiers in identifier_list

* signal_declaration_700 = naming restrictions on signal identifiers

One could argue rule 601 should be moved to an identifier_list set of rules, but it seems appropriate at this level.

.. code-block:: text

   identifier_list ::=
       identifier { , identifier }

I would make the argument that signal_kind case would be done by a signal_kind rule.

.. code-block:: text

   signal_kind ::=
       register | bus

One could make the argument that subtype_indication should be handled by it's own set of rules:

.. code-block:: text

   subtype_indication ::=
       [ resolution_indication ] type_mark [ constraint ]

   resolution_indication ::=
       resolution_function_name | ( element_resolution )

   element_resolution ::= array_element_resolution | record_resolution

   type_mark ::=
       type_name | subtype_name

And the same for constraint:

.. code-block:: text

   constraint ::=
       range_constraint
     | array_constraint
     | record_constraint

If the subtype_indication and constraint rules were moved out of signal_declaration, and where ever else they are location, that it would reduce the number of rules.
VSG currently uses a base rule to handle constraints, which is extended where constraints are used.
