src/func.h

   1 #ifndef _GNM_FUNC_H_
   2 # define _GNM_FUNC_H_
   3
   4 #include <gnumeric.h>
   5 #include <dependent.h>
   6
   7 G_BEGIN_DECLS
   8
   9 /* Setup of the symbol table */
  10 void functions_init     (void);
  11 void functions_shutdown (void);
  12
  13 GPtrArray *gnm_func_enumerate (void);
  14
  15 /******************************************************************************/
  16 /* Function group support */
  17
  18 struct _GnmFuncGroup {
  19         GOString *internal_name, *display_name;
  20         gboolean has_translation;
  21         GSList *functions;
  22         unsigned ref_count; /* boxed type */
  23 };
  24
  25 GType gnm_func_group_get_type (void); /* boxed type */
  26 GnmFuncGroup *gnm_func_group_get_nth (gint n);
  27 GnmFuncGroup *gnm_func_group_fetch (char const *name,
  28                                     char const *translation);
  29
  30 /******************************************************************************/
  31
  32 /*
  33  * Function registration routines
  34  *
  35  * Functions come in two fashions:  Those that only deal with
  36  * very specific data types and a constant number of arguments,
  37  * and those who don't.
  38  *
  39  * The former kind of functions receives a precomputed array of
  40  * GnmValue pointers.
  41  *
  42  * The latter sort of functions receives the plain ExprNodes and
  43  * it is up to that routine to do the value computations and range
  44  * processing.
  45  */
  46
  47 /*
  48  *  Argument tokens passed in 'args'
  49  *
  50  * With intersection and iteration support
  51  *      f : floating point      (no errors, string conversion attempted)
  52  *      b : boolean             (identical to f, Do we need this ?)
  53  *      s : string              (no errors)
  54  *      S : 'scalar': any non-error value
  55  *      E : scalar including errors
  56  * Without intersection or iteration support
  57  *      r : cell range  content is _NOT_ guaranteed to have been evaluated yet
  58  *      A : area        either range or array (as above)
  59  *      a : array
  60  *      ? : anything
  61  *
  62  *  For optional arguments do:
  63  * "ff|ss" where the strings are optional
  64  */
  65
  66 typedef enum {
  67         GNM_FUNC_TYPE_ARGS,     /* Arguments get marshalled by type */
  68         GNM_FUNC_TYPE_NODES,    /* Takes unevaulated expers directly */
  69
  70         /* implementation has not been loaded yet, but we know where it is */
  71         GNM_FUNC_TYPE_STUB
  72 } GnmFuncType;
  73
  74 typedef enum {
  75         GNM_FUNC_SIMPLE                 = 0,
  76         GNM_FUNC_VOLATILE               = 1 << 0, /* eg now(), today() */
  77         GNM_FUNC_RETURNS_NON_SCALAR     = 1 << 1, /* eg transpose(), mmult() */
  78
  79         /* For functions that are not exactly compatible with various import
  80          * formats.  We need to recalc their results to avoid changing values
  81          * unexpectedly when we recalc later.  This probably needs to be done
  82          * on a per import format basis.  It may not belong here.
  83          */
  84 /*      GNM_FUNC_RECALC_ONLOAD          = 1 << 2, */
  85
  86         /* an unknown function that will hopefully be defined later */
  87         GNM_FUNC_IS_PLACEHOLDER         = 1 << 3,
  88         GNM_FUNC_IS_WORKBOOK_LOCAL      = 1 << 5,
  89         GNM_FUNC_INTERNAL               = 1 << 6,
  90
  91         GNM_FUNC_AUTO_UNKNOWN           = 0 << 8,
  92         GNM_FUNC_AUTO_MONETARY          = 1 << 8,  /* Like PV */
  93         GNM_FUNC_AUTO_DATE              = 2 << 8,  /* Like DATE */
  94         GNM_FUNC_AUTO_TIME              = 3 << 8,  /* Like TIME */
  95         GNM_FUNC_AUTO_PERCENT           = 4 << 8,  /* Like IRR */
  96         GNM_FUNC_AUTO_FIRST             = 5 << 8,  /* Like SUM */
  97         GNM_FUNC_AUTO_SECOND            = 6 << 8,  /* Like IF */
  98         GNM_FUNC_AUTO_UNITLESS          = 7 << 8,  /* Like COUNT */
  99         GNM_FUNC_AUTO_MASK              = 7 << 8   /* The bits we use for AUTO.  */
 100 } GnmFuncFlags;
 101
 102 /* I do not like this.  It is going to be different for different apps probably
 103  * want to split it into bit file with our notion of its state, and 2 bits of
 104  * state per import format.
 105  */
 106 typedef enum {
 107         GNM_FUNC_IMPL_STATUS_EXISTS = 0,
 108         GNM_FUNC_IMPL_STATUS_UNIMPLEMENTED,
 109         GNM_FUNC_IMPL_STATUS_SUBSET,
 110         GNM_FUNC_IMPL_STATUS_COMPLETE,
 111         GNM_FUNC_IMPL_STATUS_SUPERSET,
 112         GNM_FUNC_IMPL_STATUS_SUBSET_WITH_EXTENSIONS,
 113         GNM_FUNC_IMPL_STATUS_UNDER_DEVELOPMENT,
 114         GNM_FUNC_IMPL_STATUS_UNIQUE_TO_GNUMERIC
 115 } GnmFuncImplStatus;
 116
 117 typedef enum {
 118         GNM_FUNC_TEST_STATUS_UNKNOWN = 0,
 119         GNM_FUNC_TEST_STATUS_NO_TESTSUITE,
 120         GNM_FUNC_TEST_STATUS_BASIC,
 121         GNM_FUNC_TEST_STATUS_EXHAUSTIVE,
 122         GNM_FUNC_TEST_STATUS_UNDER_DEVELOPMENT
 123 } GnmFuncTestStatus;
 124
 125 typedef GnmValue        *(*GnmFuncArgs)   (GnmFuncEvalInfo *ei, GnmValue const * const *args);
 126 typedef GnmValue        *(*GnmFuncNodes)  (GnmFuncEvalInfo *ei,
 127                                            int argc, GnmExprConstPtr const *argv);
 128
 129 typedef enum {
 130         GNM_FUNC_HELP_END,              /* Format */
 131                                         /* ------ */
 132         GNM_FUNC_HELP_NAME,
 133         /* <NAME>:<1 SENTENCE DESCRIPTION> (translated) */
 134
 135         GNM_FUNC_HELP_ARG,
 136         /* <NAME>:<1 SENTENCE DESCRIPTION> (translated) */
 137
 138         GNM_FUNC_HELP_DESCRIPTION,
 139         /* <LONG DESCRIPTION (reference args using @{arg})> (translated) */
 140
 141         GNM_FUNC_HELP_NOTE,
 142         /* <SPECIAL CASES (reference args using @{arg})> (translated) */
 143
 144         GNM_FUNC_HELP_EXAMPLES,
 145         /*
 146          * Either translated text, or a formula that is only marked for
 147          * translation if it contains strings that need to be translated.
 148          */
 149
 150         GNM_FUNC_HELP_SEEALSO,
 151         /* name,name,name ...   (not translated) */
 152
 153         GNM_FUNC_HELP_EXTREF,
 154         /*
 155          * Link to external descriptions.  The following styles defined:
 156          * wolfram:Sine.html
 157          * wiki:en:Trigonometric_functions
 158          */
 159
 160         GNM_FUNC_HELP_EXCEL,
 161         /* <SPECIAL NOTE RE EXCEL (reference args using @{arg})> (translated) */
 162
 163         GNM_FUNC_HELP_ODF
 164         /* <SPECIAL NOTE RE ODF (reference args using @{arg})> (translated) */
 165 } GnmFuncHelpType;
 166
 167 typedef struct {
 168     GnmFuncHelpType      type;
 169     char const          *text;
 170 } GnmFuncHelp;
 171
 172 struct _GnmFuncDescriptor {
 173         char const *name;
 174         char const *arg_spec;
 175         GnmFuncHelp const *help;
 176         GnmFuncArgs       fn_args;
 177         GnmFuncNodes      fn_nodes;
 178         GnmFuncFlags      flags;
 179         GnmFuncImplStatus impl_status;
 180         GnmFuncTestStatus test_status;
 181 };
 182
 183 struct GnmFunc_ {
 184         GObject base;
 185
 186         char const *name;
 187         GnmFuncHelp const *help;
 188
 189         /* <private> */
 190         GnmFuncType fn_type;
 191         GnmFuncGroup *fn_group;
 192         GnmFuncFlags flags;
 193         GnmFuncImplStatus impl_status;
 194         GnmFuncTestStatus test_status;
 195
 196         GOString *tdomain;
 197         char *localized_name;
 198
 199         gint usage_count;
 200
 201         // Meaningful for ARGS only
 202         char *arg_spec;
 203         GnmFuncArgs args_func;
 204
 205         // Meaningful for NODES only
 206         GnmFuncNodes nodes_func;
 207
 208         // Derived for quick access
 209         GPtrArray *arg_names;
 210         int min_args, max_args;
 211         char *arg_types;
 212 };
 213
 214 #define GNM_FUNC_TYPE   (gnm_func_get_type ())
 215 #define GNM_FUNC(obj)   (G_TYPE_CHECK_INSTANCE_CAST ((obj), GNM_FUNC_TYPE, GnmFunc))
 216 #define GNM_IS_FUNC(o)  (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNM_FUNC_TYPE))
 217
 218 GType       gnm_func_get_type        (void);
 219 void        gnm_func_load_if_stub    (GnmFunc *func);
 220 void        gnm_func_dispose         (GnmFunc *func);
 221
 222 GnmFunc    *gnm_func_inc_usage       (GnmFunc *func);
 223 void        gnm_func_dec_usage       (GnmFunc *func);
 224 gboolean    gnm_func_get_in_use      (GnmFunc *func);
 225
 226 char const *gnm_func_get_translation_domain (GnmFunc *func);
 227 void        gnm_func_set_translation_domain (GnmFunc *func,
 228                                              const char *tdomain);
 229
 230 GnmFuncFlags gnm_func_get_flags      (GnmFunc *func);
 231 void        gnm_func_set_flags       (GnmFunc *func, GnmFuncFlags f);
 232
 233
 234 GnmFuncImplStatus gnm_func_get_impl_status (GnmFunc *func);
 235 void        gnm_func_set_impl_status (GnmFunc *func, GnmFuncImplStatus st);
 236
 237 GnmFuncTestStatus gnm_func_get_test_status (GnmFunc *func);
 238 void        gnm_func_set_test_status (GnmFunc *func, GnmFuncTestStatus st);
 239
 240 GnmFuncGroup*gnm_func_get_function_group (GnmFunc *func);
 241 void        gnm_func_set_function_group (GnmFunc *func, GnmFuncGroup *group);
 242
 243 gboolean    gnm_func_is_varargs      (GnmFunc *func);
 244 gboolean    gnm_func_is_fixargs      (GnmFunc *func);
 245
 246 void        gnm_func_set_stub        (GnmFunc *func);
 247 void        gnm_func_set_varargs     (GnmFunc *func, GnmFuncNodes fn);
 248 void        gnm_func_set_fixargs     (GnmFunc *func, GnmFuncArgs fn,
 249                                       const char *spec);
 250
 251 GnmDependentFlags gnm_func_link_dep (GnmFunc *func, GnmFuncEvalInfo *ei, gboolean qlink);
 252
 253 char const *gnm_func_get_name        (GnmFunc const *func,
 254                                       gboolean localized);
 255 GnmFunc    *gnm_func_lookup          (char const *name, Workbook *scope);
 256 GnmFunc    *gnm_func_lookup_localized (char const *name, Workbook *scope);
 257 GSList     *gnm_func_lookup_prefix   (char const *prefix, Workbook *scope,
 258                                       gboolean trans);
 259 GnmFunc    *gnm_func_add             (GnmFuncGroup *group,
 260                                       GnmFuncDescriptor const *descriptor,
 261                                       const char *tdomain);
 262 void        gnm_func_set_from_desc   (GnmFunc *func, GnmFuncDescriptor const *desc);
 263
 264 GnmFunc    *gnm_func_add_placeholder (Workbook *scope,
 265                                       char const *name,
 266                                       char const *type);
 267 GnmFunc    *gnm_func_add_placeholder_localized (char const *gname, char const *lname);
 268 GnmFunc    *gnm_func_lookup_or_add_placeholder (char const *name);
 269
 270 /* TODO */
 271 char const *gnm_func_get_description (GnmFunc const *fn_def);
 272 void        gnm_func_count_args    (GnmFunc const *fn_def,
 273                                         gint *min, int *max);
 274 char        gnm_func_get_arg_type  (GnmFunc const *fn_def,
 275                                         gint arg_idx);
 276 char const *gnm_func_get_arg_type_string  (GnmFunc const *fn_def,
 277                                         gint arg_idx);
 278 char       *gnm_func_get_arg_name  (GnmFunc const *func, guint arg_idx);
 279 char const *gnm_func_get_arg_description (GnmFunc const *fn_def,
 280                                         guint arg_idx);
 281 char       *gnm_func_convert_markup_to_pango (char const *desc,
 282                                               GtkWidget *target);
 283
 284 /*************************************************************************/
 285
 286 GnmValue *function_call_with_exprs      (GnmFuncEvalInfo *ei);
 287 GnmValue *function_call_with_values     (GnmEvalPos const *ep, char const *name,
 288                                          int argc, GnmValue const * const *values);
 289 GnmValue *function_def_call_with_values (GnmEvalPos const *ep, GnmFunc const *fn,
 290                                          int argc, GnmValue const * const *values);
 291
 292 /* Utilies to interate through ranges and argument lists */
 293 typedef GnmValue * (*FunctionIterateCB) (GnmEvalPos const *ep, GnmValue const *value,
 294                                          gpointer user_data);
 295 GnmValue *function_iterate_argument_values (GnmEvalPos const *ep,
 296                                             FunctionIterateCB callback,
 297                                             gpointer callback_closure,
 298                                             int argc,
 299                                             GnmExprConstPtr const *argv,
 300                                             gboolean strict,
 301                                             CellIterFlags iter_flags);
 302
 303 /*************************************************************************/
 304
 305 struct _GnmFuncEvalInfo {
 306         GnmEvalPos const *pos;
 307         GnmExprFunction const *func_call;
 308         GnmExprEvalFlags flags;
 309 };
 310
 311 GnmFunc const *gnm_eval_info_get_func (GnmFuncEvalInfo const *ei);
 312 int gnm_eval_info_get_arg_count (GnmFuncEvalInfo const *ei);
 313
 314 G_END_DECLS
 315
 316 #endif /* _GNM_FUNC_H_ */