source: project/wiki/eggref/4/estraier-client @ 15859

Last change on this file since 15859 was 15859, checked in by sjamaan, 10 years ago

Fix definition lists (silly wiki syntax tripped me up again!)

File size: 15.2 KB
Line 
1[[tags: egg]]
2
3== estraier-client
4
5[[toc:]]
6
7=== Description
8
9A pure Scheme implementation of the
10[[http://hyperestraier.sourceforge.net|Hyper Estraier]]
11[[http://hyperestraier.sourceforge.net/nguide-en.html#protocol|P2P protocol]].
12
13=== Author
14
15[[Peter Bex]]
16
17=== Requirements
18
19Requires the [[http-client]], [[uri-common]] and [[intarweb]] eggs.
20
21=== Documentation
22
23All procedures in {{estraier-client}} accept a base URI as their first
24argument.  This can be either an [[uri-common]] object or a regular
25string representing an URI.  This URI acts as the base URI for the
26server, which will get the master or node path appended.  For example,
27the base uri {{http://admin:password@localhost:1978}} can be used both
28for master control commands as well as node commands.  In case of a
29master command, it will be appended to so we get
30{{http://admin:password@localhost:1978/master?action=<command>}}. In
31case of a node command, it will get appended to with the node name so
32we get {{http://admin:password@localhost:1978/node/mynode/<command>}}.
33
34In error situations, this library will signal one of the following
35type of conditions:
36
37; {{(exn estraier-client args)}} : Arguments are invalid
38; {{(exn estraier-client auth)}} : Authentication failed
39; {{(exn estraier-client perm)}} : Permission denied
40; {{(exn estraier-client node)}} : Node does not exist
41; {{(exn estraier-client server)}} : Internal server error
42
43=== Node API
44
45==== list-documents
46
47<procedure>(list-documents base-uri node #!key max prev)</procedure>
48
49List the documents known to the {{node}}.  Returns a list of alists
50containing the system attributes of each node: {{@id}}, {{@uri}},
51{{@digest}}, {{@cdate}}, {{@mdate}}, {{@adate}}, {{@title}},
52{{@author}}, {{@type}}, {{@lang}}, {{@genre}}, {{@size}}, {{@weight}}
53and {{@misc}}.  '''All attribute values are returned as plain strings'''.
54
55The {{max}} argument controls the maximum number of results returned
56by this procedure.  It defaults to 10.  To get the next set of
57results, supply the {{prev}} option.  Its value should be the value of
58the {{@uri}} attribute of the last document in the previous result
59set.
60
61==== put-document
62
63<procedure>(put-document base-uri node contents attribs)</procedure>
64
65Store a new document, or replace an existing document at {{node}}.
66
67{{contents}} is a list of strings representing lines in the document.
68{{attribs}} is an alist of document attributes.  The {{@uri}}
69attribute must be present or the document will '''not''' be stored!
70If the {{@uri}} is identical to an existing document, it is replaced.
71
72Example:
73
74<enscript highlight=scheme>
75(put-document "http://admin:admin@localhost:1978" "testnode"
76              '("Hello there, this is another quick test") '((@uri . "test1")))
77</enscript>
78
79==== update-attributes
80
81<procedure>(update-attributes base-uri node attribs)</procedure>
82
83Update an existing document's attributes at the given {{node}}.
84{{attribs}} is an alist containing the new attributes for the
85document.  The document is identified by the {{@uri}} attribute.
86
87The attributes in the document are completely replaced by {{attribs}}.
88This means that any attributes existing in the document but missing
89from {{attribs}} will be removed from the document.
90
91<enscript highlight=scheme>
92(update-attributes "http://admin:admin@localhost:1978" "testnode"
93                  '((@uri . "test1") (my-attribute . "some-value")))
94</enscript>
95
96==== delete-document
97
98<procedure>(delete-document base-uri node #!key id uri)</procedure>
99
100Delete the document identified by {{id}} or {{uri}} at {{node}}.  You
101must supply one of {{id}} or {{uri}}, but not both.
102
103==== find-documents
104
105<procedure>(find-documents base-uri node #!key phrase attr-phrases order max skip distinct depth wwidth hwidth awidth options auxiliary mask)</procedure>
106
107Search for documents, using the options provided. If {{phrase}} is not
108supplied and {{attr-phrases}} is an empty list, zero documents are
109returned.  Otherwise, {{phrase}} and {{attr-phrases}} must ''all''
110match a document in order for it to be returned. In other words,
111{{phrase}} is ANDed with all the {{attr-phrases}}.  The keys have the
112following meaning:
113
114; {{phrase}} : This is the search phrase which is matched against the documents (a string)
115; {{attr-phrases}} : These are the search phrases which are matched against the document attributes (a list of strings). This list can contain up to 10 search conditions, but not more. It defaults to the empty list.
116; {{order}} : The order in which the results should be returned (a string).
117; {{max}} : The maximum number of results returned (a number). If not supplied, it defaults to 10.
118; {{skip}} : The number of documents to skip in the result set (a number). Defaults to 0.
119; {{distinct}} : The attribute name on which to filter distinctly (a symbol or string).
120; {{depth}} : The depth of the meta-search (a number).  Defaults to 0.
121; {{wwidth}} : The whole width (in characters) of search result snippets (a number).  Default depends on server configuration. If zero, no snippets are returned. If negative, whole documents are returned.
122; {{hwidth}} : The width of strings (in characters) in the snippet in the beginning of the text (a number). Default depends on server configuration.
123; {{awidth}} : The width of strings (in characters) around the snipper (a number). Default depends on server configuration.
124; {{options}} : Options for the search condition. (TODO)
125; {{auxiliary}} : Permission to adopt result of the auxiliary index (a number). By default, it is 32. (TODO)
126; {{mask}} : The mask of search targets (a number). 1 means the node itself, 2 means the first link, 4 means the second link, 8 means the third link, and power values of 2 and their summation compose the mask. (TODO)
127
128See the [[http://hyperestraier.sourceforge.net/uguide-en.html#searchcond|documentation for search conditions]] for information on the syntax of {{phrase}}, {{attr-phrases}} and {{order}}.
129
130This procedure returns two values.  The first value is a list
131containing the documents (the actual search results), the second value
132is a list with meta-information about the search result set.
133
134The documents are pairs with the matched snippets (a list of pairs) as
135car and the attributes (an alist) as cdr. The car of a snippet is
136either a string to be highlighted (the part of the string that was in
137the search phrase) or {{#f}} if no appropriate highlighting can be
138made.  The cdr of a snippet is a matched string.
139
140Example:
141
142<enscript highlight=scheme>
143(put-document "http://admin:admin@localhost:1978" "testnode"
144              '("Hello there, this is another quick test") '((@uri . "test1")))
145(find-documents "http://admin:admin@localhost:1978" "testnode"
146                phrase: "quick test")
147=>
148((((#f . "Hello there, this is another ") ("quick test" . "quick test"))
149  (#nodelabel . "testnode")
150  (#nodescore . "10758")
151  (#nodeurl . "http://localhost:1978/node/testnode")
152  (@digest . "ec0e90969320452b97f55f97ad3a5cc7")
153  (@id . "8")
154  (@uri . "test1")))
155((VERSION "1.0")
156 (NODE "http://localhost:1978/node/testnode")
157 (HIT "1")
158 (HINT#1 "test" "1")
159 (DOCNUM "1")
160 (WORDNUM "8")
161 (TIME "0.004907")
162 (TIME#i "0.000597")
163 (TIME#0 "0.000749")
164 (LINK#0 "http://localhost:1978/node/testnode" "testnode" "10000" "1" "8" "9129518" "1")
165 (VIEW "SNIPPET"))
166</enscript>
167
168==== get-document
169
170<procedure>(get-document base-uri node #!key id uri)</procedure>
171
172Fetch the document identified by {{id}} or {{uri}} at {{node}}.  You
173must supply one of {{id}} or {{uri}}, but not both.  Returns two
174values: the document's contents (a list of strings, representing lines
175in the document) and the document's attributes (an alist with symbols
176as keys and strings as values).
177
178Example:
179
180<enscript highlight=scheme>
181(get-document "http://admin:admin@localhost:1978" "testnode" uri: "test1")
182=>
183("Hello there, this is another quick test")
184((#nodelabel . "testnode")
185 (#nodeurl . "http://localhost:1978/node/testnode")
186 (@digest . "34736f47d003748e7c6896a5931070dc")
187 (@id . "8")
188 (@uri . "test1"))
189</enscript>
190
191==== document-attribute
192
193<procedure>(document-attribute base-uri node attrib #!key id uri)</procedure>
194
195Fetch the attribute with name {{attrib}} from the document identified
196by {{id}} or {{uri}} at {{node}}. You must supply one of {{id}} or
197{{uri}}, but not both. {{attrib}} may be either a symbol or a
198string. This procedure returns a string with the attribute's contents.
199
200'''Note:''' If the attribute does not exist, an exception of type
201{{(exn estraier-client args)}} is thrown.
202
203Example:
204
205<enscript highlight=scheme>
206(document-attribute "http://admin:admin@localhost:1978" "testnode"
207                    '@digest uri: "test1")
208=>
209"34736f47d003748e7c6896a5931070dc"
210</enscript>
211
212==== document-keywords
213
214<procedure>(document-keywords base-uri node #!key id uri)</procedure>
215
216Fetch the keywords that belong to the document identified by {{id}} or
217{{uri}} at {{node}}. You must supply one of {{id}} or {{uri}}, but not
218both.  Returns a list of pairs.  The car is a string with the keyword,
219the cdr is a number representing the keyword's assigned score.
220
221Example:
222
223<enscript highlight=scheme>
224(document-keywords "http://admin:admin@localhost:1978" "testnode" uri: "test1")
225=>
226(("another" . 7882)
227 ("there" . 1)
228 ("," . 1)
229 ("this" . 1)
230 ("is" . 1)
231 ("quick" . 1)
232 ("hello" . 1)
233 ("test" . 1))
234</enscript>
235
236==== document-uri->id
237
238<procedure>(document-uri->id base-uri node uri)</procedure>
239
240Look up the ID of a document by its {{uri}} at {{node}}.  Returns a
241string with the document's ID.
242
243Example:
244<enscript highlight=scheme>
245(document-uri->id "http://admin:admin@localhost:1978" "testnode" "test1")
246=>
247"8"
248</enscript>
249
250==== register-admin-user
251
252<procedure>(register-admin-user base-uri node name)</procedure>
253
254Register the user with the given {{name}} to be an admin for {{node}}.
255This does not affect the user's guest status.
256
257==== register-guest-user
258
259<procedure>(register-guest-user base-uri node name)</procedure>
260
261Register the user with the given {{name}} to be a guest for {{node}}.
262This does not affect the user's admin status.
263
264==== unregister-user
265
266<procedure>(register-guest-user base-uri node name)</procedure>
267
268Remove a user with the given {{name}} from the {{node}}'s list of
269known users.
270
271==== get-node-info
272
273<procedure>(get-node-info base-uri node)</procedure>
274
275Get information about the given {{node}}.  Returns an alist containing
276the following keys:
277
278; {{name}} : The name of the node (string)
279; {{label}} : The label of the node (string)
280; {{document-count}} : The number of documents in the node's database (number)
281; {{word-count}} : The number of unique words in the node's database (number)
282; {{size}} : The size of the node's database (number) (in bytes?)
283; {{admin-users}} : The names of the users that are admin to this node (list of strings)
284; {{guest-users}} : The names of the users that are guests to this node (list of strings)
285
286==== get-cache-usage
287
288<procedure>(get-cache-usage base-uri node)</procedure>
289
290Get the cache usage for the given {{node}}.  Returns a number that
291indicates the cache size (in bytes?).
292
293==== optimize-node
294
295<procedure>(optimize-node base-uri node)</procedure>
296
297Optimize the {{node}}'s database.
298
299==== sync-node
300
301<procedure>(sync-node base-uri node)</procedure>
302
303Synchronize updating of the {{node}}'s database. If you do not perform
304this, search results or listings might not include all the latest
305additions to the database.
306
307=== Master API
308
309==== list-nodes
310
311<procedure>(list-nodes base-uri)</procedure>
312 
313List all nodes known to the node master.  Returns a list of node info
314alists.  Each node info alist contains the following symbolic keys:
315
316; {{name}} : The name of the node (string)
317; {{label}} : The label of the node (string)
318; {{document-count}} : The number of documents in the node's database (number)
319; {{word-count}} : The number of unique words in the node's database (number)
320; {{size}} : The size of the node's database (number) (in bytes?)
321
322==== add-node
323
324<procedure>(add-node base-uri name [label])</procedure>
325
326Create a new node server with the given {{name}} and {{label}} and add
327it to the master's pool of nodes.  If {{label}} is omitted, it
328defaults to {{name}}.
329
330==== delete-node
331
332<procedure>(delete-node base-uri name)</procedure>
333
334Delete the node server identified by {{name}} from the master's pool
335of nodes.  This action destroys the node and all its contents.
336
337==== clear-node
338
339<procedure>(clear-node base-uri name)</procedure>
340
341Remove all documents from the node identified by {{name}}.
342
343==== list-users
344
345<procedure>(list-users base-uri)</procedure>
346
347List all users known to the master.  Returns a list of user info
348alists.  Each user info alist contains the following symbolic keys:
349
350; {{name}} : The name of the user
351; {{password}} : The encrypted password
352; {{flags}} : The user flags. The string contains "b" if the user is banned or "s" if it is a superuser.
353; {{fullname}} : The full name of the user.
354; {{misc}} : Miscellaneous information about the user.
355
356All values are strings.
357
358==== add-user
359
360<procedure>(add-user base-uri username password #!key flags fullname misc)</procedure>
361
362Add a user with the given {{username}} and {{password}} to the master.
363The optional {{flags}} key is a string containing a "b" if the user is
364to be banned or an "s" if the user is to be a superuser.  The
365{{fullname}} specifies the user's full name and {{misc}} specifies
366miscellaneous information about the user.
367
368==== delete-user
369
370<procedure>(delete-user base-uri username)</procedure>
371
372Delete the user with the given {{username}} from the master.
373
374==== shutdown-master
375
376<procedure>(shutdown-master base-uri)</procedure>
377
378Shutdown the master server.
379
380==== sync-all-nodes
381
382<procedure>(sync-all-nodes base-uri)</procedure>
383
384Synchronize databases of all nodes to disk.
385
386==== backup-master
387
388<procedure>(backup-master base-uri)</procedure>
389
390Synchronize all databases to disk and make a full backup.
391
392==== rotate-log
393
394<procedure>(rotate-log base-uri)</procedure>
395
396Rotate the master's log.
397
398
399=== Changelog
400
401* 0.1 Initial release
402
403
404=== License
405
406  Copyright (c) 2009, Peter Bex
407  All rights reserved.
408 
409  Redistribution and use in source and binary forms, with or without
410  modification, are permitted provided that the following conditions are
411  met:
412 
413  Redistributions of source code must retain the above copyright
414  notice, this list of conditions and the following disclaimer.
415 
416  Redistributions in binary form must reproduce the above copyright
417  notice, this list of conditions and the following disclaimer in the
418  documentation and/or other materials provided with the distribution.
419 
420  Neither the name of the author nor the names of its contributors may
421  be used to endorse or promote products derived from this software
422  without specific prior written permission.
423 
424  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
425  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
426  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
427  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
428  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
429  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
430  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
431  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
432  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
433  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
434  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
435  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.