src/func.h

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