1ASON(3)                          User Manuals                          ASON(3)
2
3
4

NAME

6       ason - Overview of ASON/libason
7

DESCRIPTION

9       ASON  is an extension of JSON. Like JSON, ASON is a language for repre‐
10       senting data. However, ASON adds some important features to JSON.
11
12
13   ASON has a semantic
14       JSON has an object type, which represents data in a list  of  key-value
15       pairs. It might look like this:
16
17            { "foo": 6, "bar": 7 }
18
19       What  this might represent is somewhat intuitive to most programmers; a
20       mapping of string keys to (in this case) integer  values.  Most  higher
21       level  programming languages have a data type that represents this sort
22       of data. But consider the following:
23
24            { "bar": 7, "foo": 6 }
25
26       The JSON specification doesn't state if this value  is  different  from
27       the  last  one. That's because the JSON spec contains only a syntax; it
28       tells us that both of the examples so far are valid  JSON  but  doesn't
29       tell us anything more.  Intuitively most programmers would treat a key-
30       value store as order-independent, but JSON doesn't  say  regarding  its
31       object  type,  and there are applications which will allow order-depen‐
32       dent processing of JSON objects.  Now consider this example:
33
34            { "foo": 6, "foo": 7 }
35
36       Our intuition-guided programmer is  a  bit  more  hesitant  about  this
37       value.  Usually keys map to single values, but one-to-many dictionaries
38       are possible.  If order matters, then using the same  key  twice  could
39       have  all  sorts  of  additional meanings as well. Again, JSON tells us
40       only that the value above is valid JSON, nothing more.
41
42       ASON resolves these questions and others, because while JSON only  pro‐
43       vides  a  syntax, ASON provides a semantic; it specifies how values are
44       processed, not just what is and is not a value.
45
46
47   ASON can represent categories of values
48       JSON syntax lends itself to explicit values, whereas ASON  can  specify
49       categories or "patterns." It could be said that ASON relates to JSON in
50       the way that regular expressions relate to strings. Any valid string is
51       certainly  a valid regular expression; "cat" is valid, and so is /cat/,
52       but regular expressions can represent entire groups of strings, such as
53       /c[abc]t/.
54
55       ASON  aims  for similar expressive power. For example, representing all
56       objects with the key "foo" set to six, and  any  other  combination  of
57       keys and values, may be done as such:
58
59            { "foo": 6, * }
60
61       ASON  includes  a  series of operators for compositing such categorical
62       expressions. For example, if you wanted to also look at  objects  which
63       might have the key "bar" set to 7:
64
65            { "foo": 6, * } | { "bar": 7, * }
66
67       And if you only wanted to look at objects in both categories:
68
69            { "foo": 6, * } & { "bar": 7, * }
70            = { "foo": 6, "bar": 7, * }
71
72       In  this  last example we demonstrated two ASON expressions that repre‐
73       sent the same category. ASON's rules are complex enough that there  are
74       frequently multiple representations for the same value. The implementa‐
75       tion described here will always endeavor to reduce  ASON  values  to  a
76       simplest form.
77
78
79   libason
80       libason  is  a library for manipulating ASON values. Values are of type
81       ason_t, an opaque type which will always be handled through pointers by
82       the API user.  ason_t behaves as though it is immutable from the user's
83       perspective, but as values are created they may be reduced, so inspect‐
84       ing an ason_t value may reveal it to be structurally different from the
85       value that was entered.
86
87       ason_t values  are  created  with  ason_read(3),  can  be  copied  with
88       ason_copy(3), and are released with ason_destroy(3).  ason_read takes a
89       complicated variety of arguments that will allow you to  compose  other
90       ASON  values  and convert C values to ASON values. You can convert ASON
91       values  back  to   C   values   with   the   functions   described   in
92       ason_inspect(3).
93
94

SEE ALSO

96       ason_read(3),     ason_copy(3),    ason_destroy(3),    ason_asprint(3),
97       ason_iterators(3), ason_values(3), ason_inspect(3)
98

AUTHOR

100       Casey Dahlin <casey.dahlin@gmail.com>
101
102
103
104
105
106Linux                            JANUARY 2014                          ASON(3)
Impressum