source: project/release/3/proplist/proplist-eggdoc.scm

Last change on this file was 6231, checked in by Kon Lovett, 13 years ago

Rmvd missing tests refs.

File size: 6.3 KB
Line 
1;;;; proplist-eggdoc.scm
2
3(use eggdoc)
4
5(define license #<<EOF
6Copyright (c) 2005, Kon Lovett.  All rights reserved.
7
8Permission is hereby granted, free of charge, to any person obtaining a
9copy of this software and associated documentation files (the Software),
10to deal in the Software without restriction, including without limitation
11the rights to use, copy, modify, merge, publish, distribute, sublicense,
12and/or sell copies of the Software, and to permit persons to whom the
13Software is furnished to do so, subject to the following conditions:
14
15The above copyright notice and this permission notice shall be included
16in all copies or substantial portions of the Software.
17
18THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
22OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
23ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
24OTHER DEALINGS IN THE SOFTWARE.
25EOF
26)
27
28(define doc `(
29        (eggdoc:begin
30                (name "proplist")
31                (description (p "Provides property list operations."))
32                (author (url "mailto:klovett@pacbell.net" "Kon Lovett"))
33                (history
34                        (version "1.7" "Last version - superseded by Chicken 2.7113 built-in support.")
35                        (version "1.6" "Equal & Member Procedure Procedure Parameters")
36                        (version "1.5" "Procedure slot support")
37                        (version "1.4" "Extra symbol slot support")
38                        (version "1.3" "Renamed get-properties, removed rem-properties[/all]!")
39                        (version "1.2" "Exports")
40                        (version "1.1" "\"Real\" property list")
41                        (version "1.0" "Initial release"))
42
43                (usage)
44                (download "proplist.egg")
45
46                (documentation
47
48                        (p "Proplist is a Lisp inspired set of procedures supporting property "
49                        "list operations. A property list is a list of key-value pairs arranged "
50                        "along the top-level spine of the list.")
51
52                        (p "A property list vs. an association list: PROPLIST - (key1 val1 key2 val2) "
53                        "ALIST - ((key1 val1) (key2 val2)).")
54
55                        (p "A " (tt "HANDLE") " may be a procedure, symbol, hash-table, or a "
56                        "property-list. See the " (code "proplist-extraslot") " and "
57                        (code "proplist-procslot") " parameters for Lisp-like property list "
58                        "attachment.")
59
60                        (p "A " (tt "PROPKEY") " can be any Scheme object, but matching depends "
61                        "on the " (code "proplist-equal") " and " (code "proplist-member") " "
62                        "parameters.")
63
64                        (p "Proplist supports the pre-2.2 CHICKEN \"disembodied\" property list "
65                        "functionality, when the " (tt "HANDLE") " is a hash-table. However, "
66                        "the original functions " (code "get") " and " (code "put!") " are not "
67                        "defined.")
68
69                        (subsection "Property list"
70
71                                (procedure "(proplist-procedure PROC)"
72                                        (p "Returns the extended procedure with an empty property list.") )
73
74                                (procedure "(getprop HANDLE PROPKEY [DEFAULT #f])"
75                                        (p "Returns the first property " (tt "PROPKEY") " value of "
76                                        (tt "HANDLE") ", or the optional " (tt "DEFAULT") ", when no such "
77                                        "property."))
78
79                                (procedure "(putprop! HANDLE [PROPKEY VALUE ...])"
80                                        (p "Adds the property " (tt "PROPKEY") " value of " (tt "HANDLE") " to "
81                                        "the supplied " (tt "VALUE") ". Does not replace an existing "
82                                        "property."))
83
84                                (procedure "(setprop! HANDLE [PROPKEY VALUE ...])"
85                                        (p "Sets the property " (tt "PROPKEY") " value of " (tt "HANDLE") " to "
86                                        "the supplied " (tt "VALUE") ". Replaces any existing property."))
87
88                                (procedure "(remprop! HANDLE [PROPKEY ...])"
89                                        (p "Removes the first property " (tt "PROPKEY") " of " (tt "HANDLE") "."))
90
91                                (procedure "(remprop/all! HANDLE [PROPKEY ...])"
92                                        (p "Removes every property " (tt "PROPKEY") " of " (tt "HANDLE") "."))
93
94                                (procedure "(proplist HANDLE [PROPKEY ...])"
95                                        (p "Returns the first property " (tt "PROPKEY") " value of "
96                                        (tt "HANDLE") " for every property key specified, as a property list. "
97                                        "All properties returned when no key specified."))
98
99                                (procedure "(proplist->alist HANDLE [PROPKEY ...])"
100                                        (p "Returns the first properties " (tt "PROPKEY ...") " key-value pairs "
101                                        "of " (tt "HANDLE") " as an association list. All properties when no "
102                                        "key specified."))
103
104                                (procedure "(proplist->alist ALIST [PROPKEY ...])"
105                                        (p "Returns the first properties " (tt "PROPKEY ..") " key-value pairs "
106                                        "of " (tt "ALIST") " as an asscociation list. All properties when no "
107                                        "key specified.") )
108                        )
109
110                        (subsection "Parameters"
111
112                                (parameter "(proplist-equal [PROC eq?])"
113                                        (p "Sets or gets the binary procedure for property key equality "
114                                        "testing. Ignored for a hash-table.") )
115
116                                (parameter "(proplist-member [PROC memq?])"
117                                        (p "Sets or gets the binary procedure for property key list "
118                                        "membership testing. Ignored for a hash-table.") )
119
120                                (parameter "(proplist-extraslot [FLAG])"
121                                        (p "The property list is sourced from the symbol extraslot when "
122                                        (tt "FLAG") " is " (code "#t") ". Should the symbol extraslot feature "
123                                        "not be available or the " (tt "FLAG") " is " (code "#f") " the "
124                                        "property list is found in " "a hash-table.") )
125
126                                (parameter "(proplist-procslot [FLAG])"
127                                        (p "The property list is sourced from the procedure extended data "
128                                        "when " (tt "FLAG") " is " (code "#t") ". Should the " (tt "FLAG") " "
129                                        "be " (code "#f") " the property list is found in a hash-table.")
130
131                                        (p "The procedure " (b "must") " be initialized before using as a "
132                                        "property list handle.")
133
134                                        (p "Example: " (code "(define foo (proplist-procedure (lambda () #t)))") ".") )
135                        )
136
137                        (subsection "Property list I/O"
138
139                                (p "Property list SRFI-10 support procedures.")
140
141                                (p "A reader-ctor is defined for the external text representation of "
142                                "a property list.")
143
144                                (procedure "(print-proplist HANDLE [PORT])"
145                                        (p "Writes the external text representation of the property list "
146                                        "for " (tt "HANDLE") " to the output " (tt "PORT") ". Port defaults to "
147                                        "the " (code "(current-output-port)") "."))
148
149                                (procedure "(set-proplist! HANDLE PROPLIST)"
150                                        (p "Sets the property list for " (tt "HANDLE") " to the supplied "
151                                        (tt "PROPLIST") ".")
152
153                                        (p "Though not an I/O operation this procedure is considered too "
154                                        "dangerous for regular use and buried in this section."))
155                        )
156                )
157                (section "License" (pre ,license)))
158        )
159  )
160
161(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.