Changeset 40085 in project


Ignore:
Timestamp:
05/12/21 11:39:20 (5 weeks ago)
Author:
felix winkelmann
Message:

mdh: final API revision, after more suggestions by kluk

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/mdh

    r40084 r40085  
    2929<procedure>(global GLOBAL)</procedure>
    3030
    31 Allocates a reference to a global persistent variable. The reference should
    32 be freed using `global-free` when it is no longer required. There may be multiple
     31Allocates a an object representing a global persistent variable. The object should
     32be freed using {{global-free}} when it is no longer required. There may be multiple
    3333references to the same global variable at the same time in existance. GLOBAL
    3434may be a string, symbol or number and will be converted to a string. The result
    35 of this a wrapper procedure, invoking this object with a (possibly
    36 empty) set of indices is equivalent to calling {{global-ref}}:
     35of {{global}} is a wrapper procedure, invoking it with a (possibly
     36empty) set of indices is creates a reference to a specific location than
     37cam be further accessed and queried.
    3738
    3839<enscript highlight="scheme">
    3940(define g (global "foo"))
    4041
    41 (global-set! g 123)
    42 (global-ref g) => "123"
    43 (g)            => "123"
    44 </enscript>
    45 
    46 A wrapper procedure also has a SRFI-17 setter procedure:
    47 
    48 <enscript highlight="scheme">
    49 (set! (g 1 2) "xxx")
    50 (g 1 2) => "xxx"
     42(global-set! (g) 123)
     43(global-ref (g)) => "123"
     44</enscript>
     45
     46Indices for as many as 10 dimensions may be given:
     47
     48<enscript highlight="scheme">
     49(global-set! (g 1 2) "xxx")
     50(global-ref (g 1 2)) => "xxx"
    5151</enscript>
    5252
    5353<procedure>(global-object X)</procedure>
    5454
    55 Returns the object reference contained in the wrapper procedure X or {{#f}},
    56 if X is not a wrapper procedure. If X is already a global object, it is
     55Returns the object contained in the global reference or wrapper procedure X or {{#f}},
     56if X is not related to a global. If X is already a global object, it is
    5757returned unchanged.
    5858
     
    6161Returns true if X is a global object record structure instance.
    6262
     63<procedure>(global-reference? X)</procedure>
     64
     65Returns true if X is a global object reference for a given location in the database.
     66
    6367<procedure>(global-name G)</procedure>
    6468
    6569Returns the name of the global object G.
    6670
    67 <procedure>(global-set! G VALUE INDEX ...)</procedure>
    68 
    69 Sets the value of the element of G represented by the given indices to VAL.
    70 VAL will be converted to a string before it is stored. INDEX may be a string,
     71<procedure>(global-reference-name GR)</procedure>
     72
     73Returns the name of the global addressed by the global reference GR.
     74
     75<procedure>(global-set! GR VALUE)</procedure>
     76
     77Sets the value of the element addressed by the global reference GR to VALUE.
     78VALUE will be converted to a string before it is stored. INDEX may be a string,
    7179symbol or number and will also be converted to string. If the element doesn't exist
    72 yet for G, then it is created.
    73 
    74 <procedure>(global-ref G INDEX ...)</procedure>
    75 
    76 Returns the value of global G at the given index. If no element exists at
    77 that position, then the empty string is returned.
    78 
    79 <procedure>(global-count G INDEX ...)</procedure>
    80 
    81 Returns the number of descendants of the node specified by the global variable
    82 and indices.
     80yet for G, then it is created. If GR refers to a global, then this is equivalent
     81to {{global-set! (GR) VALUE)}}.
     82
     83<procedure>(global-ref GR)</procedure>
     84
     85Returns the value of the element addressed by the global reference GR. If no
     86element exists at that position, then the empty string is returned.
     87
     88<procedure>(global-count GR)</procedure>
     89
     90Returns the number of descendants of the node specified by the global reference.
    8391
    8492<procedure>(global-free G)</procedure>
     
    8694Releases the storage required for the global object or wrapper procedure G.
    8795After using this procedure,
    88 referencing the database through G will signal an error.
    89 
    90 <procedure>(global-kill G INDEX ...)</procedure>
     96referencing the database through G or any global reference derived from it
     97will signal an error.
     98
     99<procedure>(global-kill GR)</procedure>
    91100
    92101Removes the given element and all its descendants from the database.
    93102
    94 <procedure>(global-next G INDEX ...)</procedure>
    95 
    96 Returns the next index for the last item addressed by the given indices.
    97 Pass the empty string as the final index if you want to obtain the first
     103<procedure>(global-next GR)</procedure>
     104
     105Returns the next index for the last item addressed by the given reference.
     106Use the empty string as the final index if you want to obtain the first
    98107valid index holding data. If no further index is defined, returns the
    99108empty string:
    100109
    101110<enscript highlight="scheme">
    102 (define g (global-object (global "foo")))
    103 (global-set! g "a" 1)
    104 (global-set! g "b" 2)
    105 (global-next g "")      => "1"
    106 (global-next g "1")     => "w"
    107 (global-next g "2")     => ""
    108 </enscript>
    109 
    110 <procedure>(global-previous G INDEX ...)</procedure>
     111(define g (global "foo"))
     112(global-set! (g 1) "a")
     113(global-set! (g 2) "b")
     114(global-next (g ""))      => "1"
     115(global-next (g "1"))     => "w"
     116(global-next (g "2"))     => ""
     117</enscript>
     118
     119<procedure>(global-previous GR)</procedure>
    111120
    112121Similar to {{global-next}} but retrieves the previous index.
    113122
    114 <procedure>(global-data G INDEX ...)</procedure>
    115 
    116 Returns a symbol or {{#f}} identifying the type of node addressed by the global G
    117 and the given indices.
     123<procedure>(global-data GR)</procedure>
     124
     125Returns a symbol or {{#f}} identifying the type of node addressed by the reference
     126GR.
    118127 
    119128* {{#f}}: element is undefined
     
    122131* {{branch}}: element has a value and descendants
    123132
    124 <procedure>(global-merge G1 INDICES1 G2 INDICES2)</procedure>
    125 
    126 Copies the element and all its descendants given by G2 and the list of indices INDICES2
    127 to the position identified by G1 and INDICES1.
     133<procedure>(global-merge GR1 GR2)</procedure>
     134
     135Copies the element and all its descendants given by the reference GR2
     136to the position identified by the reference GR1.
    128137
    129138<procedure>(^ NAME INDEX ...)</procedure>
     
    137146Equivalent to {{(global-set! (global NAME) VALUE INDEX ...)}} but takes care
    138147to free the wrapper object of the global reference properly after assigning
    139 the value. NAME may be a global object, a global wrapper procedure
    140 or a name that is converted to a string.
     148the value. NAME may be a global object or a name that is converted to a string.
    141149
    142150<procedure>(^order NAME INDEX ...)</procedure>
     
    149157These are all convenience procedures that perform the named operation
    150158with an existing global object or a temporarily allocated global reference if NAME
    151 is not a global wrapper or object.
     159is not a global object.
    152160
    153161<procedure>(flush-globals)</procedure>
Note: See TracChangeset for help on using the changeset viewer.