Flow123d  JB-rel-int-test-ea53151
input.h
Go to the documentation of this file.
1 /**
2  * @defgroup input_mod Input Classes
3  *
4  * \section classes Overview of data input classes
5  * We assume that the input data of the program can be represented by a tree.
6  * The leave nodes of the tree contain actual data and has one of the 'scalar' types
7  * represented by the classes in Input::Type namespace : Bool, Integer, Double, String,
8  * and FileName. The branching nodes of the input tree
9  * can be either of type Array or type Record (or Abstract).
10  * Classes derived from \p Input::Type::TypeBase only describes structure of the input tree
11  * which is independent of actual format of the input data.
12  * All nodes of tree allows definition of input attributes, which are optional for every node.
13  * Base attributes are defined in Input::Type::Attributes, special attributes of Flow123D in
14  * FlowAttributes. These structures contain common attributes, user can define other else.
15  *
16  * Instances of the classes from
17  * the Input::Type namespace form a \e declaration-tree that is later used
18  * by a reader of the particular file format (currently we support YAML and JSON through
19  * the Input::ReaderToStorage reader) to interpret the input data, check its structure, possibly use default values
20  * and put the raw data into an intermediate \e storage-tree formed be Input:Storage classes.
21  *
22  * Finally,
23  * the data are accessible through accessors Input::Record, Input::Array, and Input::AbstractRecord.
24  * These accessors holds pointers into declaration tree as well as into the data storage tree
25  * and provides unified access to the data.
26  *
27  * Furthermore, the \e declaration-tree can output itself provided a basic documentation of the
28  * input data structure, that is consistent with the actual state.
29  *
30  * Here is simple scheme of information exchange between classes:
31  *
32  * @dot
33  digraph G
34 {
35  graph[rankdir="LR",bgcolor="transparent"];
36 
37  edge [fontname="FreeSans",fontsize=15,labelfontname="FreeSans",labelfontsize=10];
38  node [fontname="FreeSans",fontsize=15,
39  shape=record,height=0.2,width=0.4,
40  color="black", fillcolor="white", style="filled"];
41 
42  DeclarationTree [label="Declaration tree\n(Input::Type...)",URL="\ref input_types"];
43  InputFile [label="Input file\n(YAML, JSON)"];
44  Reader [label="Particular reader\n(Input::ReaderToStorage)",URL="\ref Input::ReaderToStorage"];
45  Storage [label="Data storage tree\n(Input::StorageBase...)",URL="\ref Input::StorageBase"];
46  Accessors [label="Data accessors\n(Input::Record, Input::Array, ...)",URL="\ref input_accessors"];
47  Doc [label="Input documentation"];
48  DataUsage [label="Data usage"];
49 
50  {rank=same; InputFile Reader Storage Accessors DataUsage}
51  {rank=same; DeclarationTree Doc }
52 
53  DeclarationTree -> Reader [color="black",fontsize=10,style="solid",fontname="FreeSans"];
54  DeclarationTree -> Accessors [color="black",fontsize=10,style="solid",fontname="FreeSans"];
55  DeclarationTree -> Doc [color="black",fontsize=10,style="solid",fontname="FreeSans"];
56  InputFile -> Reader [color="black",fontsize=10,style="solid",fontname="FreeSans"];
57  Reader -> Storage [color="black",fontsize=10,style="solid",fontname="FreeSans"];
58  Storage -> Accessors [color="black",fontsize=10,style="solid",fontname="FreeSans"];
59  Accessors -> DataUsage [color="black",fontsize=10,style="solid",fontname="FreeSans"];
60 }
61  * @enddot
62  *
63  * \section practical_usage Practical usage
64  *
65  * In order to use input interface you have to create \e declaration-tree, namely Selection, Record, and Abstract types
66  * has to be declared by specification of its keys. We suggest to have a static method that returns Input::Type::Record
67  * for ever class which is initialized from input interface. Example of usage follows:
68  *
69  @code
70  class Mesh {
71  static Input::Type::Record get_input_type() {
72  using namespace Input::Type;
73  return Record("Mesh", "Full description of computational mesh.")
74  .declare_key("mesh_name", String(), Default::optional(),"Optional name of the mesh")
75  .declare_key("mesh_file", FileName::input(), Default("mesh.msh"), "Principial mesh input file")
76  .declare_key("materials_to_remove", Array(Integer()), "Removes elements with material ID that appears in this list.")
77  .close();
78  }
79 
80  Mesh( Input::Record input)
81  : name( input.val<string>("mesh_name") )
82  {
83  string fname = input.val<FilePath>("mesh_file");
84  boundary = new Boundary( input.val<Input::Record>("boundary") );
85  std::vector<int> ids_to_remove;
86  input.val<Input::Array>("materials_to_remove").copy_to( ids_to_remove );
87  }
88  }
89  @endcode
90  *
91  * The accessor for the root Input::Record is provided by the reader class ( ReaderToStorage.get_root_interface<>() )
92  *
93  */