Add tests and update design doc (idaholab#17989)

framework/doc/content/source/parser/Parser.md

@@ -1,14 +1,15 @@
 # Parser
 
-The MOOSE Parser object is responsible for interacting with the HIT input file parser
-and constructing the necessary [Actions](Action.md) that ultimately execute to build
-up the objects which compose a complete MOOSE based simulation. It is important to note
-that +this+ object is not responsible for the raw file-base I/O. The underlying
-structure of the MOOSE input file is dictated by HIT and information on the format
-can be found [here](/application_usage/input_syntax.md optional=True). The parser abstraction expects
-information to be organized into a hierarchy of blocks with zero or more children
-at each level. All of the name/value pairs at each level are used to construct
-one or more complete objects.
+The MOOSE Parser object is responsible for interacting with the HIT input file
+parser and constructing the necessary [Actions](Action.md) that ultimately
+execute to build up the objects which compose a complete MOOSE based simulation.
+It is important to note that +this+ object is not responsible for the raw
+file-base I/O. The underlying structure of the MOOSE input file is dictated by
+HIT and information on the format can be found
+[here](/application_usage/input_syntax.md optional=True). The parser abstraction
+expects information to be organized into a hierarchy of blocks with zero or more
+children at each level. All of the name/value pairs at each level are used to
+construct one or more complete objects.
 
 ## Associating parser blocks
 
@@ -30,4 +31,12 @@ See [Brace Expressions](input_syntax.md optional=True)
 The Parser supports the ability to selectively activate or deactivate individual blocks
 without the use of block comment characters through the use of the special "active" and
 "inactive" parameter blocks. Either of these parameters (but not both) can be added
-to any block (including the top level) to selectively turn individual blocks on/off.
+to any block (including the top level) to selectively turn individual blocks on/off.
+
+## Multiple inputs
+
+When multiple inputs are supplied to a MOOSE application, the parser will read
+them in successively and add merge them into a single block hierarchy. Later
+inputs add to and override parameters to previous inputs. This permits the user
+to factor out common parts of a set of inputs and reuse them in multiple
+simulations.

test/tests/parser/multiple_inputs/diffusion1a.i

@@ -0,0 +1,24 @@
+[Mesh]
+  type = GeneratedMesh
+  dim = 2
+  nx = 10
+  ny = 10
+[]
+
+[BCs]
+  [left]
+    type = DirichletBC
+    variable = u
+    boundary = left
+    value = 0
+  []
+[]
+
+[Executioner]
+  type = Steady
+  solve_type = 'PJFNK'
+[]
+
+[Outputs]
+  exodus = true
+[]

test/tests/parser/multiple_inputs/diffusion1b.i

@@ -0,0 +1,5 @@
+[BCs]
+  [right]
+    value = 2
+  []
+[]

test/tests/parser/multiple_inputs/diffusion1c.i

@@ -0,0 +1,25 @@
+[Variables]
+  [u]
+  []
+[]
+
+[Kernels]
+  [diff]
+    type = Diffusion
+    variable = u
+  []
+[]
+
+[BCs]
+  [right]
+    type = DirichletBC
+    variable = u
+    boundary = right
+    value = 1
+  []
+[]
+
+[Executioner]
+  petsc_options_iname = '-pc_type -pc_hypre_type'
+  petsc_options_value = 'hypre boomeramg'
+[]

test/tests/parser/multiple_inputs/diffusion1d.i

@@ -0,0 +1,5 @@
+[BCs]
+  [right]
+    invalid_param = 'invalid_value'
+  []
+[]

test/tests/parser/multiple_inputs/gold/diffusion1a_out.e

@@ -0,0 +1 @@
+../../../kernels/simple_diffusion/gold/simple_diffusion_out.e

test/tests/parser/multiple_inputs/tests

@@ -0,0 +1,26 @@
+[Tests]
+  design = 'Parser.md'
+  issues = '#17989'
+  requirement = 'The system shall support for multiple input files, which are merged into one input specification for a simulation'
+
+  [./two_inputs]
+    type = 'Exodiff'
+    input = 'diffusion1a.i diffusion1c.i'
+    exodiff = 'diffusion1a_out.e'
+    detail = 'where no parameters overlap'
+  [../]
+
+  [./three_inputs_override]
+    type = 'Exodiff'
+    input = 'diffusion1a.i diffusion1b.i diffusion1c.i'
+    exodiff = 'diffusion1a_out.e'
+    detail = 'where input files may override parameters in previous inputs'
+  [../]
+
+  [./three_inputs_error]
+    type = 'RunException'
+    input = 'diffusion1a.i diffusion1c.i diffusion1d.i'
+    expect_err = 'moose/test/tests/parser/multiple_inputs/diffusion1d.i:3: unused parameter \'BCs/right/invalid_param\''
+    detail = 'while locating input errors in the correct file'
+  [../]
+[]