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 gnm_func_init_     (void);
  11 void gnm_func_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         /* an unknown function that will hopefully be defined later */
  80         GNM_FUNC_IS_PLACEHOLDER         = 1 << 3,
  81         GNM_FUNC_IS_WORKBOOK_LOCAL      = 1 << 5,
  82         GNM_FUNC_INTERNAL               = 1 << 6,
  83
  84         GNM_FUNC_AUTO_UNKNOWN           = 0 << 8,
  85         GNM_FUNC_AUTO_MONETARY          = 1 << 8,  /* Like PV */
  86         GNM_FUNC_AUTO_DATE              = 2 << 8,  /* Like DATE */
  87         GNM_FUNC_AUTO_TIME              = 3 << 8,  /* Like TIME */
  88         GNM_FUNC_AUTO_PERCENT           = 4 << 8,  /* Like IRR */
  89         GNM_FUNC_AUTO_FIRST             = 5 << 8,  /* Like SUM */
  90         GNM_FUNC_AUTO_SECOND            = 6 << 8,  /* Like IF */
  91         GNM_FUNC_AUTO_UNITLESS          = 7 << 8,  /* Like COUNT */
  92         GNM_FUNC_AUTO_MASK              = 7 << 8   /* The bits we use for AUTO.  */
  93 } GnmFuncFlags;
  94
  95 /* I do not like this.  It is going to be different for different apps probably
  96  * want to split it into bit file with our notion of its state, and 2 bits of
  97  * state per import format.
  98  */
  99 typedef enum {
 100         GNM_FUNC_IMPL_STATUS_EXISTS = 0,
 101         GNM_FUNC_IMPL_STATUS_UNIMPLEMENTED,
 102         GNM_FUNC_IMPL_STATUS_SUBSET,
 103         GNM_FUNC_IMPL_STATUS_COMPLETE,
 104         GNM_FUNC_IMPL_STATUS_SUPERSET,
 105         GNM_FUNC_IMPL_STATUS_SUBSET_WITH_EXTENSIONS,
 106         GNM_FUNC_IMPL_STATUS_UNDER_DEVELOPMENT,
 107         GNM_FUNC_IMPL_STATUS_UNIQUE_TO_GNUMERIC
 108 } GnmFuncImplStatus;
 109
 110 typedef enum {
 111         GNM_FUNC_TEST_STATUS_UNKNOWN = 0,
 112         GNM_FUNC_TEST_STATUS_NO_TESTSUITE,
 113         GNM_FUNC_TEST_STATUS_BASIC,
 114         GNM_FUNC_TEST_STATUS_EXHAUSTIVE,
 115         GNM_FUNC_TEST_STATUS_UNDER_DEVELOPMENT
 116 } GnmFuncTestStatus;
 117
 118 typedef GnmValue        *(*GnmFuncArgs)   (GnmFuncEvalInfo *ei, GnmValue const * const *args);
 119 typedef GnmValue        *(*GnmFuncNodes)  (GnmFuncEvalInfo *ei,
 120                                            int argc, GnmExprConstPtr const *argv);
 121
 122 typedef enum {
 123         GNM_FUNC_HELP_END,              /* Format */
 124                                         /* ------ */
 125         GNM_FUNC_HELP_NAME,
 126         /* <NAME>:<1 SENTENCE DESCRIPTION> (translated) */
 127
 128         GNM_FUNC_HELP_ARG,
 129         /* <NAME>:<1 SENTENCE DESCRIPTION> (translated) */
 130
 131         GNM_FUNC_HELP_DESCRIPTION,
 132         /* <LONG DESCRIPTION (reference args using @{arg})> (translated) */
 133
 134         GNM_FUNC_HELP_NOTE,
 135         /* <SPECIAL CASES (reference args using @{arg})> (translated) */
 136
 137         GNM_FUNC_HELP_EXAMPLES,
 138         /*
 139          * Either translated text, or a formula that is only marked for
 140          * translation if it contains strings that need to be translated.
 141          */
 142
 143         GNM_FUNC_HELP_SEEALSO,
 144         /* name,name,name ...   (not translated) */
 145
 146         GNM_FUNC_HELP_EXTREF,
 147         /*
 148          * Link to external descriptions.  The following styles defined:
 149          * wolfram:Sine.html
 150          * wiki:en:Trigonometric_functions
 151          */
 152
 153         GNM_FUNC_HELP_EXCEL,
 154         /* <SPECIAL NOTE RE EXCEL (reference args using @{arg})> (translated) */
 155
 156         GNM_FUNC_HELP_ODF
 157         /* <SPECIAL NOTE RE ODF (reference args using @{arg})> (translated) */
 158 } GnmFuncHelpType;
 159
 160 typedef struct {
 161     GnmFuncHelpType      type;
 162     char const          *text;
 163 } GnmFuncHelp;
 164
 165 struct _GnmFuncDescriptor {
 166         char const *name;
 167         char const *arg_spec;
 168         GnmFuncHelp const *help;
 169         GnmFuncArgs       fn_args;
 170         GnmFuncNodes      fn_nodes;
 171         GnmFuncFlags      flags;
 172         GnmFuncImplStatus impl_status;
 173         GnmFuncTestStatus test_status;
 174 };
 175
 176 struct GnmFunc_ {
 177         GObject base;
 178
 179         char const *name;
 180         GnmFuncHelp *help;
 181
 182         /* <private> */
 183         GnmFuncType fn_type;
 184         GnmFuncGroup *fn_group;
 185         GnmFuncFlags flags;
 186         GnmFuncImplStatus impl_status;
 187         GnmFuncTestStatus test_status;
 188
 189         GOString *tdomain;
 190         char *localized_name;
 191
 192         gint usage_count;
 193
 194         // Meaningful for ARGS only
 195         char *arg_spec;
 196         GnmFuncArgs args_func;
 197
 198         // Meaningful for NODES only
 199         GnmFuncNodes nodes_func;
 200
 201         // Derived for quick access
 202         GPtrArray *arg_names;
 203         int min_args, max_args;
 204         char *arg_types;
 205         int help_count;
 206 };
 207
 208 #define GNM_FUNC_TYPE   (gnm_func_get_type ())
 209 #define GNM_FUNC(obj)   (G_TYPE_CHECK_INSTANCE_CAST ((obj), GNM_FUNC_TYPE, GnmFunc))
 210 #define GNM_IS_FUNC(o)  (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNM_FUNC_TYPE))
 211
 212 GType       gnm_func_get_type        (void);
 213 void        gnm_func_load_if_stub    (GnmFunc *func);
 214 void        gnm_func_dispose         (GnmFunc *func);
 215
 216 GnmFunc    *gnm_func_inc_usage       (GnmFunc *func);
 217 void        gnm_func_dec_usage       (GnmFunc *func);
 218 gboolean    gnm_func_get_in_use      (GnmFunc *func);
 219
 220 char const *gnm_func_get_translation_domain (GnmFunc *func);
 221 void        gnm_func_set_translation_domain (GnmFunc *func,
 222                                              const char *tdomain);
 223 char const *gnm_func_gettext         (GnmFunc *func, const char *str);
 224
 225 GnmFuncFlags gnm_func_get_flags      (GnmFunc *func);
 226 void        gnm_func_set_flags       (GnmFunc *func, GnmFuncFlags f);
 227
 228
 229 GnmFuncImplStatus gnm_func_get_impl_status (GnmFunc *func);
 230 void        gnm_func_set_impl_status (GnmFunc *func, GnmFuncImplStatus st);
 231
 232 GnmFuncTestStatus gnm_func_get_test_status (GnmFunc *func);
 233 void        gnm_func_set_test_status (GnmFunc *func, GnmFuncTestStatus st);
 234
 235 GnmFuncGroup*gnm_func_get_function_group (GnmFunc *func);
 236 void        gnm_func_set_function_group (GnmFunc *func, GnmFuncGroup *group);
 237
 238 gboolean    gnm_func_is_varargs      (GnmFunc *func);
 239 gboolean    gnm_func_is_fixargs      (GnmFunc *func);
 240
 241 void        gnm_func_set_stub        (GnmFunc *func);
 242 void        gnm_func_set_varargs     (GnmFunc *func, GnmFuncNodes fn,
 243                                       const char *spec);
 244 void        gnm_func_set_fixargs     (GnmFunc *func, GnmFuncArgs fn,
 245                                       const char *spec);
 246
 247 GnmFuncHelp const *gnm_func_get_help (GnmFunc *func, int *n);
 248 void        gnm_func_set_help (GnmFunc *func, GnmFuncHelp const *help, int n);
 249
 250 GnmDependentFlags gnm_func_link_dep (GnmFunc *func, GnmFuncEvalInfo *ei, gboolean qlink);
 251
 252 char const *gnm_func_get_name        (GnmFunc const *func,
 253                                       gboolean localized);
 254 GnmFunc    *gnm_func_lookup          (char const *name, Workbook *scope);
 255 GnmFunc    *gnm_func_lookup_localized (char const *name, Workbook *scope);
 256 GSList     *gnm_func_lookup_prefix   (char const *prefix, Workbook *scope,
 257                                       gboolean trans);
 258 GnmFunc    *gnm_func_add             (GnmFuncGroup *group,
 259                                       GnmFuncDescriptor const *descriptor,
 260                                       const char *tdomain);
 261 void        gnm_func_set_from_desc   (GnmFunc *func, GnmFuncDescriptor const *desc);
 262
 263 GnmFunc    *gnm_func_add_placeholder (Workbook *scope,
 264                                       char const *name,
 265                                       char const *type);
 266 GnmFunc    *gnm_func_add_placeholder_localized (char const *gname, char const *lname);
 267 GnmFunc    *gnm_func_lookup_or_add_placeholder (char const *name);
 268
 269 /* TODO */
 270 char const *gnm_func_get_description (GnmFunc *func);
 271 void        gnm_func_count_args    (GnmFunc *func, gint *min, int *max);
 272 char        gnm_func_get_arg_type  (GnmFunc *func, gint arg_idx);
 273 char const *gnm_func_get_arg_type_string  (GnmFunc *func, gint arg_idx);
 274 char       *gnm_func_get_arg_name  (GnmFunc const *func, guint arg_idx);
 275 char const *gnm_func_get_arg_description (GnmFunc *func, guint arg_idx);
 276 char       *gnm_func_convert_markup_to_pango (char const *desc,
 277                                               GtkWidget *target);
 278
 279 /*************************************************************************/
 280
 281 GnmValue *function_call_with_exprs      (GnmFuncEvalInfo *ei);
 282 GnmValue *function_call_with_values     (GnmEvalPos const *ep, char const *name,
 283                                          int argc, GnmValue const * const *values);
 284 GnmValue *function_def_call_with_values (GnmEvalPos const *ep, GnmFunc const *fn,
 285                                          int argc, GnmValue const * const *values);
 286
 287 /* Utilies to interate through ranges and argument lists */
 288 typedef GnmValue * (*FunctionIterateCB) (GnmEvalPos const *ep, GnmValue const *value,
 289                                          gpointer user_data);
 290 GnmValue *function_iterate_argument_values (GnmEvalPos const *ep,
 291                                             FunctionIterateCB callback,
 292                                             gpointer callback_closure,
 293                                             int argc,
 294                                             GnmExprConstPtr const *argv,
 295                                             gboolean strict,
 296                                             CellIterFlags iter_flags);
 297
 298 /*************************************************************************/
 299
 300 struct _GnmFuncEvalInfo {
 301         GnmEvalPos const *pos;
 302         GnmExprFunction const *func_call;
 303         GnmExprEvalFlags flags;
 304 };
 305
 306 GnmFunc const *gnm_eval_info_get_func (GnmFuncEvalInfo const *ei);
 307 int gnm_eval_info_get_arg_count (GnmFuncEvalInfo const *ei);
 308
 309 /*************************************************************************/
 310
 311 GnmExpr const *gnm_func_derivative (GnmFunc *func,
 312                                     GnmExpr const *expr, GnmEvalPos const *ep,
 313                                     GnmExprDeriv *info);
 314
 315
 316 G_END_DECLS
 317
 318 #endif /* _GNM_FUNC_H_ */