3d/093c5df081c869aae31ad3d517fc6178a92275

   1 Return-Path: <craven@gmx.net>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id A94E3429E4A\r
   6         for <notmuch@notmuchmail.org>; Wed, 11 Jul 2012 01:25:25 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: 0.001\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=0.001 tagged_above=-999 required=5\r
  12         tests=[FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001]\r
  13         autolearn=disabled\r
  14 Received: from olra.theworths.org ([127.0.0.1])\r
  15         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  16         with ESMTP id Nkw0IEuP2GIO for <notmuch@notmuchmail.org>;\r
  17         Wed, 11 Jul 2012 01:25:22 -0700 (PDT)\r
  18 Received: from mailout-de.gmx.net (mailout-de.gmx.net [213.165.64.23])\r
  19         by olra.theworths.org (Postfix) with SMTP id 137A6429E3C\r
  20         for <notmuch@notmuchmail.org>; Wed, 11 Jul 2012 01:25:19 -0700 (PDT)\r
  21 Received: (qmail invoked by alias); 11 Jul 2012 08:25:14 -0000\r
  22 Received: from gw.arelion.cust.net.lagis.at (EHLO dodekanex.arelion.at)\r
  23         [83.164.197.182]\r
  24         by mail.gmx.net (mp037) with SMTP; 11 Jul 2012 10:25:14 +0200\r
  25 X-Authenticated: #201305\r
  26 X-Provags-ID: V01U2FsdGVkX1887tYf0eI8tllIWkVJ6Mvejk7/HvwFk7Ruqa/5x2\r
  27         jalLZfI1VUHSon\r
  28 Received: by dodekanex.arelion.at (Postfix, from userid 1000)\r
  29         id D4A4030313F; Wed, 11 Jul 2012 10:26:36 +0200 (CEST)\r
  30 From: <craven@gmx.net>\r
  31 To: notmuch@notmuchmail.org\r
  32 Subject: [PATCH v3 1/3] Add support for structured output formatters.\r
  33 Date: Wed, 11 Jul 2012 10:26:33 +0200\r
  34 Message-Id: <1341995195-2497-2-git-send-email-craven@gmx.net>\r
  35 X-Mailer: git-send-email 1.7.11.1\r
  36 In-Reply-To: <1341995195-2497-1-git-send-email-craven@gmx.net>\r
  37 References: <20120710191331.GE7332@mit.edu>\r
  38         <1341995195-2497-1-git-send-email-craven@gmx.net>\r
  39 MIME-Version: 1.0\r
  40 Content-Type: text/plain; charset=UTF-8\r
  41 Content-Transfer-Encoding: 8bit\r
  42 X-Y-GMX-Trusted: 0\r
  43 X-BeenThere: notmuch@notmuchmail.org\r
  44 X-Mailman-Version: 2.1.13\r
  45 Precedence: list\r
  46 List-Id: "Use and development of the notmuch mail system."\r
  47         <notmuch.notmuchmail.org>\r
  48 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  49         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  50 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  51 List-Post: <mailto:notmuch@notmuchmail.org>\r
  52 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  53 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  54         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  55 X-List-Received-Date: Wed, 11 Jul 2012 08:25:26 -0000\r
  56 \r
  57 This patch adds a new type structure_printer, which is used for\r
  58 structured formatting, e.g. JSON or S-Expressions.\r
  59 \r
  60 The structure contains the following function pointers:\r
  61 \r
  62 - initial_state: is called to create a state object, that is passed to\r
  63   all invocations. This should be used to keep track of the output file\r
  64   and everything else necessary to correctly format output.\r
  65 - map: is called when a new map (associative array, dictionary) is\r
  66   started. map_key and the primitives (string, number, bool) are used\r
  67   alternatingly to add key/value pairs. pop is used to close the map\r
  68   (see there). This function must return a nesting level identifier that\r
  69   can be used to close all nested structures (maps and lists), backing\r
  70   out to the returned nesting level.\r
  71 - list: is called when a new list (array, vector) is started. the\r
  72   primitives (string, number, bool) are used consecutively to add values\r
  73   to the list. pop is used to close the list. This function must return\r
  74   a nesting level identifier that can be used to close all nested\r
  75   structures (maps and lists), backing out to the returned nesting\r
  76   level.\r
  77 - map_key: is called to write the key of a key/value pair.\r
  78 - pop: is called to return to a given nesting level. All lists and maps\r
  79   with a deeper nesting level must be closed.\r
  80 - number, string, bool: output one element of the specific type.\r
  81 \r
  82 All functions should use state to insert delimiters etc. automatically\r
  83 when appropriate. State is a user-defined object/data that can contain\r
  84 arbitrary information. Initial state is constructed by a call to\r
  85 initial_state.\r
  86 \r
  87 Example:\r
  88 int top, one;\r
  89 top = map(state);\r
  90 map_key(state, "foo");\r
  91 one = list(state);\r
  92 number(state, 1);\r
  93 number(state, 2);\r
  94 number(state, 3);\r
  95 pop(state, one);\r
  96 map_key(state, "bar");\r
  97 map(state);\r
  98 map_key(state, "baaz");\r
  99 string(state, "hello world");\r
 100 pop(state, top);\r
 101 \r
 102 would output JSON as follows:\r
 103 \r
 104 {"foo": [1, 2, 3], "bar": { "baaz": "hello world"}}\r
 105 ---\r
 106  structured-output.h | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++\r
 107  1 file changed, 90 insertions(+)\r
 108  create mode 100644 structured-output.h\r
 109 \r
 110 diff --git a/structured-output.h b/structured-output.h\r
 111 new file mode 100644\r
 112 index 0000000..73029f1\r
 113 --- /dev/null\r
 114 +++ b/structured-output.h\r
 115 @@ -0,0 +1,90 @@\r
 116 +/* notmuch - Not much of an email program, (just index and search)\r
 117 + *\r
 118 + * Copyright © 2009 Carl Worth\r
 119 + *\r
 120 + * This program is free software: you can redistribute it and/or modify\r
 121 + * it under the terms of the GNU General Public License as published by\r
 122 + * the Free Software Foundation, either version 3 of the License, or\r
 123 + * (at your option) any later version.\r
 124 + *\r
 125 + * This program is distributed in the hope that it will be useful,\r
 126 + * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
 127 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
 128 + * GNU General Public License for more details.\r
 129 + *\r
 130 + * You should have received a copy of the GNU General Public License\r
 131 + * along with this program.  If not, see http://www.gnu.org/licenses/ .\r
 132 + *\r
 133 + * Author: Carl Worth <cworth@cworth.org>\r
 134 + */\r
 135 +\r
 136 +#include "notmuch-client.h"\r
 137 +\r
 138 +/* structured formatting, useful for JSON, S-Expressions, ...\r
 139 + *\r
 140 + * All functions should use state to insert delimiters\r
 141 + * etc. automatically when appropriate. State is a user-defined\r
 142 + * object/data that can contain arbitrary information. Initial state is\r
 143 + * constructed by a call to initial_state.\r
 144 + *\r
 145 + * Example:\r
 146 + * int top, one;\r
 147 + * top = map(state);\r
 148 + * map_key(state, "foo");\r
 149 + * one = list(state);\r
 150 + * number(state, 1);\r
 151 + * number(state, 2);\r
 152 + * number(state, 3);\r
 153 + * pop(state, one);\r
 154 + * map_key(state, "bar");\r
 155 + * map(state);\r
 156 + * map_key(state, "baaz");\r
 157 + * string(state, "hello world");\r
 158 + * pop(state, top);\r
 159 + *\r
 160 + * would output JSON as follows:\r
 161 + *\r
 162 + * {"foo": [1, 2, 3], "bar": { "baaz": "hello world"}}\r
 163 + */\r
 164 +typedef struct structure_printer {\r
 165 +    /* map: is called when a new map (associative array, dictionary) is\r
 166 +     * started. map_key and the primitives (string, number, bool) are\r
 167 +     * used alternatingly to add key/value pairs. pop is used to close\r
 168 +     * the map (see there). This function must return a nesting level\r
 169 +     * identifier number that can be used to close all nested structures\r
 170 +     * (maps and lists), backing out to the returned nesting level.\r
 171 +     */\r
 172 +    int (*map) (void *state);\r
 173 +\r
 174 +    /* list: is called when a new list (array, vector) is started. the\r
 175 +     * primitives (string, number, bool) are used consecutively to add\r
 176 +     * values to the list. pop is used to close the list. This function\r
 177 +     * must return a nesting level identifier number that can be used to\r
 178 +     * close all nested structures (maps and lists), backing out to the\r
 179 +     * returned nesting level.\r
 180 +     */\r
 181 +    int (*list) (void *state);\r
 182 +\r
 183 +    /* pop: is called to return to a given nesting level. All lists and\r
 184 +     * maps with a deeper nesting level must be closed.\r
 185 +     */\r
 186 +    void (*pop) (void *state, int level);\r
 187 +\r
 188 +    /* map_key: is called to write the key of a key/value pair.\r
 189 +     */\r
 190 +    void (*map_key) (void *state, const char *key);\r
 191 +\r
 192 +    /* number, string, bool: output one element of the specific type. */\r
 193 +    void (*number) (void *state, int val);\r
 194 +    void (*string) (void *state, const char *val);\r
 195 +    void (*bool) (void *state, notmuch_bool_t val);\r
 196 +\r
 197 +    /* initial_state: is called to create a state object, that is passed\r
 198 +     * to all invocations. This should be used to keep track of the\r
 199 +     * output file and everything else necessary to correctly format\r
 200 +     * output.\r
 201 +     */\r
 202 +    void *(*initial_state) (const struct structure_printer *sp,\r
 203 +                           FILE *output);\r
 204 +\r
 205 +} structure_printer_t;\r
 206 -- \r
 207 1.7.11.1\r
 208 \r