Branch data Line data Source code
1 : : /*
2 : : * gnc-sx-instance-model.h
3 : : *
4 : : * Copyright (C) 2006 Josh Sled <jsled@asynchronous.org>
5 : : *
6 : : * This program is free software; you can redistribute it and/or
7 : : * modify it under the terms of version 2 and/or version 3 of the GNU General Public
8 : : * License as published by the Free Software Foundation.
9 : : *
10 : : * This program is distributed in the hope that it will be useful,
11 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 : : * GNU General Public License for more details.
14 : : *
15 : : * You should have received a copy of the GNU General Public License
16 : : * along with this program; if not, contact:
17 : : *
18 : : * Free Software Foundation Voice: +1-617-542-5942
19 : : * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652
20 : : * Boston, MA 02110-1301, USA gnu@gnu.org
21 : : */
22 : :
23 : : /** \file
24 : : */
25 : :
26 : : #ifndef _GNC_SX_INSTANCE_MODEL_H
27 : : #define _GNC_SX_INSTANCE_MODEL_H
28 : :
29 : : #include <config.h>
30 : : #include <glib.h>
31 : : #include <glib-object.h>
32 : : #include "gnc-numeric.h"
33 : : #include "SchedXaction.h"
34 : :
35 : : G_BEGIN_DECLS
36 : :
37 : : #define GNC_TYPE_SX_INSTANCE_MODEL (gnc_sx_instance_model_get_type ())
38 : 0 : G_DECLARE_FINAL_TYPE (GncSxInstanceModel, gnc_sx_instance_model, GNC, SX_INSTANCE_MODEL, GObject)
39 : :
40 : : typedef struct _GncSxInstances
41 : : {
42 : : SchedXaction *sx;
43 : : GHashTable /** <name:char*,GncSxVariable*> **/ *variable_names;
44 : : gboolean variable_names_parsed;
45 : :
46 : : GDate next_instance_date;
47 : :
48 : : /** GList<GncSxInstance*> **/
49 : : GList *instance_list;
50 : : } GncSxInstances;
51 : :
52 : : typedef enum
53 : : {
54 : : SX_INSTANCE_STATE_IGNORED,
55 : : SX_INSTANCE_STATE_POSTPONED,
56 : : SX_INSTANCE_STATE_TO_CREATE,
57 : : SX_INSTANCE_STATE_REMINDER,
58 : : SX_INSTANCE_STATE_CREATED,
59 : : SX_INSTANCE_STATE_MAX_STATE
60 : : } GncSxInstanceState;
61 : :
62 : : typedef struct _GncSxVariable
63 : : {
64 : : gchar *name;
65 : : gnc_numeric value; /**< only numeric values are supported. **/
66 : : gboolean editable;
67 : : } GncSxVariable;
68 : :
69 : : typedef struct _GncSxInstance
70 : : {
71 : : GncSxInstances *parent; /**< the parent instances collection. **/
72 : : SXTmpStateData *temporal_state; /**< the sx creation temporal state. **/
73 : : GncSxInstanceState orig_state; /**< the original state at generation time. **/
74 : : GncSxInstanceState state; /**< the current state of the instance (during editing) **/
75 : : GDate date; /**< the instance date. **/
76 : : GHashTable *variable_bindings; /**< variable bindings. **/
77 : : } GncSxInstance;
78 : :
79 : : typedef struct _GncSxVariableNeeded
80 : : {
81 : : GncSxInstance *instance;
82 : : GncSxVariable *variable;
83 : : } GncSxVariableNeeded;
84 : :
85 : : /** Shorthand for get_instances(now, FALSE); */
86 : : GncSxInstanceModel* gnc_sx_get_current_instances(void);
87 : :
88 : : /** Allocates a new SxInstanceModel and fills it with generated
89 : : * instances for all scheduled transactions up to the given range_end
90 : : * date.
91 : : *
92 : : * The caller must unref the returned object by
93 : : * g_object_unref(G_OBJECT(inst_model)); when no longer in use. */
94 : : GncSxInstanceModel* gnc_sx_get_instances(const GDate *range_end, gboolean include_disabled);
95 : :
96 : : /**
97 : : * Regenerates and updates the GncSxInstances* for the given SX. Model
98 : : * consumers are probably going to call this in response to seeing the
99 : : * "update" signal, unless they need to be doing something else like
100 : : * finishing an iteration over an existing GncSxInstances*.
101 : : **/
102 : : void gnc_sx_instance_model_update_sx_instances(GncSxInstanceModel *model, SchedXaction *sx);
103 : : void gnc_sx_instance_model_remove_sx_instances(GncSxInstanceModel *model, SchedXaction *sx);
104 : :
105 : : /** Fix up numerics where they've gotten out-of-sync with the formulas.
106 : : *
107 : : * Ideally this would be done at load time, but it requires gnc_exp_parser to
108 : : * work and neither engine nor the backends can depend on it.
109 : : */
110 : : void gnc_sx_scrub_split_numerics (gpointer psplit, gpointer user);
111 : :
112 : : /** @return GList<GncSxVariable*>. Caller owns the list, but not the items. **/
113 : : GList *gnc_sx_instance_get_variables(GncSxInstance *inst);
114 : :
115 : : Account* gnc_sx_get_template_transaction_account(const SchedXaction *sx);
116 : :
117 : : /**
118 : : * @return caller-owned data struct.
119 : : **/
120 : : GHashTable* gnc_sx_instance_get_variables_for_parser(GHashTable *instance_var_hash);
121 : :
122 : : GncSxVariable* gnc_sx_variable_new_full(gchar *name, gnc_numeric value, gboolean editable);
123 : : void gnc_sx_variable_free(GncSxVariable *var);
124 : :
125 : : /**
126 : : * There is a constraint around a sequence of upcoming instance states. In
127 : : * short: the last-created state and a list of postponed instances are modeled,
128 : : * but upcoming reminders are not. As such, a reminder can never be before any
129 : : * other (modeled) instance type. For instance, the following sequences are
130 : : * disallowed:
131 : : *
132 : : * [...]
133 : : * remind <- will be lost/skipped over; must be converted to `postponed`.
134 : : * to-create <- this will be the last-recorded state.
135 : : * [...]
136 : : *
137 : : * [...]
138 : : * remind <- same as previous; will be lost/skipped; must be `postponed`.
139 : : * postponed
140 : : * [...]
141 : : *
142 : : * remind <- same...
143 : : * ignore
144 : : * [...]
145 : : *
146 : : *
147 : : * As such, the SinceLastRun model will enforce that there are no previous
148 : : * `remind` instances at every state change. They will be silently converted to
149 : : * `postponed`-state transactions.
150 : : **/
151 : : void gnc_sx_instance_model_change_instance_state(GncSxInstanceModel *model,
152 : : GncSxInstance *instance,
153 : : GncSxInstanceState new_state);
154 : :
155 : : void gnc_sx_instance_model_set_variable(GncSxInstanceModel *model,
156 : : GncSxInstance *instance,
157 : : GncSxVariable *variable,
158 : : gnc_numeric *new_value);
159 : :
160 : : /**
161 : : * @return List<GncSxVariableNeeded> of unbound {instance,variable} pairs;
162 : : * the caller owns the list and the items.
163 : : **/
164 : : GList* gnc_sx_instance_model_check_variables(GncSxInstanceModel *model);
165 : :
166 : : /** Really ("effectively") create the transactions from the SX
167 : : * instances in the given model. */
168 : : void gnc_sx_instance_model_effect_change(GncSxInstanceModel *model,
169 : : gboolean auto_create_only,
170 : : GList **created_transaction_guids,
171 : : GList **creation_errors);
172 : :
173 : : typedef struct _GncSxSummary
174 : : {
175 : : gboolean need_dialog; /**< If the dialog needs to be displayed. **/
176 : :
177 : : gint num_instances; /**< The number of total instances (in any state). **/
178 : : gint num_to_create_instances; /**< The number of (not-auto-create) to-create instances. **/
179 : : gint num_auto_create_instances; /**< The total number of auto-create instances. **/
180 : : gint num_auto_create_no_notify_instances; /**< The number of automatically-created instances that do no request notification. **/
181 : : } GncSxSummary;
182 : :
183 : : /**
184 : : * @param summary Caller-provided, populated with a summarization of the
185 : : * state of the model. Specifically, used to determine if there are SLR SXes
186 : : * that need either auto-creation or user-interaction.
187 : : **/
188 : : void gnc_sx_instance_model_summarize(GncSxInstanceModel *model, GncSxSummary *summary);
189 : :
190 : : /** Debug output to trace file */
191 : : void gnc_sx_summary_print(const GncSxSummary *summary);
192 : :
193 : : void gnc_sx_get_variables(SchedXaction *sx, GHashTable *var_hash);
194 : : int gnc_sx_parse_vars_from_formula(const char *formula, GHashTable *var_hash, gnc_numeric *result);
195 : : void gnc_sx_randomize_variables(GHashTable *vars);
196 : :
197 : : /** Returns a GHashTable<GUID*, gnc_numeric*> with no destructor for
198 : : * the key, but a destructor for the value set.
199 : : *
200 : : * The returned value must be free'd with g_hash_table_destroy or
201 : : * g_hash_table_unref. */
202 : : GHashTable* gnc_g_hash_new_guid_numeric(void);
203 : :
204 : : /** Instantiates the cash flow of all given SXs (in the given
205 : : * GList<SchedXAction*>) into the GHashTable<GUID*, gnc_numeric*> for the
206 : : * given date range. Each SX is counted with multiplicity as it has
207 : : * occurrences in the given date range.
208 : : *
209 : : * The creation_errors list, if non-NULL, receive any errors that
210 : : * occurred during creation, similar as in
211 : : * gnc_sx_instance_model_effect_change(). */
212 : : void gnc_sx_all_instantiate_cashflow(GList *all_sxes,
213 : : const GDate *range_start, const GDate *range_end,
214 : : GHashTable* map, GList **creation_errors);
215 : :
216 : : /** Simplified wrapper around gnc_sx_all_instantiate_cashflow(): Run
217 : : * that function on all SX of the current book for the given date
218 : : * range. Ignore any potential error messages. Returns a newly
219 : : * allocated GHashTable with the result, which is a GHashTable<GUID*,
220 : : * gnc_numeric*>, identical to what gnc_g_hash_new_guid_numeric()
221 : : * would return. The returned value must be free'd with
222 : : * g_hash_table_destroy. */
223 : : GHashTable* gnc_sx_all_instantiate_cashflow_all(GDate range_start, GDate range_end);
224 : :
225 : : /** Returns the list of GncSxInstances in the model
226 : : * (Each element in the list has type GncSxInstances)
227 : : *
228 : : * The returned list is owned by the model
229 : : */
230 : : GList *gnc_sx_instance_model_get_sx_instances_list (GncSxInstanceModel *model);
231 : :
232 : : G_END_DECLS
233 : :
234 : :
235 : : #endif // _GNC_SX_INSTANCE_MODEL_H
|
