(use eggdoc) (define license "Copyright (c) 2007-2009 Tony Sidaway. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.") ; Various macros to do repetitive stuff that needs to be done in the eggdoc. (define-syntax wiki-method-warning (syntax-rules () ((_) '((dt "wiki") (dd "The full URL of the API page of the wiki. If not given," " the value of the default-wiki parameter will be assumed") (dt "method") (dd "POST or GET. If not given the value of the default-method" " parameter will be assumed. Some commands such as edit and send-mail will only" " work with the POST method.") )))) (define doc `((eggdoc:begin (name "mw-core") (description (p "A basic interface to the MediaWiki API as used by Wikipedia")) (author "Tony Sidaway") (history (version "0.2" "Move mw-raw and mw-sxml modules to mw-core egg") (version "0.1" "Initial release of mw") ) (usage) (p "The entire egg may be loaded as above, or individual modules may be loaded as needed.") (documentation (p "Provides a basic functional programming interface to the MediaWiki API as documented" " at " (a (@ (href "http://www.mediawiki.org/wiki/API")) "http://www.mediawiki.org/wiki/API")) (p "This egg provides a functional interface which can be used to search, read, edit," " and perform privileged functions on any wiki hosting a reasonably up-to-date" " version of MediaWiki") (p "The API is operated by sending commands via http to the API page of the wiki," " which is usually at an address of the form \"/w/api.php\", for instance" " \"http://en.wikipedia.org/w/api.php\" for English Wikipedia. This interface" " greatly eases the sending of such commands and the handling of the response" " from the API.") (p "Unless stated otherwise, the result of procedures is a list of SXML documents." " The choice of using lists is due to the batching methods employed by the API." " A procedure sx-select is provided to resolve selected result elements or" " attributes into tables, using xpath data selectors.") (p "NOTE: This egg should be used in compliance with the policies" " of the wiki it is used on. If your account is blocked or you lose privileges," " don't blame the software.") (section "Raw API" (p "(require-extension mw-raw)") (p "This low-level module handles communication with the wiki") (procedure "(raw-api-call command-parameters #!key wiki method)" (p "Send a command to the MediaWiki API and return the response as a string." " The command will be sent with http headers as specified by the" " default-headers parameter.") (dl (dt "command-parameters") (dd "An ALIST containing pairs of API command parameters" " to send to the API. If the format command parameter is not included" " the result will be in the default format (usually xml source formatted" " for display as a human-readable HTML page)") ,(wiki-method-warning) ) (p "Returns a string containing the content of the response sent by the wiki." " The format of this depends on the format command-parameter you sent to" " the wiki.") ) (procedure "(pipejoin c)" (p "Convert a vector or list of strings to a single string with text items separated" " by the \"|\" character") (p "This is useful for converting lists of items such as wiki page titles to the" " format required by the MediaWiki API.") (dl (dt "c") (dd "A list or vector containing the items to be joined")) (p "Returns a string containing the items all converted to strings and then" " joined together separated by a \"|\" character.") ) (parameter "default-method" (p "This parameter can be used to control the http method used to send a command" " in the absence of a method argument to an API call") (p "Initial value: GET")) (parameter "default-wiki" (p "This parameter can be used to control the URL to which a command is sent in" " the absence of a wiki argument to an API call") (p "Initial value: #f (it must be set to a valid URL before use)")) (parameter "default-headers" (p "This parameter can be used to control the http headers that are sent along" " with each command") (p "See the http-client egg for a description of the format and range of" " acceptable values for headers") (p "Initial value: ((accept-encoding . (gzip))) which instructs the API to send the" " response as gzip-encoded text, which is automatically inflated by this module.")) (procedure "(default-headers-gzip)" (p "Set the default-headers parameter to request gzip-encoding. Any previous" " value is lost. The return value of this procedure is unspecified.")) (procedure "(default-headers-none)" (p "Set the default-headers parameter to an empty list. Any previous value is" " lost. The return value is unspecified.")) (procedure "(mw:error loc msg . rest)" (p "Mainly for internal use.") (p "Raises a MediaWiki error") (dl (dt "loc") (dd "location, the procedure raising the error") (dt "msg") (dd "a message describing the error") (dt "rest") (dd "Other arguments") ) (p "A composite error of the types exn and mw:error is raised."))) (section "SXML module" (p "(require-extension mw-sxml)") (p "This module implements a SXML interface on top of mw-raw, converting all" " responses to SXML.") (subsection "SXML interface to API" (procedure "(sx-call command-parameters #!key wiki method)" (dl (dt "command-parameters") (dd "An ALIST containing pairs of API command" " parameters to send to the API. A format command-parameter should NOT" " be included. The module itself will add (format . xml) to all API calls" " to ensure that an XML response will be received.") ,(wiki-method-warning) ) (p "Returns a list of batches of xml response from the API, converted to SXML" " by ssax:xml->sxml.") (p "NOTE: in the case of queries and lists (API command parameter (action . query))" " the size of the response may be very large. This procedure will fetch all" " available data from the API, which may not be the most efficient use of" " memory or time. For an alternative, see the make-sx-call procedure.")) (procedure "(make-sx-call command-parameters #!key wiki method)" (dl (dt "command-parameters") (dd "An ALIST containing pairs of API command parameters to send to the API." " A format command parameter should NOT be included. The module itself" " will add (format . xml) to all API calls to ensure that an XML response" " will be received.") ,(wiki-method-warning) ) (p "Returns a thunk (a procedure with no arguments) which returns a single batch" " of responses from the API each time it is called. The size of each batch is" " controlled by the limit API command parameter in the API call (See " (a (@ (href "http://www.mediawiki.org/wiki/API:Query#Continuing_queries")) "the API documentation on continuing queries") " but you don't need to worry about the details, they're all taken care of" " by the module code.) For compatibility with sx-call, the result of each" " call to the thunk is enclosed in a single-item list so that it can be" " processed using identical code.") (p "This procedure can be used to obtain query responses from the API in small" " batches, saving memory and, in the case where processing is aborted before" " all data has been fetched, saving time.")) (procedure "(generate-query source query)" (p "Support \"generate\" syntax of API") (dl (dt "source")(dd "An ALIST representing a query which will be" " used to generate titles for this query. Alternatively" " a string representing a single title or a sequence of" " titles separated by pipe (\"|\") characters, or else" " a list headed by one of the keywords \"titles\", \"pageids\"," " or \"revids\", followed by titles or ids of pages of revisions") (dt "query")(dd "An ALIST representing a query which will be" " combined with the source to produce a generator query." " The query should not contain a \"titles\" clause or" " any other means of identifying the page titles, because" " the source argument is supposed to provide the" " list of titles to work on.")) (p "A new ALIST is returned representing a combination of source and" " query. The rules of the \"generate\" syntax are followed, but" " this does not guarantee that the combination will be accepted. See " (a (@ (href "http://www.mediawiki.org/wiki/API:Query#Generators")) " the API documentation") " for details."))) (subsection "Formatting results" (procedure "(sx-select sx-call-result data-selector-list)" (p "Formats a sx-call or make-sx-call result into tabular form") (dl (dt "sx-call-result") (dd "The batched list of sxml results from sx-call or a thunk created by" " make-sx-call") (dt "data-selector-list") (dd "A list of xpath descriptors each representing an entity or attribute" " value to be included in the selection. Instead of an xpath descriptor," " the procedure results returned by sx-call are also acceptable and will" " save time on successive calls.")) (p "Returns a selection of items as specified in the xpath descriptors, in the" " form of a row-column list. The list length will be the number of top-level" " elements returned by the original query and each item in the list will be a" " list of items as specified by the data-selector-list."))) (subsection "Predicates" (procedure "(sx-match-predicate match-string)" (p "Creates a predicate based on a sxpath string.") (dl (dt "match-string") (dd "An xpath string")) (p "This is used internally to construct the predicates sx-warnings? and sx-error?" " It will return #f if applied to a sxml document for which the result of the" " sxpath query is null.")) (procedure "(sx-warnings? sxml)" (dl (dt "sxml") (dd "A result returned by sx-call or by a thunk created by make-sx-call")) (p "Returns #f if there are no warnings from the API")) (procedure "(sx-error? sxml)" (dl (dt "sxml") (dd "A result returned by sx-call or by a thunk created by make-sx-call")) (p "Returns #f if there are no error messages from the API"))) (subsection "Handling API errors and warnings" (parameter "sx-error-handler" (p "This parameter specifies a procedure to be executed on encountering an API error." " The form of the procedure is as follows:") (p "(lambda (loc sxml-result) ...)") (dl (dt "loc") (dd "The location. The name of the procedure encountering the error.") (dt "sxml-result") (dd "Result. The SSAX-parsed API response")) (p "Initial value: a procedure that calls mw:error with a suitable error message")) (parameter "sx-warning-handler" (p "This parameter specifies a procedure to be executed on encountering API warnings." " The form of the procedure is as follows:") (p "(lambda (loc sxml-result) ...)") (dl (dt "loc") (dd "The location. The name of the procedure encountering the warnings.") (dt "sxml-result") (dd "Result. The SSAX-parsed API response")) (p "Initial value: a procedure that returns the sxml-result argument, effectively" " ignoring the API warnings.")) (procedure "(sx-warnings-strict)" (p "Sets the sx-warning-handler parameter to a procedure that calls mw:error" " with an appropriate error message. The return value is unspecified.")) (procedure "(sx-warnings-ignore)" (p "Sets the sx-warning-handler parameter to a procedure that ignores warnings." " The return value is unspecified.")) ) ) (section "License" (pre ,license)))))) (eggdoc->html doc)