dfsm: Add all the missing API reference comments
[bendy-bus:bendy-bus.git] / dfsm / dfsm-ast-node.c
1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
2 /*
3  * D-Bus Simulator
4  * Copyright (C) Philip Withnall 2011 <philip@tecnocode.co.uk>
5  * 
6  * D-Bus Simulator is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * D-Bus Simulator is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with D-Bus Simulator.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 /**
21  * SECTION:dfsm-ast-node
22  * @short_description: AST node
23  * @stability: Unstable
24  * @include: dfsm/dfsm-ast-node.h
25  *
26  * Abstract base class for all AST nodes implementing the basis of the checking code.
27  */
28
29 #include <glib.h>
30
31 #include "dfsm-ast-node.h"
32
33 G_DEFINE_ABSTRACT_TYPE (DfsmAstNode, dfsm_ast_node, G_TYPE_OBJECT)
34
35 static void
36 dfsm_ast_node_class_init (DfsmAstNodeClass *klass)
37 {
38         /* Nothing to see here. */
39 }
40
41 static void
42 dfsm_ast_node_init (DfsmAstNode *self)
43 {
44         /* Nothing to see here. */
45 }
46
47 /**
48  * dfsm_ast_node_sanity_check:
49  * @self: a #DfsmAstNode
50  *
51  * Sanity check the node (but not its descendents), asserting that various conditions hold which should always be true, regardless of the stage of
52  * interpretation the system's in. If any of the assertions fail, the program will abort.
53  *
54  * The checks made by this function should always hold, regardless of user input.
55  */
56 void
57 dfsm_ast_node_sanity_check (DfsmAstNode *self)
58 {
59         DfsmAstNodeClass *klass;
60
61         g_return_if_fail (DFSM_IS_AST_NODE (self));
62
63         klass = DFSM_AST_NODE_GET_CLASS (self);
64
65         /* If the sanity check function doesn't exist, assume the node is always guaranteed to be OK. */
66         if (klass->sanity_check != NULL) {
67                 klass->sanity_check (self);
68         }
69 }
70
71 /**
72  * dfsm_ast_node_pre_check_and_register:
73  * @self: a #DfsmAstNode
74  * @environment: environment to register variables in
75  * @error: a #GError
76  *
77  * Check the node and its descendents are basically correct. The checks guarantee enough is correct for appropriate additions to be made to the
78  * @environment, which are performed by this function. If checking finds a problem, @error will be set to a suitable #GError; otherwise, @error will
79  * remain unset. If a problem is found, @environment will be left in an unspecified state.
80  *
81  * The checks made by this function may not hold, depending on user input.
82  */
83 void
84 dfsm_ast_node_pre_check_and_register (DfsmAstNode *self, DfsmEnvironment *environment, GError **error)
85 {
86         DfsmAstNodeClass *klass;
87         GError *child_error = NULL;
88
89         g_return_if_fail (DFSM_IS_AST_NODE (self));
90         g_return_if_fail (DFSM_IS_ENVIRONMENT (environment));
91         g_return_if_fail (error != NULL && *error == NULL);
92
93         klass = DFSM_AST_NODE_GET_CLASS (self);
94
95         /* If the pre-check function doesn't exist, assume the node is always guaranteed to be OK and doesn't need to register anything in the
96          * environment. */
97         if (klass->pre_check_and_register != NULL) {
98                 klass->pre_check_and_register (self, environment, &child_error);
99
100                 /* We pass in our own child_error so that we can guarantee it's non-NULL to the virtual method implementations. */
101                 if (child_error != NULL) {
102                         g_propagate_error (error, child_error);
103                 }
104         }
105 }
106
107 /**
108  * dfsm_ast_node_check:
109  * @self: a #DfsmAstNode
110  * @environment: environment containing the values of all variables known so far
111  * @error: a #GError
112  *
113  * Check the node and its descendents are correct. This may, for example, involve type checking or checking of constants. If checking finds a problem,
114  * @error will be set to a suitable #GError; otherwise, @error will remain unset.
115  *
116  * This should only be called after dfsm_ast_node_pre_check_and_register() has been successfully called for all nodes, since this node's validity may
117  * depend on other nodes having registered things in the @environment.
118  *
119  * The checks made by this function may not hold, depending on user input.
120  */
121 void
122 dfsm_ast_node_check (DfsmAstNode *self, DfsmEnvironment *environment, GError **error)
123 {
124         DfsmAstNodeClass *klass;
125         GError *child_error = NULL;
126
127         g_return_if_fail (DFSM_IS_AST_NODE (self));
128         g_return_if_fail (DFSM_IS_ENVIRONMENT (environment));
129         g_return_if_fail (error != NULL && *error == NULL);
130
131         klass = DFSM_AST_NODE_GET_CLASS (self);
132
133         /* If the check function doesn't exist, assume the node is always guaranteed to be OK. */
134         if (klass->check != NULL) {
135                 klass->check (self, environment, &child_error);
136
137                 /* We pass in our own child_error so that we can guarantee it's non-NULL to the virtual method implementations. */
138                 if (child_error != NULL) {
139                         g_propagate_error (error, child_error);
140                 }
141         }
142 }