You can edit this page using wiki syntax for markup.

Article contents:[[tags: egg]] == estraier-client [[toc:]] === Description A pure Scheme implementation of the [[http://fallabs.com/hyperestraier/index.html|Hyper Estraier]] [[http://fallabs.com/hyperestraier/nguide-en.html#protocol|P2P protocol]]. === Author [[/users/peter-bex|Peter Bex]] === Repository This egg is hosted on the CHICKEN Subversion repository: [[https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/estraier-client|https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/estraier-client]] If you want to check out the source code repository of this egg and you are not familiar with Subversion, see [[/egg-svn-checkout|this page]]. === Requirements Requires the [[http-client]], [[uri-common]] and [[intarweb]] eggs. === Documentation All procedures in {{estraier-client}} accept a base URI as their first argument. This can be either an [[uri-common]] object or a regular string representing an URI. This URI acts as the base URI for the server, which will get the master or node path appended. For example, the base uri {{http://admin:password@localhost:1978}} can be used both for master control commands as well as node commands. In case of a master command, it will be appended to so we get {{http://admin:password@localhost:1978/master?action=<command>}}. In case of a node command, it will get appended to with the node name so we get {{http://admin:password@localhost:1978/node/mynode/<command>}}. In error situations, this library will signal one of the following type of conditions: ; {{(exn estraier-client args)}} : Arguments are invalid ; {{(exn estraier-client auth)}} : Authentication failed ; {{(exn estraier-client perm)}} : Permission denied ; {{(exn estraier-client node)}} : Node does not exist ; {{(exn estraier-client server)}} : Internal server error === Node API ==== list-documents <procedure>(list-documents base-uri node #!key max prev)</procedure> List the documents known to the {{node}}. Returns a list of alists containing the system attributes of each node: {{@id}}, {{@uri}}, {{@digest}}, {{@cdate}}, {{@mdate}}, {{@adate}}, {{@title}}, {{@author}}, {{@type}}, {{@lang}}, {{@genre}}, {{@size}}, {{@weight}} and {{@misc}}. '''All attribute values are returned as plain strings'''. The {{max}} argument controls the maximum number of results returned by this procedure. It defaults to 10. To get the next set of results, supply the {{prev}} option. Its value should be the value of the {{@uri}} attribute of the last document in the previous result set. ==== put-document <procedure>(put-document base-uri node contents attribs)</procedure> Store a new document, or replace an existing document at {{node}}. {{contents}} is a list of strings representing lines in the document. {{attribs}} is an alist of document attributes. The {{@uri}} attribute must be present or the document will '''not''' be stored! If the {{@uri}} is identical to an existing document, it is replaced. Example: <enscript highlight=scheme> (put-document "http://admin:admin@localhost:1978" "testnode" '("Hello there, this is another quick test") '((@uri . "test1"))) </enscript> ==== update-attributes <procedure>(update-attributes base-uri node attribs)</procedure> Update an existing document's attributes at the given {{node}}. {{attribs}} is an alist containing the new attributes for the document. The document is identified by the {{@uri}} attribute. The attributes in the document are completely replaced by {{attribs}}. This means that any attributes existing in the document but missing from {{attribs}} will be removed from the document. <enscript highlight=scheme> (update-attributes "http://admin:admin@localhost:1978" "testnode" '((@uri . "test1") (my-attribute . "some-value"))) </enscript> ==== delete-document <procedure>(delete-document base-uri node #!key id uri)</procedure> Delete the document identified by {{id}} or {{uri}} at {{node}}. You must supply one of {{id}} or {{uri}}, but not both. ==== find-documents <procedure>(find-documents base-uri node #!key phrase attr-phrases order max skip distinct depth wwidth hwidth awidth options auxiliary mask)</procedure> Search for documents, using the options provided. If {{phrase}} is not supplied and {{attr-phrases}} is an empty list, zero documents are returned. Otherwise, {{phrase}} and {{attr-phrases}} must ''all'' match a document in order for it to be returned. In other words, {{phrase}} is ANDed with all the {{attr-phrases}}. The keys have the following meaning: ; {{phrase}} : This is the search phrase which is matched against the documents (a string) ; {{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. ; {{order}} : The order in which the results should be returned (a string). ; {{max}} : The maximum number of results returned (a number). If not supplied, it defaults to 10. ; {{skip}} : The number of documents to skip in the result set (a number). Defaults to 0. ; {{distinct}} : The attribute name on which to filter distinctly (a symbol or string). ; {{depth}} : The depth of the meta-search (a number). Defaults to 0. ; {{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. ; {{hwidth}} : The width of strings (in characters) in the snippet in the beginning of the text (a number). Default depends on server configuration. ; {{awidth}} : The width of strings (in characters) around the snipper (a number). Default depends on server configuration. ; {{options}} : Options for the search condition. (TODO) ; {{auxiliary}} : Permission to adopt result of the auxiliary index (a number). By default, it is 32. (TODO) ; {{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) See the [[http://fallabs.com/hyperestraier/uguide-en.html#searchcond|documentation for search conditions]] for information on the syntax of {{phrase}}, {{attr-phrases}} and {{order}}. This procedure returns two values. The first value is a list containing the documents (the actual search results), the second value is a list with meta-information about the search result set. The documents are pairs with the matched snippets (a list of pairs) as car and the attributes (an alist) as cdr. The car of a snippet is either a string to be highlighted (the part of the string that was in the search phrase) or {{#f}} if no appropriate highlighting can be made. The cdr of a snippet is a matched string. Example: <enscript highlight=scheme> (put-document "http://admin:admin@localhost:1978" "testnode" '("Hello there, this is another quick test") '((@uri . "test1"))) (find-documents "http://admin:admin@localhost:1978" "testnode" phrase: "quick test") => ((((#f . "Hello there, this is another ") ("quick test" . "quick test")) (#nodelabel . "testnode") (#nodescore . "10758") (#nodeurl . "http://localhost:1978/node/testnode") (@digest . "ec0e90969320452b97f55f97ad3a5cc7") (@id . "8") (@uri . "test1"))) ((VERSION "1.0") (NODE "http://localhost:1978/node/testnode") (HIT "1") (HINT#1 "test" "1") (DOCNUM "1") (WORDNUM "8") (TIME "0.004907") (TIME#i "0.000597") (TIME#0 "0.000749") (LINK#0 "http://localhost:1978/node/testnode" "testnode" "10000" "1" "8" "9129518" "1") (VIEW "SNIPPET")) </enscript> ==== get-document <procedure>(get-document base-uri node #!key id uri)</procedure> Fetch the document identified by {{id}} or {{uri}} at {{node}}. You must supply one of {{id}} or {{uri}}, but not both. Returns two values: the document's contents (a list of strings, representing lines in the document) and the document's attributes (an alist with symbols as keys and strings as values). Example: <enscript highlight=scheme> (get-document "http://admin:admin@localhost:1978" "testnode" uri: "test1") => ("Hello there, this is another quick test") ((#nodelabel . "testnode") (#nodeurl . "http://localhost:1978/node/testnode") (@digest . "34736f47d003748e7c6896a5931070dc") (@id . "8") (@uri . "test1")) </enscript> ==== document-attribute <procedure>(document-attribute base-uri node attrib #!key id uri)</procedure> Fetch the attribute with name {{attrib}} from the document identified by {{id}} or {{uri}} at {{node}}. You must supply one of {{id}} or {{uri}}, but not both. {{attrib}} may be either a symbol or a string. This procedure returns a string with the attribute's contents. '''Note:''' If the attribute does not exist, an exception of type {{(exn estraier-client args)}} is thrown. Example: <enscript highlight=scheme> (document-attribute "http://admin:admin@localhost:1978" "testnode" '@digest uri: "test1") => "34736f47d003748e7c6896a5931070dc" </enscript> ==== document-keywords <procedure>(document-keywords base-uri node #!key id uri)</procedure> Fetch the keywords that belong to the document identified by {{id}} or {{uri}} at {{node}}. You must supply one of {{id}} or {{uri}}, but not both. Returns a list of pairs. The car is a string with the keyword, the cdr is a number representing the keyword's assigned score. Example: <enscript highlight=scheme> (document-keywords "http://admin:admin@localhost:1978" "testnode" uri: "test1") => (("another" . 7882) ("there" . 1) ("," . 1) ("this" . 1) ("is" . 1) ("quick" . 1) ("hello" . 1) ("test" . 1)) </enscript> ==== document-uri->id <procedure>(document-uri->id base-uri node uri)</procedure> Look up the ID of a document by its {{uri}} at {{node}}. Returns a string with the document's ID. Example: <enscript highlight=scheme> (document-uri->id "http://admin:admin@localhost:1978" "testnode" "test1") => "8" </enscript> ==== register-admin-user <procedure>(register-admin-user base-uri node name)</procedure> Register the user with the given {{name}} to be an admin for {{node}}. This does not affect the user's guest status. ==== register-guest-user <procedure>(register-guest-user base-uri node name)</procedure> Register the user with the given {{name}} to be a guest for {{node}}. This does not affect the user's admin status. ==== unregister-user <procedure>(register-guest-user base-uri node name)</procedure> Remove a user with the given {{name}} from the {{node}}'s list of known users. ==== get-node-info <procedure>(get-node-info base-uri node)</procedure> Get information about the given {{node}}. Returns an alist containing the following keys: ; {{name}} : The name of the node (string) ; {{label}} : The label of the node (string) ; {{document-count}} : The number of documents in the node's database (number) ; {{word-count}} : The number of unique words in the node's database (number) ; {{size}} : The size of the node's database (number) (in bytes?) ; {{admin-users}} : The names of the users that are admin to this node (list of strings) ; {{guest-users}} : The names of the users that are guests to this node (list of strings) ==== get-cache-usage <procedure>(get-cache-usage base-uri node)</procedure> Get the cache usage for the given {{node}}. Returns a number that indicates the cache size (in bytes?). ==== optimize-node <procedure>(optimize-node base-uri node)</procedure> Optimize the {{node}}'s database. ==== sync-node <procedure>(sync-node base-uri node)</procedure> Synchronize updating of the {{node}}'s database. If you do not perform this, search results or listings might not include all the latest additions to the database. === Master API ==== list-nodes <procedure>(list-nodes base-uri)</procedure> List all nodes known to the node master. Returns a list of node info alists. Each node info alist contains the following symbolic keys: ; {{name}} : The name of the node (string) ; {{label}} : The label of the node (string) ; {{document-count}} : The number of documents in the node's database (number) ; {{word-count}} : The number of unique words in the node's database (number) ; {{size}} : The size of the node's database (number) (in bytes?) ==== add-node <procedure>(add-node base-uri name [label])</procedure> Create a new node server with the given {{name}} and {{label}} and add it to the master's pool of nodes. If {{label}} is omitted, it defaults to {{name}}. ==== delete-node <procedure>(delete-node base-uri name)</procedure> Delete the node server identified by {{name}} from the master's pool of nodes. This action destroys the node and all its contents. ==== clear-node <procedure>(clear-node base-uri name)</procedure> Remove all documents from the node identified by {{name}}. ==== list-users <procedure>(list-users base-uri)</procedure> List all users known to the master. Returns a list of user info alists. Each user info alist contains the following symbolic keys: ; {{name}} : The name of the user ; {{password}} : The encrypted password ; {{flags}} : The user flags. The string contains "b" if the user is banned or "s" if it is a superuser. ; {{fullname}} : The full name of the user. ; {{misc}} : Miscellaneous information about the user. All values are strings. ==== add-user <procedure>(add-user base-uri username password #!key flags fullname misc)</procedure> Add a user with the given {{username}} and {{password}} to the master. The optional {{flags}} key is a string containing a "b" if the user is to be banned or an "s" if the user is to be a superuser. The {{fullname}} specifies the user's full name and {{misc}} specifies miscellaneous information about the user. ==== delete-user <procedure>(delete-user base-uri username)</procedure> Delete the user with the given {{username}} from the master. ==== shutdown-master <procedure>(shutdown-master base-uri)</procedure> Shutdown the master server. ==== sync-all-nodes <procedure>(sync-all-nodes base-uri)</procedure> Synchronize databases of all nodes to disk. ==== backup-master <procedure>(backup-master base-uri)</procedure> Synchronize all databases to disk and make a full backup. ==== rotate-log <procedure>(rotate-log base-uri)</procedure> Rotate the master's log. === Other procedures These procedures are not likely to be very useful, but they are provided for completeness. ==== read-draft <procedure>(read-attributes inport)</procedure> Read a document in [[http://fallabs.com/hyperestraier/uguide-en.html#formats|"draft format"]] from the input-port {{inport}}. Returns two values: the document contents (a list of strings representing the lines in the docuemnt) and the document's attributes (an alist). ==== read-attributes <procedure>(read-attributes inport)</procedure> Like {{read-attributes}}, except this only reads the attributes and returns only one value: an alist with the attributes. ==== write-draft <procedure>(write-draft outport contents attributes)</procedure> Write out a document in [[http://fallabs.com/hyperestraier/uguide-en.html#formats|"draft format"]] to the specified output port {{outport}}. {{attributes}} is an alist with the attributes of the document, {{contents}} is a list of strings with the lines in the document. ==== write-attributes <procedure>(write-attributes outport attributes)</procedure> Like {{write-draft}}, except this only writes the attributes part (the "header", in a way) of the draft. === Changelog * 1.0 Port to CHICKEN 5. * 0.3.2 Fix tests to use {{utils}} to get {{system*}}. Add test for {{max}} argument for {{find-documents}}. * 0.3.1 Be more careful while running the tests (run on a nonstandard port to avoid collision with already running "live" estraier instances, error early when estmaster can't be invoked etc). * 0.3 Ensure it works in Chicken 4.6.3 (with new irregex/regex changes). Should also improve performance. * 0.2 Small but effective speed improvement * 0.1 Initial release === License Copyright (c) 2009-2018 Peter Bex All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Description of your changes:

I would like to authenticate

Spam control

What do you get when you add 12 to 19?