Listing Extension

The listing extension provides a mechanism for creating source code listings. The system allows for the inclusion of local content as well as complete or partial snippets of the desired source code and includes the ability to parse MOOSE input files and separate out blocks. The main purpose is to avoid copying code or input syntax into the documentation to avoid out-of-date content.

The extension provides the !listing command (see Command Extension), which allows for numbered captions to be applied, the Float Extension provides additional details. The following table list the available configure options for the extension.

Key	Default	Description
active	True	Toggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime.
prefix	Listing	The caption prefix (e.g., Fig.).
modal-link	True	Insert modal links with complete files.

The !listing command has the capability to include text from local content and arbitrary files (such as source code). files. There is a wide range of settings that are available to specialize how the code is imported. The complete list of available of settings are provided in Table 2 and the sections below provide various examples of using some of these settings.

Local Listing Content

It is possible to create a listing using local content. This is done by using the !listing command without any arguments with the desired content following the command, see Command Extension for details to how content is defined. The available settings for this command are given in Table 1.

Example 1: Example listing with content from local markdown.

Markdown
HTML

!listing id=local caption=A function for adding 42. language=cpp
double add_forty_two(const double y);
y += 42;
return y;

Table 1: Settings available when creating a listing from local content.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
caption	None	The caption text for the float object.
prefix	None	The numbered caption label to include prior to the caption text.
max-height	350px	The default height for listing content.
language	None	The language to use for highlighting, if not supplied it will be inferred from the extension (if possible).

File Content

You can include complete files from the repository. For example, the following creates the code listing in Example 2.

Table 2: Settings available when capturing text from a file with the listing command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
caption	None	The caption text for the float object.
prefix	None	The numbered caption label to include prior to the caption text.
max-height	350px	The default height for listing content.
language	None	The language to use for highlighting, if not supplied it will be inferred from the extension (if possible).
diff	None	Path to a file to diff against
before_link_prefix	-	Prefix for the modal link to the diffed "before" file
after_link_prefix	+	Prefix for the modal link to the diffed "after" file
link	True	Show the complete file via a link; overridden by SourceExtension
prepend	None	Text to include prior to each line of the included text.
append		Text to include after each line of the included text.
header	None	Text to include prior to the included text.
header-newlines	1	The number of newlines after the header.
footer		Text to include after the included text.
footer-newlines	1	The number of newlines before the footer.
indent	0	The level of indenting to apply to the included text.
strip-header	True	When True the MOOSE header is removed for display.
fix-moose-header	True	In C/h files within MOOSE the '//*' is used for the header at the top. This breaks the highlighting, this option removes these and replaces them with '//'.
strip-extra-newlines	True	Removes extraneous new lines from the text.
strip-leading-whitespace	False	When True leading white-space is removed from the included text.
line	None	A portion of text that unique identifies a single line to include.
re	None	Extract content via a regex, if the 'content' group exists it is used as the desired content; if 'remove' group exists it is extracted; otherwise group 0 is used for the content.
re-flags	re.M\|re.S\|re.U	Python re flags.
start	None	A portion of text that unique identifies the starting location for including text, if not provided the beginning of the file is utilized.
end	None	A portion of text that unique identifies the ending location for including text, if not provided the end of the file is used. By default this line is not included in the display.
include-start	True	When False the text captured by the 'start' setting is excluded in the displayed text.
include-end	False	When True the text captured by the 'end' setting is included in the displayed text.
replace	None	List of replacement string pairs: ['foo','bar', 'boom','baam'] replaces 'foo' with 'bar' and 'boom' with 'baam'.

Example 2: Example for showing a complete file.

Markdown
HTML

!listing framework/src/kernels/Diffusion.C

Regular Expression Match

Regular expressions can be utilized to extract specific content from files. Example 3 uses a regular expression to extract the content of a class method.

Example 3: Example listing using the "re" setting.

Markdown
HTML

!listing framework/src/kernels/Diffusion.C
         re=Real\sDiffusion::computeQpResidual.*?^}

Single Line Match

It is possible to show a single line of a file by including a snippet that allows the line to be located within the file. If multiple matches occur only the first match will be shown. For example, the call to addClassDescription can be shown by adding the following.

Example 4: Example for displaying a single line from a file.

Markdown
HTML

