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 : : /** Allocates a new SxInstanceModel and fills it with generated
97 : : * instances for the given scheduled transactions up to now. If
98 : : * no instance exists for a given scheduled transaction, the next
99 : : * instance is generated.
100 : : *
101 : : * The caller must unref the returned object by
102 : : * g_object_unref(G_OBJECT(inst_model)); when no longer in use. */
103 : : GncSxInstanceModel* gnc_sx_get_select_instances(GList *sel_sxes);
104 : :
105 : : /**
106 : : * Regenerates and updates the GncSxInstances* for the given SX. Model
107 : : * consumers are probably going to call this in response to seeing the
108 : : * "update" signal, unless they need to be doing something else like
109 : : * finishing an iteration over an existing GncSxInstances*.
110 : : **/
111 : : void gnc_sx_instance_model_update_sx_instances(GncSxInstanceModel *model, SchedXaction *sx);
112 : : void gnc_sx_instance_model_remove_sx_instances(GncSxInstanceModel *model, SchedXaction *sx);
113 : :
114 : : /** Fix up numerics where they've gotten out-of-sync with the formulas.
115 : : *
116 : : * Ideally this would be done at load time, but it requires gnc_exp_parser to
117 : : * work and neither engine nor the backends can depend on it.
118 : : */
119 : : void gnc_sx_scrub_split_numerics (gpointer psplit, gpointer user);
120 : :
121 : : /** @return GList<GncSxVariable*>. Caller owns the list, but not the items. **/
122 : : GList *gnc_sx_instance_get_variables(GncSxInstance *inst);
123 : :
124 : : Account* gnc_sx_get_template_transaction_account(const SchedXaction *sx);
125 : :
126 : : /**
127 : : * @return caller-owned data struct.
128 : : **/
129 : : GHashTable* gnc_sx_instance_get_variables_for_parser(GHashTable *instance_var_hash);
130 : :
131 : : GncSxVariable* gnc_sx_variable_new_full(gchar *name, gnc_numeric value, gboolean editable);
132 : : void gnc_sx_variable_free(GncSxVariable *var);
133 : :
134 : : /**
135 : : * There is a constraint around a sequence of upcoming instance states. In
136 : : * short: the last-created state and a list of postponed instances are modeled,
137 : : * but upcoming reminders are not. As such, a reminder can never be before any
138 : : * other (modeled) instance type. For instance, the following sequences are
139 : : * disallowed:
140 : : *
141 : : * [...]
142 : : * remind <- will be lost/skipped over; must be converted to `postponed`.
143 : : * to-create <- this will be the last-recorded state.
144 : : * [...]
145 : : *
146 : : * [...]
147 : : * remind <- same as previous; will be lost/skipped; must be `postponed`.
148 : : * postponed
149 : : * [...]
150 : : *
151 : : * remind <- same...
152 : : * ignore
153 : : * [...]
154 : : *
155 : : *
156 : : * As such, the SinceLastRun model will enforce that there are no previous
157 : : * `remind` instances at every state change. They will be silently converted to
158 : : * `postponed`-state transactions.
159 : : **/
160 : : void gnc_sx_instance_model_change_instance_state(GncSxInstanceModel *model,
161 : : GncSxInstance *instance,
162 : : GncSxInstanceState new_state);
163 : :
164 : : void gnc_sx_instance_model_set_variable(GncSxInstanceModel *model,
165 : : GncSxInstance *instance,
166 : : GncSxVariable *variable,
167 : : gnc_numeric *new_value);
168 : :
169 : : /**
170 : : * @return List<GncSxVariableNeeded> of unbound {instance,variable} pairs;
171 : : * the caller owns the list and the items.
172 : : **/
173 : : GList* gnc_sx_instance_model_check_variables(GncSxInstanceModel *model);
174 : :
175 : : /** Really ("effectively") create the transactions from the SX
176 : : * instances in the given model. */
177 : : void gnc_sx_instance_model_effect_change(GncSxInstanceModel *model,
178 : : gboolean auto_create_only,
179 : : GList **created_transaction_guids,
180 : : GList **creation_errors);
181 : :
182 : : typedef struct _GncSxSummary
183 : : {
184 : : gboolean need_dialog; /**< If the dialog needs to be displayed. **/
185 : :
186 : : gint num_instances; /**< The number of total instances (in any state). **/
187 : : gint num_to_create_instances; /**< The number of (not-auto-create) to-create instances. **/
188 : : gint num_auto_create_instances; /**< The total number of auto-create instances. **/
189 : : gint num_auto_create_no_notify_instances; /**< The number of automatically-created instances that do no request notification. **/
190 : : } GncSxSummary;
191 : :
192 : : /**
193 : : * @param summary Caller-provided, populated with a summarization of the
194 : : * state of the model. Specifically, used to determine if there are SLR SXes
195 : : * that need either auto-creation or user-interaction.
196 : : **/
197 : : void gnc_sx_instance_model_summarize(GncSxInstanceModel *model, GncSxSummary *summary);
198 : :
199 : : /** Debug output to trace file */
200 : : void gnc_sx_summary_print(const GncSxSummary *summary);
201 : :
202 : : void gnc_sx_get_variables(SchedXaction *sx, GHashTable *var_hash);
203 : : int gnc_sx_parse_vars_from_formula(const char *formula, GHashTable *var_hash, gnc_numeric *result);
204 : : void gnc_sx_randomize_variables(GHashTable *vars);
205 : :
206 : : /** Returns a GHashTable<GUID*, gnc_numeric*> with no destructor for
207 : : * the key, but a destructor for the value set.
208 : : *
209 : : * The returned value must be free'd with g_hash_table_destroy or
210 : : * g_hash_table_unref. */
211 : : GHashTable* gnc_g_hash_new_guid_numeric(void);
212 : :
213 : : /** Instantiates the cash flow of all given SXs (in the given
214 : : * GList<SchedXAction*>) into the GHashTable<GUID*, gnc_numeric*> for the
215 : : * given date range. Each SX is counted with multiplicity as it has
216 : : * occurrences in the given date range.
217 : : *
218 : : * The creation_errors list, if non-NULL, receive any errors that
219 : : * occurred during creation, similar as in
220 : : * gnc_sx_instance_model_effect_change(). */
221 : : void gnc_sx_all_instantiate_cashflow(GList *all_sxes,
222 : : const GDate *range_start, const GDate *range_end,
223 : : GHashTable* map, GList **creation_errors);
224 : :
225 : : /** Simplified wrapper around gnc_sx_all_instantiate_cashflow(): Run
226 : : * that function on all SX of the current book for the given date
227 : : * range. Ignore any potential error messages. Returns a newly
228 : : * allocated GHashTable with the result, which is a GHashTable<GUID*,
229 : : * gnc_numeric*>, identical to what gnc_g_hash_new_guid_numeric()
230 : : * would return. The returned value must be free'd with
231 : : * g_hash_table_destroy. */
232 : : GHashTable* gnc_sx_all_instantiate_cashflow_all(GDate range_start, GDate range_end);
233 : :
234 : : /** Returns the list of GncSxInstances in the model
235 : : * (Each element in the list has type GncSxInstances)
236 : : *
237 : : * The returned list is owned by the model
238 : : */
239 : : GList *gnc_sx_instance_model_get_sx_instances_list (GncSxInstanceModel *model);
240 : :
241 : : G_END_DECLS
242 : :
243 : :
244 : : #endif // _GNC_SX_INSTANCE_MODEL_H
|
