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
|
