include/data.h

   1 /*
   2  * A general structure for extracting hierarchical data from the devices;
   3  * typically key-value pairs, but allows for more rich data as well.
   4  *
   5  * Copyright (C) 2015 by Erkki Seppälä <flux@modeemi.fi>
   6  *
   7  * This program is free software: you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation, either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #ifndef INCLUDE_DATA_H_
  22 #define INCLUDE_DATA_H_
  23
  24 #include <stdio.h>
  25
  26 typedef enum {
  27         DATA_DATA,              /* pointer to data is stored */
  28         DATA_INT,               /* pointer to integer is stored */
  29         DATA_DOUBLE,            /* pointer to a double is stored */
  30         DATA_STRING,            /* pointer to a string is stored */
  31         DATA_ARRAY,             /* pointer to an array of values is stored */
  32         DATA_COUNT,             /* invalid */
  33         DATA_FORMAT             /* indicates the following value is formatted */
  34 } data_type_t;
  35
  36 typedef struct data_array {
  37         int          num_values;
  38         data_type_t  type;
  39         void        *values;
  40 } data_array_t;
  41
  42 typedef struct data {
  43         char        *key;
  44         char        *pretty_key; /* the name used for displaying data to user in with a nicer name */
  45         data_type_t  type;
  46         char        *format; /* if not null, contains special formatting string */
  47         void        *value;
  48         struct data* next; /* chaining to the next element in the linked list; NULL indicates end-of-list */
  49 } data_t;
  50
  51 struct data_printer;
  52 extern struct data_printer data_json_printer;
  53 extern struct data_printer data_kv_printer;
  54 extern struct data_printer data_csv_printer;
  55
  56 /** Constructs a structured data object.
  57
  58     Example:
  59     data_make("key", "Pretty key", DATA_INT, 42,
  60               "others", "More data", DATA_DATA, data_make("foo", DATA_DOUBLE, 42.0, NULL),
  61               "zoom", NULL, data_array(2, DATA_STRING, (char*[]){"hello", "World"}),
  62               "double", "Double", DATA_DOUBLE, 10.0/3,
  63               NULL);
  64
  65     Most of the time the function copies perhaps what you expect it to. Things
  66     it copies:
  67     - string contents for keys and values
  68     - numerical arrays
  69     - string arrays (copied deeply)
  70
  71     Things it moves:
  72     - recursive data_t* and data_array_t* values
  73
  74     The rule is: if an object is boxed (look at the dmt structure in the data.c)
  75     and it has a array_elementwise_import in the same structure, then it is
  76     copied deeply. Otherwise, it is copied shallowly.
  77
  78     @param key Name of the first value to put in.
  79     @param pretty_key Pretty name for the key. Use "" if to omit pretty label for this field completely,
  80                       or NULL if to use key name for it.
  81     @param type Type of the first value to put in.
  82     @param ... The value of the first value to put in, follwed by the rest of the
  83                key-type-values. The list is terminated with a NULL.
  84
  85     @return A constructed data_t* object or NULL if there was a memory allocation error.
  86 */
  87 data_t *data_make(const char *key, const char *pretty_key, ...);
  88
  89 /** Constructs an array from given data of the given uniform type.
  90
  91     @param ptr The contents pointed by the argument are copied in.
  92
  93     @return The constructed data array object, typically placed inside a data_t or NULL
  94             if there was a memory allocation error.
  95 */
  96 data_array_t *data_array(int num_values, data_type_t type, void *ptr);
  97
  98 /** Releases a data array */
  99 void data_array_free(data_array_t *array);
 100
 101 /** Prints a structured data object as JSON to the given stream */
 102 void data_print(data_t *data, FILE* file, struct data_printer *printer, void *aux);
 103
 104 /** Releases a structure object */
 105 void data_free(data_t *data);
 106
 107 /** Construct auxiliary data for CSV construction
 108
 109     @param fields the list of fields to accept and expect. Array is copied, but the actual
 110                   strings not. The list may contain duplicates and they are eliminated.
 111     @param num_fields number of fields
 112
 113     @return The auxiliary data to pass along with data_csv_printer to data_print.
 114             You must release this object with data_csv_free once you're done with it.
 115 */
 116 void *data_csv_init(const char **fields, int num_fields);
 117
 118 /** Destructs auxiliary CSV data. */
 119 void data_csv_free(void *csv);
 120
 121 #endif // INCLUDE_DATA_H_