Changes between Version 5 and Version 6 of JsoCowan


Ignore:
Timestamp:
08/15/17 14:53:50 (6 weeks ago)
Author:
cowan
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • JsoCowan

    v5 v6  
    1 This library allows the creation and use of ''!JavaScript-style objects (JSOs)'', which are chained mappings, represented using a variant of alists, that map keys (which are symbols) to arbitrary values. 
     1This library allows the creation and use of ''!JavaScript-style objects (JSOs)'', which are chained mappings that map keys (which are symbols) to arbitrary values.  JSOs are represented using a variant of alists, but they are not compatible with alist procedures. 
    22 
    33When you create a JSO, you can specify a ''prototype JSO''. The recursive sequence of a JSO's prototype, the prototype of its prototype, and so on, is called the ''prototype chain''. If a JSO doesn't contain a particular key, the prototype chain will be searched for it. Modifications, however, are only applied to the JSO proper, never to anything along the prototype chain. Note that this value is not itself a JSO.  A JSO without a prototype chain is called a ''free JSO''. 
     
    66 
    77A JSO is represented as a Scheme pair whose car is the symbol `@` and whose cdr is the concatenation of zero or more two-element lists with another JSO or the empty list.  The first element of each two-element list is a symbol known as the ''key'' and the second element is an arbitrary Scheme object known as the ''value''.  Keys are tested for equality with `eqv?`.  It is no accident that the attribute list of an SXML element has the same representation as a JSO. 
    8  
    9 == Undefined value and null JSO == 
    10  
    11 `(jso-undef? `''obj''`)` 
    12  
    13 Returns `#t` if ''obj'' is the undefined value, and `#f` otherwise.  The undefined value is distinct in the sense of `eqv?` from every other Scheme object. 
    14  
    15 `jso-null?` 
    16  
    17 A variable whose value is ''the null JSO'', a unique free JSO with no keys or values.  It is an error to mutate the null JSO in any way. 
    18  
    19 (`jso-null? `''obj''`)` 
    20  
    21 Returns `#t` if ''obj'' is the null JSO and `#f` otherwise. 
    228 
    239== Constructors == 
     
    3117Creates a newly allocated JSO with the specified ''prototype'' (or a free JSO if ''prototype'' is the undefined value).  The key-value pairs of ''alist'' become the corresponding keys and values of the JSO. 
    3218 
     19`jso-null` 
     20 
     21A variable whose value is ''the null JSO'', a unique free JSO with no keys or values.  It is an error to mutate the null JSO in any way. 
     22 
    3323== Predicates == 
     24 
     25`(jso-undef? `''obj''`)` 
     26 
     27Returns `#t` if ''obj'' is the undefined value, and `#f` otherwise.  The undefined value is distinct in the sense of `eqv?` from every other Scheme object. 
    3428 
    3529`(jso? `''obj''`)` 
    3630 
    3731Returns `#t` if the car of ''jso'' is the symbol `@`, and `#f` otherwise.  The rest of the JSO is left unexamined. 
     32 
     33(`jso-null? `''obj''`)` 
     34 
     35Returns `#t` if ''obj'' is the null JSO and `#f` otherwise. 
    3836 
    3937`(jso-empty? `''jso''`)` 
     
    5149Searches ''jso'', including the prototype chain, for the key ''key'', invokes the procedure ''success'' on it, and returns the result.  If ''key'' is not found, invokes the thunk ''failure'' and returns the result.  If ''success'' is not specified, it is the identity function; if ''fail'' is not specified, it is a procedure that returns the undefined value. 
    5250 
     51`(jso-local-ref `''jso key'' [ ''failure'' [ ''success'' ] ]`)` 
     52 
     53The same as `jso-ref`, except that it does not search the prototype chain. 
     54 
    5355`(jso-size `''jso''`)` 
    5456 
    5557Returns the number of keys in ''jso'' as an exact integer.  The prototype chain is left unexamined. 
    5658 
    57 == Mutators == 
    58  
    59 `(jso-set! `''jso key value''`)` 
    60  
    61 Searches ''jso'' for the key ''key'', and if found changes its value to ''value''.  If ''key'' is not found, ''key'' and ''value'' are added as the last key before the prototype chain. The prototype chain is left unexamined.  Returns an undefined value (not necessarily ''the'' undefined value). 
    62  
    63 `(jso-delete! `''jso key'' ...`)` 
    64  
    65 Searches ''jso'' and removes all keys that are equal to any of the ''keys''. The prototype chain is left unexamined. Unknown keys are ignored.  Returns an undefined value (not necessarily ''the'' undefined value). 
    66  
    67 `(jso-delete-all! `''jso key-list''`)` 
    68  
    69 Does the same as `jso-delete!`, except that the keys to be deleted are specified as a list. 
    70  
    7159`(jso-prototype `''jso''`)` 
    7260 
    7361Returns the prototype of ''jso'', or the undefined value if ''jso'' is free. 
    74  
    75 `(jso-set-prototype! `''jso prototype''`)` 
    76  
    77 Replaces the prototype of ''jso'' with ''prototype''.  If ''prototype'' is the undefined value, ''jso'' becomes free.  Returns an undefined value (not necessarily ''the'' undefined value). 
    7862 
    7963== Conversions == 
     
    9579Creates a newly allocated alist whose key-value pairs are the keys and values of the JSO, including its prototype chain. 
    9680 
     81`(alist->jso `''alist''`)` 
     82 
     83Creates a free JSO whose keys and values are the key-value pairs of the alist.  If any key is not a symbol, an error is signaled. 
     84 
    9785== Copying, mapping, and folding == 
    9886 
     
    113101Returns a newly allocated JSO after applying ''proc'' to each key and value of ''jso''.  The prototype chains are shared. 
    114102 
    115 `(jso-map! `''proc jso''`)` 
    116  
    117 Mutates ''jso'' by applying ''proc'' to each value.  The prototype chain is left unexamined.  Returns an undefined value (not necessarily ''the'' undefined value). 
    118  
    119103`(jso-full-map `''proc jso''`)` 
    120104 
     
    128112 
    129113Applies ''proc'' to each key and value, including those in the prototype chain.  Returns an undefined value (not necessarily ''the'' undefined value). 
     114 
     115== Mutators == 
     116 
     117`(jso-set! `''jso key value''`)` 
     118 
     119Searches ''jso'' for ''key'', and if found changes its value to ''value''.  If ''key'' is not found, ''key'' and ''value'' are added as the last key before the prototype chain. The prototype chain is left unexamined.  Returns an undefined value (not necessarily ''the'' undefined value). 
     120 
     121`(jso-delete! `''jso key'' ...`)` 
     122 
     123Searches ''jso'' and removes all keys (and their values) that are equal to any of the ''keys''. The prototype chain is left unexamined. Unknown keys are ignored.  Returns an undefined value (not necessarily ''the'' undefined value). 
     124 
     125`(jso-delete-all! `''jso key-list''`)` 
     126 
     127Does the same as `jso-delete!`, except that the keys to be deleted are specified as a list. 
     128 
     129`(jso-set-prototype! `''jso prototype''`)` 
     130 
     131Replaces the prototype of ''jso'' with ''prototype''.  If ''prototype'' is the undefined value, ''jso'' becomes free.  Returns an undefined value (not necessarily ''the'' undefined value). 
     132 
     133`(jso-map! `''proc jso''`)` 
     134 
     135Mutates ''jso'' by applying ''proc'' to each value.  The prototype chain is left unexamined.  Returns an undefined value (not necessarily ''the'' undefined value). 
    130136 
    131137== Method calls == 
     
    147153Note that when discriminating between JSON values, they should be tested in the following order:  the empty list representing an empty JSON array, the null JSO representing JSON `null`, any other JSO representing a JSON object, and any other list representing a non-empty JSON array. 
    148154 
    149 `(json-encode-string `''string'' [ ''unicode?'' ]`)` 
     155`(json-escape-string `''string ascii?''`)` 
    150156 
    151 Inserts escapes into a plain Scheme string to make it a valid JSON string.  In particular, all characters that cannot appear directly in a JSON string, or that have single-character escape sequences, are escaped.  As JSON requires, characters larger than `#\xFFFF` are encoded as two consecutive `\u` sequences. 
     157Inserts JSON escapes into a plain Scheme string to make it a valid JSON string.  In particular, all characters that cannot appear directly in a JSON string, or that have single-character escape sequences, are escaped.  As JSON requires, characters larger than `#\xFFFF` are encoded as two consecutive `\u` sequences. 
    152158 
    153 If the ''unicode?'' argument is false or omitted, all non-ASCII characters are escaped. 
     159If the ''ascii?'' argument is true, all non-ASCII characters are also escaped. 
    154160 
    155 `(json-decode-string `''string''`)` 
     161`(json-unescape-string `''string''`)` 
    156162 
    157163Interprets all escape sequences in a valid JSON string and returns the result.  An error is signaled if a malformed escape sequence is found. 
    158164 
    159 `(json-write `''obj'' [ ''unicode?'' [ ''port'' ] ]`)` 
     165`(json-write `''obj options'' [ ''port'' ] ]`)` 
    160166 
    161 Output ''obj'' to ''port'' (which defaults to the value of `(current-output-port)`) in [https://tools.ietf.org/html/rfc7159 JSON format].  Exact rationals other than integers are converted to inexact numbers before being output.  The argument ''unicode?'' (which defaults to false) is passed to `json-string-decode` whenever a string is output.  The null JSO is output as the keyword `null`.  If ''obj'' is not a JSON value, an error is signaled before any output is done. 
     167Output ''obj'' to ''port'' (which defaults to the value of `(current-output-port)`) in [https://tools.ietf.org/html/rfc7159 JSON format].  Exact rationals other than integers are converted to inexact numbers before being output.  The null JSO is output as the keyword `null`.  If ''obj'' is not a JSON value, an error is signaled before any output is done. 
     168 
     169The ''options'' argument is a list of symbols.  The symbol `ascii` causes all non-ASCII characters in strings to be escaped.  The symbol `pretty` may cause the JSON to be pretty-printed.  All other symbols are implementation-dependent. 
    162170 
    163171`(json-read `[ ''prototype'' [ ''port'' ] ]`)` 
     
    165173Reads the [https://tools.ietf.org/html/rfc7159 JSON representation] of a JSON value from ''port'' (which defaults to the value of `(current-input-port)`) and returns the appropriate value.  Any leading whitespace is skipped. 
    166174  
    167 Integers are returned as exact numbers in accordance with Scheme rules; all other JSON numbers are returned as inexact numbers.  The keyword ''null'' is returned as the null JSO.  If the representation is not syntactically correct JSON, an error is signaled.  If the an end of file is read from ''port'', then if nothing has been read yet an end-of-file object is returned; otherwise, an error that satisfies `file-error?` is signaled. 
     175Integers are returned as exact numbers in accordance with Scheme rules; all other JSON numbers are returned as inexact numbers.  The keyword ''null'' is returned as the null JSO.  If the representation is not syntactically correct JSON, an error is signaled.  If an end of file is read from ''port'', then if nothing has been read yet an end-of-file object is returned; otherwise, an error is signaled. 
    168176 
    169177Any JSOs returned are created with ''prototype'', or as free JSOs if ''prototype'' is the undefined value or omitted.