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 typedef GnmDependentFlags (*GnmFuncLink)  (GnmFuncEvalInfo *ei, gboolean qlink);
 129
 130 typedef void     (*GnmFuncUsageNotify) (GnmFunc *f, int refcount);
 131 typedef gboolean (*GnmFuncLoadDesc)  (GnmFunc const *f, GnmFuncDescriptor *fd);
 132
 133 typedef enum {
 134         GNM_FUNC_HELP_END,              /* Format */
 135                                         /* ------ */
 136         GNM_FUNC_HELP_NAME,
 137         /* <NAME>:<1 SENTENCE DESCRIPTION> (translated) */
 138
 139         GNM_FUNC_HELP_ARG,
 140         /* <NAME>:<1 SENTENCE DESCRIPTION> (translated) */
 141
 142         GNM_FUNC_HELP_DESCRIPTION,
 143         /* <LONG DESCRIPTION (reference args using @{arg})> (translated) */
 144
 145         GNM_FUNC_HELP_NOTE,
 146         /* <SPECIAL CASES (reference args using @{arg})> (translated) */
 147
 148         GNM_FUNC_HELP_EXAMPLES,
 149         /*
 150          * Either translated text, or a formula that is only marked for
 151          * translation if it contains strings that need to be translated.
 152          */
 153
 154         GNM_FUNC_HELP_SEEALSO,
 155         /* name,name,name ...   (not translated) */
 156
 157         GNM_FUNC_HELP_EXTREF,
 158         /*
 159          * Link to external descriptions.  The following styles defined:
 160          * wolfram:Sine.html
 161          * wiki:en:Trigonometric_functions
 162          */
 163
 164         GNM_FUNC_HELP_EXCEL,
 165         /* <SPECIAL NOTE RE EXCEL (reference args using @{arg})> (translated) */
 166
 167         GNM_FUNC_HELP_ODF
 168         /* <SPECIAL NOTE RE ODF (reference args using @{arg})> (translated) */
 169 } GnmFuncHelpType;
 170 typedef struct {
 171     GnmFuncHelpType      type;
 172     char const          *text;
 173 } GnmFuncHelp;
 174
 175 struct _GnmFuncDescriptor {
 176         char const *name;
 177         char const *arg_spec;
 178         GnmFuncHelp const *help;
 179         GnmFuncArgs       fn_args;
 180         GnmFuncNodes      fn_nodes;
 181         GnmFuncLink       linker;
 182         GnmFuncUsageNotify usage_notify;
 183         GnmFuncFlags      flags;
 184         GnmFuncImplStatus impl_status;
 185         GnmFuncTestStatus test_status;
 186 };
 187
 188 struct _GnmFunc {
 189         char const *name;
 190         GPtrArray  *arg_names_p;
 191         GnmFuncHelp const *help;
 192         GOString *tdomain;
 193         char *localized_name;
 194         GnmFuncType fn_type;
 195         union {
 196                 GnmFuncNodes nodes;
 197                 struct {
 198                         char const *arg_spec;
 199                         GnmFuncArgs  func;
 200                         int min_args, max_args;
 201                         char *arg_types;
 202                 } args;
 203                 GnmFuncLoadDesc load_desc;
 204         } fn;
 205         GnmFuncGroup            *fn_group; /* most recent it was assigned to */
 206         GnmFuncLink              linker;
 207         GnmFuncUsageNotify       usage_notify;
 208         GnmFuncImplStatus        impl_status;
 209         GnmFuncTestStatus        test_status;
 210         GnmFuncFlags             flags;
 211
 212         gint                     usage_count;
 213         gpointer                 user_data;
 214 };
 215
 216 struct _GnmFuncEvalInfo {
 217         GnmEvalPos const *pos;
 218         GnmExprFunction const *func_call;
 219         GnmExprEvalFlags flags;
 220 };
 221
 222 GnmFunc const *gnm_eval_info_get_func (GnmFuncEvalInfo const *ei);
 223 int gnm_eval_info_get_arg_count (GnmFuncEvalInfo const *ei);
 224
 225
 226 GType       gnm_func_get_type        (void);
 227 void        gnm_func_free            (GnmFunc *func);
 228 GnmFunc    *gnm_func_ref             (GnmFunc *func);
 229 void        gnm_func_unref           (GnmFunc *func);
 230 void        gnm_func_load_if_stub    (GnmFunc *func);
 231 void        gnm_func_load_stub       (GnmFunc *fn_def);
 232 char const *gnm_func_get_name        (GnmFunc const *func,
 233                                       gboolean localized);
 234 gpointer    gnm_func_get_user_data   (GnmFunc const *func);
 235 void        gnm_func_set_user_data   (GnmFunc *func, gpointer user_data);
 236 GnmFunc    *gnm_func_lookup          (char const *name, Workbook *scope);
 237 GnmFunc    *gnm_func_lookup_localized (char const *name, Workbook *scope);
 238 GSList     *gnm_func_lookup_prefix   (char const *prefix, Workbook *scope,
 239                                       gboolean trans);
 240 GnmFunc    *gnm_func_add             (GnmFuncGroup *group,
 241                                       GnmFuncDescriptor const *descriptor,
 242                                       const char *tdomain);
 243 GnmFunc    *gnm_func_add_placeholder (Workbook *optional_scope,
 244                                       char const *name,
 245                                       char const *type);
 246 GnmFunc    *gnm_func_add_placeholder_localized (char const *gname, char const *lname);
 247 GnmFunc    *gnm_func_lookup_or_add_placeholder (char const *name);
 248 void        gnm_func_upgrade_placeholder
 249                                       (GnmFunc *fd,
 250                                        GnmFuncGroup *fn_group,
 251                                        const char *tdomain,
 252                                        GnmFuncLoadDesc load_desc,
 253                                        GnmFuncUsageNotify opt_usage_notify);
 254
 255 /* TODO */
 256 char const *gnm_func_get_description (GnmFunc const *fn_def);
 257 void        gnm_func_count_args    (GnmFunc const *fn_def,
 258                                         gint *min, int *max);
 259 char        gnm_func_get_arg_type  (GnmFunc const *fn_def,
 260                                         gint arg_idx);
 261 char const *gnm_func_get_arg_type_string  (GnmFunc const *fn_def,
 262                                         gint arg_idx);
 263 char       *gnm_func_get_arg_name  (GnmFunc const *fn_def,
 264                                         guint arg_idx);
 265 char const *gnm_func_get_arg_description (GnmFunc const *fn_def,
 266                                         guint arg_idx);
 267 char       *gnm_func_convert_markup_to_pango (char const *desc,
 268                                               GtkWidget *target);
 269
 270 /*************************************************************************/
 271
 272 GnmValue *function_call_with_exprs      (GnmFuncEvalInfo *ei);
 273 GnmValue *function_call_with_values     (GnmEvalPos const *ep, char const *name,
 274                                          int argc, GnmValue const * const *values);
 275 GnmValue *function_def_call_with_values (GnmEvalPos const *ep, GnmFunc const *fn,
 276                                          int argc, GnmValue const * const *values);
 277
 278 /* Utilies to interate through ranges and argument lists */
 279 typedef GnmValue * (*FunctionIterateCB) (GnmEvalPos const *ep, GnmValue const *value,
 280                                          gpointer user_data);
 281 GnmValue *function_iterate_argument_values (GnmEvalPos const *ep,
 282                                             FunctionIterateCB callback,
 283                                             gpointer callback_closure,
 284                                             int argc,
 285                                             GnmExprConstPtr const *argv,
 286                                             gboolean strict,
 287                                             CellIterFlags iter_flags);
 288
 289 G_END_DECLS
 290
 291 #endif /* _GNM_FUNC_H_ */