1ASON(3) User Manuals ASON(3)
2
6 ason - Overview of ASON/libason
7
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 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 { "foo": 6, "bar": 7 }
18 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 { "bar": 7, "foo": 6 }
25 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 { "foo": 6, "foo": 7 }
35 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 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 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 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 { "foo": 6, * }
60 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 { "foo": 6, * } | { "bar": 7, * }
66 And if you only wanted to look at objects in both categories:
68 { "foo": 6, * } & { "bar": 7, * }
70 = { "foo": 6, "bar": 7, * }
71 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 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 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
96 ason_read(3), ason_copy(3), ason_destroy(3), ason_asprint(3),
97 ason_iterators(3), ason_values(3), ason_inspect(3)
98
100 Casey Dahlin <casey.dahlin@gmail.com>
101Linux JANUARY 2014 ASON(3)