doc/mpdm_overview.txt

   1 MPDM overview
   2 =============
   3
   4 MPDM (Minimum Profit Data Manager) is a lightweight library that provides C
   5 programs with a rich set of useful data types as scalars, dynamic arrays
   6 or hashes, similar to those of the Perl language. Also, it contains a
   7 rudimentary garbage collector that alleviates the need to keep track of
   8 data no longer useful, as well as help for operating system abstraction
   9 and portability, regular expressions, string manipulation, character set
  10 conversions, localization and file I/O access.
  11
  12 Values
  13 ------
  14
  15 The basic unit of information under MPDM is the _value_. It's declared
  16 inside the C code as a variable of mpdm_t type:
  17
  18  /* a MPDM value, initialized as NULL */
  19  mpdm_t v = NULL;
  20
  21 MPDM values can be single or multiple ones. A single value is a scalar and
  22 contains meaning by itself; a multiple one contains one or more MPDM
  23 values, that can be accessed by different means, depending on its nature.
  24
  25 A value also has an internal reference count; when it's 0, the value is
  26 suitable for being swept by the garbage collector. The reference count of
  27 a value can be manipulated by calling mpdm_ref() and mpdm_unref() on it.
  28 Also, whenever a value is stored inside a multiple one, its reference count
  29 is automatically incremented, and decremented when deleted from it. All
  30 newly created values are unreferenced.
  31
  32 Scalars
  33 -------
  34
  35 The simplest scalar is a string one:
  36
  37  /* a scalar string MPDM value */
  38  mpdm_t v = MPDM_S(L"I'm a happy scalar");
  39
  40 The MPDM_S() macro creates an MPDM value from a dinamically allocated
  41 copy of a wide-character string. MPDM works internally with wide-character
  42 strings; though this can seem awkward, it's the only way to do character
  43 set manipulation (i.e. Unicode) correctly.
  44
  45 A more memory-efficient way of creating a string scalar from a literal
  46 string is using the MPDM_LS() macro:
  47
  48  /* another scalar string, this time storing the string directly */
  49  mpdm_t w = MPDM_LS(L"I'm also a happy scalar");
  50
  51 Both are semantically the same. Many string manipulation functions,
  52 however, return values of the first kind.
  53
  54 Creating values from integers and real numbers (doubles) is also easy:
  55
  56  /* a scalar value, from an integer */
  57  mpdm_t i = MPDM_I(16384);
  58
  59  /* another scalar, this time from a double */
  60  mpdm_t pi = MPDM_R(3.1416);
  61
  62 Again, those new values are stored as dinamically allocated wide-char
  63 strings, so they are no different from the first one.
  64
  65 Backwards, an MPDM value can always be converted to integer or real:
  66
  67  /* converts i to integer */
  68  int n = mpdm_ival(i);
  69
  70  /* converts pi to real */
  71  double d = mpdm_rval(pi);
  72
  73 Sometimes you don't have a wide-char string available, but a multibyte
  74 one. The handy macro MPDM_MBS() does the conversion for you:
  75
  76  /* create a value with the value of the HOME environment variable
  77     (no error condition checked) */
  78  mpdm_t home = MPDM_MBS(getenv("HOME"));
  79
  80 Take note that MPDM_MBS() relies on a correctly working locale subsystem
  81 for character set conversion.
  82
  83 There are many more value creation macros for scalars; see the reference
  84 documentation for further details.
  85
  86 Value sizes
  87 -----------
  88
  89 An MPDM value always have a size. For scalar values, the size is usually
  90 the length of its string representation. It's returned by the mpdm_size()
  91 function:
  92
  93  /* prints 6 */
  94  printf("%d\n", mpdm_size(pi));
  95
  96 The mpdm_size() function, when applied to arrays, returns the number of
  97 elements instead:
  98
  99  /* A new array */
 100  mpdm_t ary = MPDM_A(0);
 101
 102  /* two new values pushed */
 103  mpdm_push(ary, MPDM_LS(L"Hey!");
 104  mpdm_push(ary, MPDM_LS(L"You!");
 105
 106  /* prints 2 */
 107  printf("%d\n", mpdm_size(ary));
 108
 109 On hashes it's a little different, as mpdm_size() returns the number of
 110 _buckets_ in it, which is probably not very useful; this is a side effect
 111 of hashes being implemented as arrays. To avoid this, the mpdm_hsize()
 112 special function returns the number of key/value pairs stored in the hash:
 113
 114  /* a new hash */
 115  mpdm_t en2es = MPDM_H(0);
 116
 117  /* three new pairs added */
 118  mpdm_hset(en2es, MPDM_LS(L"monday"), MPDM_LS(L"lunes"));
 119  mpdm_hset(en2es, MPDM_LS(L"tuesday"), MPDM_LS(L"martes"));
 120  mpdm_hset(en2es, MPDM_LS(L"friday"), MPDM_LS(L"viernes"));
 121
 122  /* prints 3 */
 123  printf("%d\n", mpdm_hsize(en2es));
 124
 125  /* prints the number of buckets (probably 31) */
 126  printf("%d\n", mpdm_size(en2es));
 127
 128 Arrays
 129 ------
 130
 131 To be written.
 132
 133 Hashes
 134 ------
 135
 136 To be written.
 137
 138 The 'garbage collector'
 139 -----------------------
 140
 141 To be written.
 142
 143 Executable values
 144 -----------------
 145
 146 To be written.
 147
 148 Regular expressions
 149 -------------------
 150
 151 To be written.
 152
 153 File I/O
 154 --------
 155
 156 To be written.
 157
 158 Charset conversions
 159 -------------------
 160
 161 To be written.
 162
 163 Localization
 164 ------------
 165
 166 To be written.
 167
 168 Environment variables
 169 ---------------------
 170
 171 To be written.
 172
 173 MPDM_NULL_HASH
 174 ~~~~~~~~~~~~~~
 175
 176 To be written.
 177
 178 ----
 179 Angel Ortega <angel@triptico.com>