verilog/tools/formatter/README.md - third_party/verible - Git at Google

 # SystemVerilog Formatter

 <!--*
 freshness: { owner: 'hzeller' reviewed: '2020-10-07' }
 *-->

 `verible-verilog-format` is the SystemVerilog formatter tool. You can can
 get a full set of avilable flags using the `--helpfull` flag.

 For automatic formatting suggestions on github pull requests, there is a
 [easy to integrate github action available][github-format-action].

 ## Usage

 ```
 usage: verible-verilog-format [options] <file> [<file...>]
 To pipe from stdin, use '-' as <file>.

   Flags from common/formatting/basic_format_style_init.cc:
     --column_limit (Target line length limit to stay under when formatting.);
       default: 100;
     --indentation_spaces (Each indentation level adds this many spaces.);
       default: 2;
     --line_break_penalty (Penalty added to solution for each introduced line
       break.); default: 2;
     --over_column_limit_penalty (For penalty minimization, this represents the
       baseline penalty value of exceeding the column limit. Additional penalty
       of 1 is incurred for each character over this limit); default: 100;
     --wrap_spaces (Each wrap level adds this many spaces. This applies when the
       first element after an open-group section is wrapped. Otherwise, the
       indentation level is set to the column position of the open-group
       operator.); default: 4;

   Flags from verilog/formatting/format_style_init.cc:
     --assignment_statement_alignment (Format various assignments:
       {align,flush-left,preserve,infer}); default: infer;
     --case_items_alignment (Format case items:
       {align,flush-left,preserve,infer}); default: infer;
     --class_member_variable_alignment (Format class member variables:
       {align,flush-left,preserve,infer}); default: infer;
     --compact_indexing_and_selections (Use compact binary expressions inside
       indexing / bit selection operators); default: true;
     --distribution_items_alignment (Aligh distribution items:
       {align,flush-left,preserve,infer}); default: infer;
     --enum_assignment_statement_alignment (Format assignments with enums:
       {align,flush-left,preserve,infer}); default: infer;
     --expand_coverpoints (If true, always expand coverpoints.); default: false;
     --formal_parameters_alignment (Format formal parameters:
       {align,flush-left,preserve,infer}); default: infer;
     --formal_parameters_indentation (Indent formal parameters: {indent,wrap});
       default: wrap;
     --module_net_variable_alignment (Format net/variable declarations:
       {align,flush-left,preserve,infer}); default: infer;
     --named_parameter_alignment (Format named actual parameters:
       {align,flush-left,preserve,infer}); default: infer;
     --named_parameter_indentation (Indent named parameter assignments:
       {indent,wrap}); default: wrap;
     --named_port_alignment (Format named port connections:
       {align,flush-left,preserve,infer}); default: infer;
     --named_port_indentation (Indent named port connections: {indent,wrap});
       default: wrap;
     --port_declarations_alignment (Format port declarations:
       {align,flush-left,preserve,infer}); default: infer;
     --port_declarations_indentation (Indent port declarations: {indent,wrap});
       default: wrap;
     --port_declarations_right_align_packed_dimensions (If true, packed
       dimensions in contexts with enabled alignment are aligned to the right.);
       default: false;
     --port_declarations_right_align_unpacked_dimensions (If true, unpacked
       dimensions in contexts with enabled alignment are aligned to the right.);
       default: false;
     --struct_union_members_alignment (Format struct/union members:
       {align,flush-left,preserve,infer}); default: infer;
     --try_wrap_long_lines (If true, let the formatter attempt to optimize line
       wrapping decisions where wrapping is needed, else leave them unformatted.
       This is a short-term measure to reduce risk-of-harm.); default: false;

   Flags from verilog/tools/formatter/verilog_format.cc:
     --failsafe_success (If true, always exit with 0 status, even if there were
       input errors or internal errors. In all error conditions, the original
       text is always preserved. This is useful in deploying services where
       fail-safe behaviors should be considered a success.); default: true;
     --inplace (If true, overwrite the input file on successful conditions.);
       default: false;
     --lines (Specific lines to format, 1-based, comma-separated, inclusive N-M
       ranges, N is short for N-N. By default, left unspecified, all lines are
       enabled for formatting. (repeatable, cumulative)); default: ;
     --max_search_states (Limits the number of search states explored during line
       wrap optimization.); default: 100000;
     --show_equally_optimal_wrappings (If true, print when multiple optimal
       solutions are found (stderr), but continue to operate normally.);
       default: false;
     --show_inter_token_info (If true, along with show_token_partition_tree,
       include inter-token information such as spacing and break penalties.);
       default: false;
     --show_largest_token_partitions (If > 0, print token partitioning and then
       exit without formatting output.); default: 0;
     --show_token_partition_tree (If true, print diagnostics after token
       partitioning and then exit without formatting output.); default: false;
     --stdin_name (When using '-' to read from stdin, this gives an alternate
       name for diagnostic purposes. Otherwise this is ignored.);
       default: "<stdin>";
     --verbose (Be more verbose.); default: false;
     --verify_convergence (If true, and not incrementally formatting with
       --lines, verify that re-formatting the formatted output yields no further
       changes, i.e. formatting is convergent.); default: true;
 ```

 ## Disabling Formatting {#disable-formatting}

 When you want to exempt a range of text from formatting, write:

 ```
 // verilog_format: off
 ... untouched code ...
 // verilog_format: on
 ```

 or

 ```
 /* verilog_format: off */
 ... untouched code ...
 /* verilog_format: on */
 ```

 As a good practice, include a reason why you choose to disable a section.

 ```
 // verilog_format: off  // my alignment is prettier than the tool's

 // verilog_format: off  // issue #N: working around.
 ```

 These directives take precedence over `--lines` specifications.

 ## Formatting included files

 For files that are included as snippets in other contexts, e.g. only statements,
 or only module body items, adding a
 [parsing mode directive](../../analysis#alternative-parsing-modes) (such as `//
 verilog_syntax: parse-as-module-body`) will let the formatter parse and format
 such files successfully.

 ## Interactive Formatting

 The formatter is ever a work-in-progress and may not always behave the way a
 user would like it to behave. If you wish to review changes introduced by the
 formatter and apply them interactively, we've provided a helper script (that is
 actually formatter-agnostic) for the job.

 ```
 verible-transform-interactive.sh -- verible-verilog-format -- files...
 ```

 This will run the formatter on the affected files without modifying them
 initially, and pass the `diff`-generated patch into a tool
 (`verible-patch-tool`) that interactively applies patch hunks.

 Answer the \[y/n\] prompts.

 The original files will be modified in-place with the elected changes.

 For convenience, one could create an alias like:

 ```
 alias verilog-format-interactive='verible-transform-interactive.sh -- verible-verilog-format --'
 ```

 ## Incremental Formatting

 If you wish to format only changed lines (a.k.a. incremental or partial
 formatting), the following tools are provided to assist.

 ### Git users

 `git-verible-verilog-format.sh` (installed along with `verible-verilog-format`)
 can be run from within any subdirectory of a Git project. It automatically
 detects new and changed lines, and generates the `--lines` flag for each
 modified file in your workspace.

 From `--help`:

 ```
 git-verible-verilog-format.sh:
 Performs incremental file formatting (verible-verilog-format) based on current diffs.
 New files explicitly git-add-ed by the user are wholly formatted.

 Actions:
   1) Runs 'git add -u' to stage currently modified files to the index.
      To format new files (wholly), 'git add' those before calling this script.
   2) Runs 'git diff -u --cached' to generate a unified diff.
   3) Diff is scanned to determine added or modified lines in each file.
   4) Invokes 'verible-verilog-format --inplace' on all touched or new Verilog files,
      but does not 'git add' so that the changes may be examined and tested.
      Formatting can be easily undone with:
        'git diff | git apply --reverse -'.

 usage: git-verible-verilog-format.sh [script options] [-- [verilog_format options]]
   (no positional arguments)
   Run from anywhere inside a git project tree.

 script options: (options with arguments can be: --flag=VALUE or --flag VALUE)
   --help | -h : print help and exit
   --verbose | -v : execute verbosely
   --dry-run : stop before running formatter, and print formatting commands
   --formatter TOOL : path to verilog_format binary
        [using: /usr/local/bin/verible-verilog-format]
   -- : stops option processing, and forwards remaining args as flags to the
        underlying --formatter tool.
 ```

 ## Incremental Interactive Formatting

 In your locally modified client (p4, git) run:

 ```shell
 verible-verilog-format-changed-lines-interactive.sh
 ```

 and follow the prompts.

 > NOTE: git and hg users can pass in a different base revision to diff against:
 >
 > ```shell
 > # Diff against the previous revision in hg
 > verible-verilog-format-changed-lines-interactive.sh --rev .^
 > # Diff against upstream mainline in git
 > verible-verilog-format-changed-lines-interactive.sh --rev origin/main
 > ```

 ## Aligned Formatting

 There are several sections of code that are eligible for aligned formatting. In
 each of these contexts, the user has some control over the alignment behavior.
 Without alignment, the default behavior is to flush-left, which respects
 indentation and minimum inter-token spacing constraints.

 Yet, alignment is not always desired. So how does the formatter know whether or
 not the user intended for alignment? It can only examine the original code and
 make some judgment.

 Consider the following example (module formal parameters):

 ```
 module m #(
   int W,
   type T
 );
   ...
 endmodule
 ```

 With alignment, this formats to:

 ```
 module m #(
   int  W,
   type T
 );
   ...
 endmodule
 ```

 When the spacing difference between between aligned and flushed-left formatting
 is "sufficiently small", the formatter will align because the small difference
 has low risk of compromising readability.

 In contrast, aligning the following example _could_ be considered less readable.

 original:

 ```systemverilog
 module m #(
   int  W,
   some_long_name T
 );
   ...
 endmodule
 ```

 aligned:

 ```systemverilog
 module m #(
   int            W,
   some_long_name T
 );
   ...
 endmodule
 ```

 To detect the above condition, the formatter examines the number of _excess_
 spaces (spacing errors) within an alignment group (original vs. flushed-left).
 If that value is lower than a threshold, the formatter infers that the author
 intended flush-left formatting.

 To induce alignment, the author needs to _inject_ four excess spaces _between_
 any two tokens in any row in the aligned section, not before first tokens (which
 fall under indentation, not alignment). In this example, spaces are deliberately
 injected before `W` (but after `W` would work too):

 ```systemverilog
 module m #(
   int      W,
   some_long_name T
 );
   ...
 endmodule
 ```

 formatted with alignment:

 ```
 module m #(
   int            W,
   some_long_name T
 );
   ...
 endmodule
 ```

 This also implies that previously aligned code will most likely remain aligned.

 Finally, if none of the above conditions hold, the formatter will leave the
 original code as-is, preserving all pre-existing spaces.

 ## Failsafe Behavior

 _A formatter must not corrupt data._

 On rare conditions, you may observe that the formatter leaves the original code
 untouched. You may have encountered a fail-safe condition, in which the
 formatter conservatively gives up to keep your code from being corrupted. This
 can happen for one of several reasons.

 ### Syntax Errors

 On failure to lex/parse, the formatter gives up because it doesn't have a syntax
 tree to work with.

 ### Internal Verification

 Before outputting the formatted result, several properties are checked:

 *   **Equivalence**: The output is lexically equivalent to the input, meaning
     that only whitespaces may have changed, but all other tokens are equal. For
     example, if two identifiers accidentally got merged together into one (by
     removing spaces between them), this check would fail. Lexical equivalence
     also implies that the output is still parseable.
 *   **Convergence**: Re-formatting the _output_ results in no further changes.
     This property is particularly important when the formatter is used to
     _check_ that a file is formatted properly. Without convergence, such a check
     would fail after formatting, potentially asking the user to run formatting
     two or more times. Note that this requirement is stricter than _eventual
     convergence_, which allows multiple iterations before reaching a
     fixed-point.

 ### Internal Limits

 If an optimization such as line-wrapping optimization fails to complete within
 time resource limits, then the formatter also gives up to avoid hanging.

 ### Fatal Error

 If the formatter crashes for any other reason, it will leave the original file
 intact. The formatter does not attempt to open any file for writing in-place
 until all formatting calculations have been done and internal verifications
 pass.

 [github-format-action]: https://github.com/chipsalliance/verible-formatter-action
	# SystemVerilog Formatter

	<!--*
	freshness: { owner: 'hzeller' reviewed: '2020-10-07' }
	*-->

	`verible-verilog-format` is the SystemVerilog formatter tool. You can can
	get a full set of avilable flags using the `--helpfull` flag.

	For automatic formatting suggestions on github pull requests, there is a
	[easy to integrate github action available][github-format-action].

	## Usage

	```
	usage: verible-verilog-format [options] <file> [<file...>]
	To pipe from stdin, use '-' as <file>.

	Flags from common/formatting/basic_format_style_init.cc:
	--column_limit (Target line length limit to stay under when formatting.);
	default: 100;
	--indentation_spaces (Each indentation level adds this many spaces.);
	default: 2;
	--line_break_penalty (Penalty added to solution for each introduced line
	break.); default: 2;
	--over_column_limit_penalty (For penalty minimization, this represents the
	baseline penalty value of exceeding the column limit. Additional penalty
	of 1 is incurred for each character over this limit); default: 100;
	--wrap_spaces (Each wrap level adds this many spaces. This applies when the
	first element after an open-group section is wrapped. Otherwise, the
	indentation level is set to the column position of the open-group
	operator.); default: 4;

	Flags from verilog/formatting/format_style_init.cc:
	--assignment_statement_alignment (Format various assignments:
	{align,flush-left,preserve,infer}); default: infer;
	--case_items_alignment (Format case items:
	{align,flush-left,preserve,infer}); default: infer;
	--class_member_variable_alignment (Format class member variables:
	{align,flush-left,preserve,infer}); default: infer;
	--compact_indexing_and_selections (Use compact binary expressions inside
	indexing / bit selection operators); default: true;
	--distribution_items_alignment (Aligh distribution items:
	{align,flush-left,preserve,infer}); default: infer;
	--enum_assignment_statement_alignment (Format assignments with enums:
	{align,flush-left,preserve,infer}); default: infer;
	--expand_coverpoints (If true, always expand coverpoints.); default: false;
	--formal_parameters_alignment (Format formal parameters:
	{align,flush-left,preserve,infer}); default: infer;
	--formal_parameters_indentation (Indent formal parameters: {indent,wrap});
	default: wrap;
	--module_net_variable_alignment (Format net/variable declarations:
	{align,flush-left,preserve,infer}); default: infer;
	--named_parameter_alignment (Format named actual parameters:
	{align,flush-left,preserve,infer}); default: infer;
	--named_parameter_indentation (Indent named parameter assignments:
	{indent,wrap}); default: wrap;
	--named_port_alignment (Format named port connections:
	{align,flush-left,preserve,infer}); default: infer;
	--named_port_indentation (Indent named port connections: {indent,wrap});
	default: wrap;
	--port_declarations_alignment (Format port declarations:
	{align,flush-left,preserve,infer}); default: infer;
	--port_declarations_indentation (Indent port declarations: {indent,wrap});
	default: wrap;
	--port_declarations_right_align_packed_dimensions (If true, packed
	dimensions in contexts with enabled alignment are aligned to the right.);
	default: false;
	--port_declarations_right_align_unpacked_dimensions (If true, unpacked
	dimensions in contexts with enabled alignment are aligned to the right.);
	default: false;
	--struct_union_members_alignment (Format struct/union members:
	{align,flush-left,preserve,infer}); default: infer;
	--try_wrap_long_lines (If true, let the formatter attempt to optimize line
	wrapping decisions where wrapping is needed, else leave them unformatted.
	This is a short-term measure to reduce risk-of-harm.); default: false;

	Flags from verilog/tools/formatter/verilog_format.cc:
	--failsafe_success (If true, always exit with 0 status, even if there were
	input errors or internal errors. In all error conditions, the original
	text is always preserved. This is useful in deploying services where
	fail-safe behaviors should be considered a success.); default: true;
	--inplace (If true, overwrite the input file on successful conditions.);
	default: false;
	--lines (Specific lines to format, 1-based, comma-separated, inclusive N-M
	ranges, N is short for N-N. By default, left unspecified, all lines are
	enabled for formatting. (repeatable, cumulative)); default: ;
	--max_search_states (Limits the number of search states explored during line
	wrap optimization.); default: 100000;
	--show_equally_optimal_wrappings (If true, print when multiple optimal
	solutions are found (stderr), but continue to operate normally.);
	default: false;
	--show_inter_token_info (If true, along with show_token_partition_tree,
	include inter-token information such as spacing and break penalties.);
	default: false;
	--show_largest_token_partitions (If > 0, print token partitioning and then
	exit without formatting output.); default: 0;
	--show_token_partition_tree (If true, print diagnostics after token
	partitioning and then exit without formatting output.); default: false;
	--stdin_name (When using '-' to read from stdin, this gives an alternate
	name for diagnostic purposes. Otherwise this is ignored.);
	default: "<stdin>";
	--verbose (Be more verbose.); default: false;
	--verify_convergence (If true, and not incrementally formatting with
	--lines, verify that re-formatting the formatted output yields no further
	changes, i.e. formatting is convergent.); default: true;
	```

	## Disabling Formatting {#disable-formatting}

	When you want to exempt a range of text from formatting, write:

	```
	// verilog_format: off
	... untouched code ...
	// verilog_format: on
	```

	or

	```
	/* verilog_format: off */
	... untouched code ...
	/* verilog_format: on */
	```

	As a good practice, include a reason why you choose to disable a section.

	```
	// verilog_format: off // my alignment is prettier than the tool's

	// verilog_format: off // issue #N: working around.
	```

	These directives take precedence over `--lines` specifications.

	## Formatting included files

	For files that are included as snippets in other contexts, e.g. only statements,
	or only module body items, adding a
	[parsing mode directive](../../analysis#alternative-parsing-modes) (such as `//
	verilog_syntax: parse-as-module-body`) will let the formatter parse and format
	such files successfully.

	## Interactive Formatting

	The formatter is ever a work-in-progress and may not always behave the way a
	user would like it to behave. If you wish to review changes introduced by the
	formatter and apply them interactively, we've provided a helper script (that is
	actually formatter-agnostic) for the job.

	```
	verible-transform-interactive.sh -- verible-verilog-format -- files...
	```

	This will run the formatter on the affected files without modifying them
	initially, and pass the `diff`-generated patch into a tool
	(`verible-patch-tool`) that interactively applies patch hunks.

	Answer the \[y/n\] prompts.

	The original files will be modified in-place with the elected changes.

	For convenience, one could create an alias like:

	```
	alias verilog-format-interactive='verible-transform-interactive.sh -- verible-verilog-format --'
	```

	## Incremental Formatting

	If you wish to format only changed lines (a.k.a. incremental or partial
	formatting), the following tools are provided to assist.

	### Git users

	`git-verible-verilog-format.sh` (installed along with `verible-verilog-format`)
	can be run from within any subdirectory of a Git project. It automatically
	detects new and changed lines, and generates the `--lines` flag for each
	modified file in your workspace.

	From `--help`:

	```
	git-verible-verilog-format.sh:
	Performs incremental file formatting (verible-verilog-format) based on current diffs.
	New files explicitly git-add-ed by the user are wholly formatted.

	Actions:
	1) Runs 'git add -u' to stage currently modified files to the index.
	To format new files (wholly), 'git add' those before calling this script.
	2) Runs 'git diff -u --cached' to generate a unified diff.
	3) Diff is scanned to determine added or modified lines in each file.
	4) Invokes 'verible-verilog-format --inplace' on all touched or new Verilog files,
	but does not 'git add' so that the changes may be examined and tested.
	Formatting can be easily undone with:
	'git diff \| git apply --reverse -'.

	usage: git-verible-verilog-format.sh [script options] [-- [verilog_format options]]
	(no positional arguments)
	Run from anywhere inside a git project tree.

	script options: (options with arguments can be: --flag=VALUE or --flag VALUE)
	--help \| -h : print help and exit
	--verbose \| -v : execute verbosely
	--dry-run : stop before running formatter, and print formatting commands
	--formatter TOOL : path to verilog_format binary
	[using: /usr/local/bin/verible-verilog-format]
	-- : stops option processing, and forwards remaining args as flags to the
	underlying --formatter tool.
	```

	## Incremental Interactive Formatting

	In your locally modified client (p4, git) run:

	```shell
	verible-verilog-format-changed-lines-interactive.sh
	```

	and follow the prompts.

	> NOTE: git and hg users can pass in a different base revision to diff against:
	>
	> ```shell
	> # Diff against the previous revision in hg
	> verible-verilog-format-changed-lines-interactive.sh --rev .^
	> # Diff against upstream mainline in git
	> verible-verilog-format-changed-lines-interactive.sh --rev origin/main
	> ```

	## Aligned Formatting

	There are several sections of code that are eligible for aligned formatting. In
	each of these contexts, the user has some control over the alignment behavior.
	Without alignment, the default behavior is to flush-left, which respects
	indentation and minimum inter-token spacing constraints.

	Yet, alignment is not always desired. So how does the formatter know whether or
	not the user intended for alignment? It can only examine the original code and
	make some judgment.

	Consider the following example (module formal parameters):

	```
	module m #(
	int W,
	type T
	);
	...
	endmodule
	```

	With alignment, this formats to:

	```
	module m #(
	int W,
	type T
	);
	...
	endmodule
	```

	When the spacing difference between between aligned and flushed-left formatting
	is "sufficiently small", the formatter will align because the small difference
	has low risk of compromising readability.

	In contrast, aligning the following example _could_ be considered less readable.

	original:

	```systemverilog
	module m #(
	int W,
	some_long_name T
	);
	...
	endmodule
	```

	aligned:

	```systemverilog
	module m #(
	int W,
	some_long_name T
	);
	...
	endmodule
	```

	To detect the above condition, the formatter examines the number of _excess_
	spaces (spacing errors) within an alignment group (original vs. flushed-left).
	If that value is lower than a threshold, the formatter infers that the author
	intended flush-left formatting.

	To induce alignment, the author needs to _inject_ four excess spaces _between_
	any two tokens in any row in the aligned section, not before first tokens (which
	fall under indentation, not alignment). In this example, spaces are deliberately
	injected before `W` (but after `W` would work too):

	```systemverilog
	module m #(
	int W,
	some_long_name T
	);
	...
	endmodule
	```

	formatted with alignment:

	```
	module m #(
	int W,
	some_long_name T
	);
	...
	endmodule
	```

	This also implies that previously aligned code will most likely remain aligned.

	Finally, if none of the above conditions hold, the formatter will leave the
	original code as-is, preserving all pre-existing spaces.

	## Failsafe Behavior

	_A formatter must not corrupt data._

	On rare conditions, you may observe that the formatter leaves the original code
	untouched. You may have encountered a fail-safe condition, in which the
	formatter conservatively gives up to keep your code from being corrupted. This
	can happen for one of several reasons.

	### Syntax Errors

	On failure to lex/parse, the formatter gives up because it doesn't have a syntax
	tree to work with.

	### Internal Verification

	Before outputting the formatted result, several properties are checked:

	* Equivalence: The output is lexically equivalent to the input, meaning
	that only whitespaces may have changed, but all other tokens are equal. For
	example, if two identifiers accidentally got merged together into one (by
	removing spaces between them), this check would fail. Lexical equivalence
	also implies that the output is still parseable.
	* Convergence: Re-formatting the _output_ results in no further changes.
	This property is particularly important when the formatter is used to
	_check_ that a file is formatted properly. Without convergence, such a check
	would fail after formatting, potentially asking the user to run formatting
	two or more times. Note that this requirement is stricter than _eventual
	convergence_, which allows multiple iterations before reaching a
	fixed-point.

	### Internal Limits

	If an optimization such as line-wrapping optimization fails to complete within
	time resource limits, then the formatter also gives up to avoid hanging.

	### Fatal Error

	If the formatter crashes for any other reason, it will leave the original file
	intact. The formatter does not attempt to open any file for writing in-place
	until all formatting calculations have been done and internal verifications
	pass.

	[github-format-action]: https://github.com/chipsalliance/verible-formatter-action