!listing framework/src/kernels/Diffusion.C line=computeQp

Range Line Match

Code starting and ending on lines containing a string is also possible by using the 'start' and 'end' options. If 'start' is omitted then the snippet will start at the beginning of the file. Similarly, if 'end' is omitted the snippet will include the remainder of the file content.

Example 5: Example listing using the "start" and "end" settings.

Markdown
HTML

!listing moose/test/tests/kernels/simple_diffusion/simple_diffusion.i
         start=Kernels
         end=Executioner

Input File Content

Like C++ files, MOOSE input files also have additional capability, mainly the "block" and "remove" settings (see Table 3 for a complete list). The included content will be limited to the input block matching the supplied name. Notice that the supplied name may be approximate; however, if it is not unique only the first match will appear. Similarly, input file blocks may be removed from the displayed content. In addition to block names, the "remove" setting also accepts the names of individual input parameters. However, the full path to the parameter must be specified. Example 6 demonstrates proper use of the block and remove syntax.

Example 6: Example use of "block" and "remove" settings for input files.

Markdown
HTML

!listing moose/test/tests/kernels/simple_diffusion/simple_diffusion.i
         block=Kernels
         id=input-block
         caption=Code listing of [MOOSE] input file block.

!listing moose/test/tests/kernels/simple_diffusion/simple_diffusion.i
         remove=left Executioner/petsc_options_iname Executioner/petsc_options_value
         id=input-remove
         caption=Code listing of a [MOOSE] input file with blocks and parameters removed.

note:The "block" and "remove" settings apply to all HIT formatted files.

The settings given in Table 3 are available to all HIT formatted listings, including test specification files.

Table 3: Settings available for input file listings.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
caption	None	The caption text for the float object.
prefix	None	The numbered caption label to include prior to the caption text.
max-height	350px	The default height for listing content.
language	None	The language to use for highlighting, if not supplied it will be inferred from the extension (if possible).
diff	None	Path to a file to diff against
before_link_prefix	-	Prefix for the modal link to the diffed "before" file
after_link_prefix	+	Prefix for the modal link to the diffed "after" file
link	True	Show the complete file via a link; overridden by SourceExtension
prepend	None	Text to include prior to each line of the included text.
append		Text to include after each line of the included text.
header	None	Text to include prior to the included text.
header-newlines	1	The number of newlines after the header.
footer		Text to include after the included text.
footer-newlines	1	The number of newlines before the footer.
indent	0	The level of indenting to apply to the included text.
strip-header	True	When True the MOOSE header is removed for display.
fix-moose-header	True	In C/h files within MOOSE the '//*' is used for the header at the top. This breaks the highlighting, this option removes these and replaces them with '//'.
strip-extra-newlines	True	Removes extraneous new lines from the text.
strip-leading-whitespace	False	When True leading white-space is removed from the included text.
line	None	A portion of text that unique identifies a single line to include.
re	None	Extract content via a regex, if the 'content' group exists it is used as the desired content; if 'remove' group exists it is extracted; otherwise group 0 is used for the content.
re-flags	re.M\|re.S\|re.U	Python re flags.
start	None	A portion of text that unique identifies the starting location for including text, if not provided the beginning of the file is utilized.
end	None	A portion of text that unique identifies the ending location for including text, if not provided the end of the file is used. By default this line is not included in the display.
include-start	True	When False the text captured by the 'start' setting is excluded in the displayed text.
include-end	False	When True the text captured by the 'end' setting is included in the displayed text.
replace	None	List of replacement string pairs: ['foo','bar', 'boom','baam'] replaces 'foo' with 'bar' and 'boom' with 'baam'.
block	None	Space separated list of input file block names to include.
remove	None	Space separated list of input file block and/or parameter names to remove. The full path to parameters must be used, e.g., `Kernels/diffusion/variable`.

Diffing Content

You can produce a diffed listing between two files using the "diff" setting.

Example 7: Example listing using the "diff" setting.

Markdown
HTML

!listing framework/src/kernels/Diffusion.C
         diff=framework/src/kernels/ADDiffusion.C

The prefixes for the links after the listing (when using the "link" option, which defaults to true) can be modified using the "before_link_prefix" and "after_link_prefix" settings.

Example 8: Example listing using the "diff" setting with overridden link prefixes.

Markdown
HTML

