This is an old version, view current version.

34.4 Automatic updating and formatting of Stan programs

In addition to compiling Stan programs, stanc3 features several flags which can be used to format Stan programs and update them to the most recent Stan syntax by removing any deprecation features which can be automatically replaced.

These flags work for both .stan model files and .stanfunctions function files. They can be combined with --o to redirect the formatted output to a new file.

34.4.1 Automatic formatting

Invoking stanc --auto-format <model_file> will print a version of your model which has been re-formatted. The goal is to have this automatic formatting stay as close as possible to the Stan Program Style Guide. This means spacing, indentation, and line length are all regularized. Some deprecated features, like the use of # for line comments, are replaced, but the goal is mainly to preserve the program while formatting it.

By default, this will try to split lines at or before column 78. This number can be changed using --max-line-length.

34.4.2 Canonicalizing

In addition to automatic formatting, stanc can also “canonicalize” programs by updating deprecated syntax, removing unnecessary parenthesis, and adding braces around bodies of if statements and for and while loops.

This can be done by using stanc --auto-format --canonicalize=... where ... is a comma-separated list of options. Currently these options are:

• deprecations

  Removes deprecated syntax such as replacing <- with =, replacing the deprecated _log suffix, replacing deprecated functions with their drop-in replacements, and replacing get_lp() with target() and increment_log_prob(...) with target += ....

• parentheses

  Removes unnecessary extra parentheses, such as converting y = ((x-1)) to y = x - 1

• braces

  Places braces around all blocks. For example, the following statement

  if (cond)
    //result

  will be formatted as

  if (cond) {
    //result
  }

  and similarly for both kinds of loops containing a single statement.

• includes

  This will pretty-print code from other files included with #include as part of the program. This was the default behavior prior to Stan 2.29. When not enabled, the pretty-printer output will include the same #include directives as the input program.

Invoking stanc --print-canonical <model_file> is synonymous with running stanc --auto-format --canonicalize=deprecations,braces,parentheses,includes

34.4.3 Known issues

The formatting and canonicalizing features of stanc3 are still under development. The following are some known issues one should be aware of before using either:

• Oddly placed comments

  If your Stan program features comments in unexpected places, such as inside an expression, they may be moved in the process of formatting. Moved comments are prefixed with the string ^^^: to indicate they originally appeared higher in the program.

  We hope to improve this functionality in future versions. For now, this can usually be avoided by manually moving the comment outside of an expression, either by placing it on its own line or following a separator such as a comma or keyword.

• Failure to recreate strange #include structure

  Printing without include inlining (--canonicalize=includes) can fail when includes were used in atypical locations, such as in the middle of statements. We recommend either printing with inlining enabled or reconsidering the use of includes in this way.