JSOs
  1. JSOs
    1. Introduction
    2. Author
    3. License
    4. Requirements
    5. Usage
    6. Reference
      1. Basics
        1. make-jso
        2. jso?
        3. jso-undef?
        4. jso-ref
        5. jso-set!
        6. jso-remove!
        7. jso-proto
      2. Special values
        1. jso-value
        2. jso-set-value!
      3. Copiers
        1. jso-copy
        2. jso-full-copy
      4. Mappers
        1. jso-map
        2. jso-map!
        3. jso-for-each
        4. jso-full-map
        5. jso-full-for-each
      5. Method application
        1. jso-apply
        2. jso-apply/fallback

Introduction

This library allows the creation and use of JavaScript-style objects (JSOs), which are chained association lists that map keys (which must be symbols) to arbitrary values.

When 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 referenced JSO, never to anything along the prototype chain. An attempt to look up an unknown key returns a unique value known as the undefined value, which can be tested with jso-undef?. Note that this value is not itself a JSO.

A JSO is an ordinary Scheme association list with a special key in the first key-value pair. As long as this pair is left undisturbed, they can be searched with assq and the resulting pairs mutated with set-car! and set-cdr!. However, it is safer to use the jso-ref and jso-set! procedures instead.

Author

John Cowan

License

3-clause BSD

Requirements

None

Usage

 
(import jso)

Reference

Basics
make-jso
[procedure] (make-jso)
[procedure] (make-jso PROTO)

Constructs a new JSO. If PROTO is supplied, it must be a JSO and is used as the prototype for the new object.

jso?
[procedure] (jso? OBJ)

Returns true if OBJ is a JSO.

jso-undef?
[procedure] (jso-undef? OBJ)

Returns true if OBJ is the undefined value.

jso-ref
[procedure] (jso-ref JSO KEY)

Retrieves the value for KEY in JSO, or the undefined value if KEY is not found.

jso-set!
[procedure] (jso-set! JSO KEY VALUE)

Sets VALUE to be the value of KEY in JSO; the prototype chain is not searched.

jso-remove!
[procedure] (jso-remove! JSO KEY)

Removes KEY and the associated value from JSO. The prototype chain is not searched. Therefore, if the same key exists in the prototype chain, it will now be exposed. Attempts to remove nonexistent keys are ignored.

jso-proto
[procedure] (jso-proto jso)

Returns the JSO's prototype, or the undefined value if it has none.

Special values

In addition to key-value pairs, a JSO also has an associated special value, which is the undefined value by default but can be changed to be any Scheme object.

jso-value
[procedure] (jso-value JSO)

Returns the special value of JSO.

jso-set-value!
[procedure] (jso-set-value! JSO VALUE)

Sets the special value of JSO to VALUE.

Copiers
jso-copy
[procedure] (jso-copy JSO)

Returns a shallow copy of JSO that shares the same prototype chain.

jso-full-copy
[procedure] (jso-full-copy JSO)

Returns a shallow copy of JSO including the whole prototype chain. The old and the new JSOs share nothing.

Mappers

These all accept procedures which take two arguments, the key and the value respectively, and return the new value.

jso-map
[procedure] (jso-map PROC JSO)

Returns a new JSO after applying PROC to each key-value pair of JSO. The new and old JSOs share prototypes.

jso-map!
[procedure] (jso-map! PROC JSO)

Modifies JSO by applying PROC to each key-value pair of JSO. The prototype chain is left undisturbed.

jso-for-each
[procedure] (jso-for-each proc jso)

Executes PROC over all the key-value pairs of JSO. The returned values are ignored. The prototype chain is not processed.

jso-full-map
[procedure] (jso-full-map PROC JSO)

Returns a new JSO after applying PROC to each key-value pair of JSO including the whole prototype chain. The new and old JSOs share nothing.

Note that there is no jso-full-map!, on the principle that no standard JSO procedure makes a destructive change to the prototype chain.

jso-full-for-each
[procedure] (jso-full-for-each PROC JSO)

Executes PROC over all the key-value pairs of JSO, including the whole prototype chain. The returned values are ignored.

Method application
jso-apply
[procedure] (jso-apply JSO KEY . ARGS)

Applies the procedure (method) which is the value of KEY in JSO to JSO. Any trailing arguments are also passed.

jso-apply/fallback
[procedure] (jso-apply/fallback JSO KEY FALLBACK . ARGS)

Applies the procedure (method) which is the value of KEY in JSO to JSO. Any trailing arguments are also passed. If there is no such key, the fallback procedure is invoked instead.