!listing framework/src/kernels/Diffusion.C
         diff=framework/src/kernels/ADDiffusion.C
         before_link_prefix=Diffusion without AD:
         after_link_prefix=Diffusion with AD:

(contrib/moose/framework/src/kernels/Diffusion.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

InputParameters
Diffusion::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

(contrib/moose/framework/src/kernels/Diffusion.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

InputParameters
Diffusion::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

(contrib/moose/framework/src/kernels/Diffusion.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

InputParameters
Diffusion::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

(contrib/moose/test/tests/kernels/simple_diffusion/simple_diffusion.i)

[Mesh]
  type = GeneratedMesh
  dim = 2
  nx = 10
  ny = 10
[]

[Variables]
  [u]
  []
[]

[Kernels]
  [diff]
    type = Diffusion
    variable = u
  []
[]

[BCs]
  [left]
    type = DirichletBC
    variable = u
    boundary = left
    value = 0
  []
  [right]
    type = DirichletBC
    variable = u
    boundary = right
    value = 1
  []
[]

[Executioner]
  type = Steady
  solve_type = 'PJFNK'
  petsc_options_iname = '-pc_type'
  petsc_options_value = 'hypre'
[]

[Outputs]
  exodus = true
[]

(contrib/moose/test/tests/kernels/simple_diffusion/simple_diffusion.i)

[Mesh]
  type = GeneratedMesh
  dim = 2
  nx = 10
  ny = 10
[]

[Variables]
  [u]
  []
[]

[Kernels]
  [diff]
    type = Diffusion
    variable = u
  []
[]

[BCs]
  [left]
    type = DirichletBC
    variable = u
    boundary = left
    value = 0
  []
  [right]
    type = DirichletBC
    variable = u
    boundary = right
    value = 1
  []
[]

[Executioner]
  type = Steady
  solve_type = 'PJFNK'
  petsc_options_iname = '-pc_type'
  petsc_options_value = 'hypre'
[]

[Outputs]
  exodus = true
[]

(contrib/moose/test/tests/kernels/simple_diffusion/simple_diffusion.i)

[Mesh]
  type = GeneratedMesh
  dim = 2
  nx = 10
  ny = 10
[]

[Variables]
  [u]
  []
[]

[Kernels]
  [diff]
    type = Diffusion
    variable = u
  []
[]

[BCs]
  [left]
    type = DirichletBC
    variable = u
    boundary = left
    value = 0
  []
  [right]
    type = DirichletBC
    variable = u
    boundary = right
    value = 1
  []
[]

[Executioner]
  type = Steady
  solve_type = 'PJFNK'
  petsc_options_iname = '-pc_type'
  petsc_options_value = 'hypre'
[]

[Outputs]
  exodus = true
[]

(contrib/moose/framework/src/kernels/ADDiffusion.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "ADDiffusion.h"

registerMooseObject("MooseApp", ADDiffusion);

InputParameters
ADDiffusion::validParams()
{
  auto params = ADKernelGrad::validParams();
  params.addClassDescription("Same as `Diffusion` in terms of physics/residual, but the Jacobian "
                             "is computed using forward automatic differentiation");
  return params;
}

ADDiffusion::ADDiffusion(const InputParameters & parameters) : ADKernelGrad(parameters) {}

ADRealVectorValue
ADDiffusion::precomputeQpResidual()
{
  return _grad_u[_qp];
}

(contrib/moose/framework/src/kernels/Diffusion.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

InputParameters
Diffusion::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

(contrib/moose/framework/src/kernels/ADDiffusion.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "ADDiffusion.h"

registerMooseObject("MooseApp", ADDiffusion);

InputParameters
ADDiffusion::validParams()
{
  auto params = ADKernelGrad::validParams();
  params.addClassDescription("Same as `Diffusion` in terms of physics/residual, but the Jacobian "
                             "is computed using forward automatic differentiation");
  return params;
}

ADDiffusion::ADDiffusion(const InputParameters & parameters) : ADKernelGrad(parameters) {}

ADRealVectorValue
ADDiffusion::precomputeQpResidual()
{
  return _grad_u[_qp];
}

(contrib/moose/framework/src/kernels/Diffusion.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

InputParameters
Diffusion::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

Local Listing Content
File Content
Input File Content
Diffing Content