Patch to add results for JSON operator examples

Started by Sehrope Sarkuniabout 12 years ago2 messagesdocs
Jump to latest
#1Sehrope Sarkuni
sehrope@jackdb.com

The attached patches adds an "Example Result" column to the json/jsonb
operators table[1]http://www.postgresql.org/docs/devel/static/functions-json.html that has the evaluated result of each example. I
think this makes it much easy to reason what each operator does. The
two patches are mutually exclusive and I recommend using the -better
patch.

The patches only touches the json and jsonb operators table, the
additional jsonb operators table is left without example results. All
the results for those examples are "true" so I don't think it's
needed. Maybe wouldn't hurt though.

[1]: http://www.postgresql.org/docs/devel/static/functions-json.html

The first file (docs-json-operator-example.diff) adds results for the
existing operator examples.

The other file (docs-json-operator-example-better.diff) replaces some
of the examples that return JSON objects so that the result is an
object (not a scalar). I like this one better.

For the operator examples that return json (as opposed to text), I
think the result should be a non-scalar. It makes it easier for
someone new reading the operator docs to understand which situations
they are used for.

For example, both of the following return "3" as a result but they
mean different things that are only apparent if you understand the
difference between the > and >> operators (ie look at the PG return
type).

=> SELECT x->'a'
-> , pg_typeof(x->'a')
-> , x->>'a'
-> , pg_typeof(x->>'a')
-> FROM (SELECT '{"a":3}'::json as x) t;
?column? | pg_typeof | ?column? | pg_typeof
----------+-----------+----------+-----------
3 | json | 3 | text
(1 row)

Whereas, the following clearly shows that it's returning an JSON
object with a PG type of json, not a scalar:

=> SELECT '{"a": {"b":"foo"}}'::json->'a';
?column?
-------------
{"b":"foo"}
(1 row)

A related thought is changing the scalar results for the remaining
examples to something other than a single digit integer. Again, this
is to avoid confusion as someone new looking at it may not immediately
understand that it's actually a text string. Either that or showing it
in quotes so that it's apparent that it's text and not a number.

Regards,
-- Sehrope Sarkuni
Founder & CEO | JackDB, Inc. | http://www.jackdb.com/

Attachments:

docs-json-operator-example.difftext/plain; charset=US-ASCII; name=docs-json-operator-example.diffDownload+7-0
docs-json-operator-example-better.difftext/plain; charset=US-ASCII; name=docs-json-operator-example-better.diffDownload+15-11
#2Bruce Momjian
bruce@momjian.us
In reply to: Sehrope Sarkuni (#1)
Re: Patch to add results for JSON operator examples

On Fri, Mar 28, 2014 at 03:51:47PM -0400, Sehrope Sarkuni wrote:

The attached patches adds an "Example Result" column to the json/jsonb
operators table[1] that has the evaluated result of each example. I
think this makes it much easy to reason what each operator does. The
two patches are mutually exclusive and I recommend using the -better
patch.

The patches only touches the json and jsonb operators table, the
additional jsonb operators table is left without example results. All
the results for those examples are "true" so I don't think it's
needed. Maybe wouldn't hurt though.

[1]: http://www.postgresql.org/docs/devel/static/functions-json.html

The first file (docs-json-operator-example.diff) adds results for the
existing operator examples.

The other file (docs-json-operator-example-better.diff) replaces some
of the examples that return JSON objects so that the result is an
object (not a scalar). I like this one better.

"Better" patch version applied. Thanks.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ Everyone has their own god. +

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs