--- /dev/null
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id BD39A431FC4\r
+ for <notmuch@notmuchmail.org>; Thu, 12 Jul 2012 13:29:39 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id HitGYQWVtJaO for <notmuch@notmuchmail.org>;\r
+ Thu, 12 Jul 2012 13:29:38 -0700 (PDT)\r
+Received: from dmz-mailsec-scanner-5.mit.edu (DMZ-MAILSEC-SCANNER-5.MIT.EDU\r
+ [18.7.68.34])\r
+ by olra.theworths.org (Postfix) with ESMTP id 00F45431FAF\r
+ for <notmuch@notmuchmail.org>; Thu, 12 Jul 2012 13:29:37 -0700 (PDT)\r
+X-AuditID: 12074422-b7f1f6d00000090b-e9-4fff33b1be8c\r
+Received: from mailhub-auth-2.mit.edu ( [18.7.62.36])\r
+ by dmz-mailsec-scanner-5.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id F6.03.02315.1B33FFF4; Thu, 12 Jul 2012 16:29:37 -0400 (EDT)\r
+Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
+ by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id q6CKTaWK011245; \r
+ Thu, 12 Jul 2012 16:29:37 -0400\r
+Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
+ (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q6CKTYir001950\r
+ (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+ Thu, 12 Jul 2012 16:29:35 -0400 (EDT)\r
+Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.77)\r
+ (envelope-from <amdragon@mit.edu>)\r
+ id 1SpQ10-0004fY-J8; Thu, 12 Jul 2012 16:29:34 -0400\r
+Date: Thu, 12 Jul 2012 16:29:34 -0400\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: craven@gmx.net\r
+Subject: Re: [PATCH v4 1/3] Add support for structured output formatters.\r
+Message-ID: <20120712202934.GG7332@mit.edu>\r
+References: <87d34hsdx8.fsf@awakening.csail.mit.edu>\r
+ <1342079004-5300-1-git-send-email-craven@gmx.net>\r
+ <1342079004-5300-2-git-send-email-craven@gmx.net>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\r
+Content-Disposition: inline\r
+In-Reply-To: <1342079004-5300-2-git-send-email-craven@gmx.net>\r
+User-Agent: Mutt/1.5.21 (2010-09-15)\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFmphleLIzCtJLcpLzFFi42IRYrdT0d1o/N/f4PN9GYu9De2MFtdvzmR2\r
+ YPJYvGk/m8ezVbeYA5iiuGxSUnMyy1KL9O0SuDJ+bnMt+KFT8WfmG+YGxvXKXYycHBICJhJf\r
+ t/9hg7DFJC7cWw9kc3EICexjlLjydAcrhLOBUWLGl0ZGCOckk8T/jd+hMksYJZo2/GAG6WcR\r
+ UJVYumES2Cw2AQ2JbfuXM4LYIgJCEpO+vGIBsZkFpCW+/W5mArGFBTwlTp1uBYvzCmhLTJ/X\r
+ xw4xdA6jxMTOR6wQCUGJkzOfQDVrSdz49xKomQNs0PJ/HCBhTgE7iVPT/4PtEhVQkZhychvb\r
+ BEahWUi6ZyHpnoXQvYCReRWjbEpulW5uYmZOcWqybnFyYl5eapGuqV5uZoleakrpJkZwYLso\r
+ 7WD8eVDpEKMAB6MSD+/OdX/9hVgTy4orcw8xSnIwKYnyagDjQogvKT+lMiOxOCO+qDQntfgQ\r
+ owQHs5IIb5YEUI43JbGyKrUoHyYlzcGiJM57LeWmv5BAemJJanZqakFqEUxWhoNDSYJXFWSo\r
+ YFFqempFWmZOCUKaiYMTZDgP0PBAkBre4oLE3OLMdIj8KUZFKXFecZCEAEgiozQPrheWeF4x\r
+ igO9IgzRzgNMWnDdr4AGMwENnvXzH8jgkkSElFQDo1YEn8IKh9+sEUbV1/ebrOrcFLLGR9Vj\r
+ c4HyOwFNh9MH+DseC6lGBuRx2b+b0mqz1fEw81busMCqgHvXFGdd+89+09nt/MPHuvMmVU/S\r
+ eLbHw7c7Z9NBM9/oGS8Tr4ndlXqRujTx+7fyDf0fV5m/dTM3vmzKaOR048IJkTlvyljWSRje\r
+ KTLuUWIpzkg01GIuKk4EAB0RSF0XAwAA\r
+Cc: notmuch@notmuchmail.org\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Thu, 12 Jul 2012 20:29:39 -0000\r
+\r
+Quoth craven@gmx.net on Jul 12 at 9:43 am:\r
+> This patch adds a new type sprinter_t, which is used for structured\r
+> formatting, e.g. JSON or S-Expressions. The structure printer is the\r
+> code from Austin Clements (id:87d34hsdx8.fsf@awakening.csail.mit.edu).\r
+> \r
+> The structure printer contains the following function pointers:\r
+> \r
+> /* start a new map/dictionary structure.\r
+> */\r
+> void (*begin_map) (struct sprinter *);\r
+> \r
+> /* start a new list/array structure\r
+> */\r
+> void (*begin_list) (struct sprinter *);\r
+> \r
+> /* end the last opened list or map structure\r
+> */\r
+> void (*end) (struct sprinter *);\r
+> \r
+> /* print one string/integer/boolean/null element (possibly inside a\r
+> * list or map\r
+> */\r
+> void (*string) (struct sprinter *, const char *);\r
+> void (*integer) (struct sprinter *, int);\r
+> void (*boolean) (struct sprinter *, notmuch_bool_t);\r
+> void (*null) (struct sprinter *);\r
+> \r
+> /* print the key of a map's key/value pair.\r
+> */\r
+> void (*map_key) (struct sprinter *, const char *);\r
+> \r
+> /* print a frame delimiter (such as a newline or extra whitespace)\r
+> */\r
+> void (*frame) (struct sprinter *);\r
+> \r
+> The printer can (and should) use internal state to insert delimiters and\r
+> syntax at the correct places.\r
+> \r
+> Example:\r
+> \r
+> format->begin_map(format);\r
+> format->map_key(format, "foo");\r
+> format->begin_list(format);\r
+> format->integer(format, 1);\r
+> format->integer(format, 2);\r
+> format->integer(format, 3);\r
+> format->end(format);\r
+> format->map_key(format, "bar");\r
+> format->begin_map(format);\r
+> format->map_key(format, "baaz");\r
+> format->string(format, "hello world");\r
+> format->end(format);\r
+> format->end(format);\r
+> \r
+> would output JSON as follows:\r
+> \r
+> {"foo": [1, 2, 3], "bar": { "baaz": "hello world"}}\r
+> ---\r
+> sprinter.h | 49 +++++++++++++++++++++++++++++++++++++++++++++++++\r
+> 1 file changed, 49 insertions(+)\r
+> create mode 100644 sprinter.h\r
+> \r
+> diff --git a/sprinter.h b/sprinter.h\r
+> new file mode 100644\r
+> index 0000000..1dad9a0\r
+> --- /dev/null\r
+> +++ b/sprinter.h\r
+> @@ -0,0 +1,49 @@\r
+> +#ifndef NOTMUCH_SPRINTER_H\r
+> +#define NOTMUCH_SPRINTER_H\r
+> +\r
+> +/* for notmuch_bool_t */\r
+\r
+Style/consistency nit: all of the comments should start with a capital\r
+letter and anything that's a sentence should end with a period (some\r
+of your comments do, some of them don't).\r
+\r
+> +#include "notmuch-client.h"\r
+> +\r
+> +/* Structure printer interface */\r
+> +typedef struct sprinter\r
+> +{\r
+> + /* start a new map/dictionary structure.\r
+\r
+This should probably mention how other functions should be called\r
+within the map structure. Perhaps,\r
+\r
+/* Start a new map/dictionary structure. This should be followed by a\r
+ * sequence of alternating calls to map_key and one of the value\r
+ * printing functions until the map is ended.\r
+ */\r
+\r
+(You had a comment to this effect in one of your earlier patches.)\r
+\r
+> + */\r
+> + void (*begin_map) (struct sprinter *);\r
+> +\r
+> + /* start a new list/array structure\r
+> + */\r
+> + void (*begin_list) (struct sprinter *);\r
+> +\r
+> + /* end the last opened list or map structure\r
+> + */\r
+> + void (*end) (struct sprinter *);\r
+> +\r
+> + /* print one string/integer/boolean/null element (possibly inside a\r
+> + * list or map\r
+\r
+Missing close paren.\r
+\r
+> + */\r
+> + void (*string) (struct sprinter *, const char *);\r
+> + void (*integer) (struct sprinter *, int);\r
+> + void (*boolean) (struct sprinter *, notmuch_bool_t);\r
+> + void (*null) (struct sprinter *);\r
+> +\r
+> + /* print the key of a map's key/value pair.\r
+> + */\r
+> + void (*map_key) (struct sprinter *, const char *);\r
+> +\r
+> + /* print a frame delimiter (such as a newline or extra whitespace)\r
+> + */\r
+> + void (*frame) (struct sprinter *);\r
+\r
+I wonder if frame is still necessary. At the time, I was thinking\r
+that we would use embedded newline framing to do streaming JSON\r
+parsing, but I wound up going with a general incremental JSON parser,\r
+eliminating the need for framing.\r
+\r
+It's probably still useful to have a function that inserts a newline\r
+purely for readability/debuggability purposes. In practice, the\r
+implementation would be the same as frame (though if it's for\r
+readability, maybe you'd want to print the comma before the newline\r
+instead of after), but since the intent would be different, it would\r
+need different documentation and maybe a different name. "Frame"\r
+isn't a bad name for either intent. We can't use "break".\r
+"Separator" (or just "sep")? "Space"? "Split"? The comment could be\r
+something like\r
+\r
+/* Insert a separator for improved readability without affecting the\r
+ * abstract syntax of the structure being printed. For JSON, this is\r
+ * simply a line break.\r
+ */\r
+\r
+> +} sprinter_t;\r
+> +\r
+> +/* Create a new structure printer that emits JSON */\r
+> +struct sprinter *\r
+> +sprinter_json_new(const void *ctx, FILE *stream);\r
+\r
+This should probably be called sprinter_json_create to be consistent\r
+with the naming of other constructors in notmuch.\r
+\r
+Also, missing space between the function name and parameter list\r
+(sorry, my fault).\r
+\r
+> +\r
+> +/* A dummy structure printer that signifies that standard text output is\r
+> + * to be used instead of any structured format.\r
+> + */\r
+> +struct sprinter *\r
+> +sprinter_text;\r
+\r
+It looks like you never assign anything to this pointer, so all of\r
+your tests against sprinter_text are equivalent to just checking for a\r
+NULL pointer. You could either just use NULL as the designated value\r
+for the text format, or you could use this global variable, but make\r
+it a struct sprinter instead of a struct sprinter *.\r
+\r
+Also, this can probably be a static declaration in notmuch-search.c.\r
+\r
+> +\r
+> +#endif // NOTMUCH_SPRINTER_H\r
projects / notmuch-archives.git / commitdiff