(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.") (define doc `((eggdoc:begin (name "mw") (description (p "An interface to the MediaWiki API as used by Wikipedia")) (author "Tony Sidaway") (history (version "0.1" "Initial release") ) (usage) (p "The entire egg may be loaded as above, or individual modules may be loaded as needed.") (documentation (p "Provides a 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 for sending of such commands and the handling of the response" " from the API.") (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)") (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. Note: some commands such as login" " only work with POST.") ) (p "Returns the content of the response sent by the wiki. The format of this will" " depend 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")) (procedure "(default-headers-none)" (p "Set the default-headers parameter to an empty list")) (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 interface" (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.") (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. Note: some commands such as" " login only work with POST.") ) (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.") (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. Note: some commands such as" " login only work with POST.") ) (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."))) (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 sxcall 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.")) (procedure "(sx-warnings-ignore)" (p "Sets the sx-warning-handler parameter to a procedure that ignores warnings.")))) (section "Editing API" (p "(require-extension mw-edit)") (p "These procedures perform logins, logouts, edits and watchlist management") (procedure "(login credentials #!key wiki)" (p "Logs the user in to the wiki") (dl (dt "credentials") (dd "A procedure that expects to be given the URL of the wiki and returns" " two values: the username and password for that wiki") (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")) (p "A login is attempted. If it fails an appropriate error is thrown. The login" " API command requires the POST method, so the default-method parameter is ignored.")) (procedure "(logout #!key wiki)" (p "Logs the user out of the wiki.") (dl (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") ) ) (procedure "(edit title #!key section text appendtext prependtext summary minor notminor bot recreate createonly nocreate watchlist md5 captchaid captchaword undo undoafter wiki)" (p "General editing procedure") (dl (dt "title") (dd "The title of the page to edit") (dt "section") (dd "The section") (dt "text")(dd "Text to replace the text on the page or section") (dt "appendtext")(dd "Text to append to the text on the page or section") (dt "prependtext")(dd "Text to prepend to (place in front of) the text on" " the page or section") (dt "summary") (dd "The summary message for the edit. If section parameter is" " \"new\" then this will be the section title") (dt "minor") (dd "Force minor edit tag ignoring user preferences") (dt "notminor") (dd "Disable minor edit tag ignoring user preferences") (dt "bot")(dd "Place bot tag. Needed if your user has bot privileges") (dt "recreate")(dd "Force page recreation if it's been deleted") (dt "createonly")(dd "Signal error if page already exists") (dt "nocreate")(dd "Signal error if page doesn't exist") (dt "watchlist")(dd "Specify treatment of watchlist (watch, unwatch, preferences" " or nochange)") (dt "md5")(dd "md5 hash for content") (dt "captchaid")(dd "id of a previous captcha challenge") (dd "captchaword")(dd "response to the captcha challenge identified by captchaid") (dd "undo")(dd "Revision id to undo") (dd "undoafter")(dd "Undo all revisions from undo up to but not including this" " one. If not set, just undo one revision") (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") ) (p "The page is edited. The edit API command requires the POST method, so the" " default-method parameter is ignored.")) (procedure "(watch page #!key wiki method)" (p "Adds a page to the watchlist of the logged-in user") (dl (dt "page") (dd "The page to add") (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.") ) (p "Adds the page to the user's watchlist")) (procedure "(unwatch page #!key wiki method)" (p "Removes a page from the watchlist of the logged-in user") (dl (dt "page") (dd "The page to remove") (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.") ) (p "Removes the page from the user's watchlist")) #;(procedure "(send-email user subject contents #!key wiki)" (p "Sends an email to a user of the wiki") (dl (dt "user") (dd "The recipient of the email") (dt "subject")(dd "The subject of the email") (dt "contents")(dd "The contents of the email") (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")) (p "Sends the email if the user has enabled the email facility and site policy" " permits it. The emailuser API command requires use of the POST method, so this" " procedure ignores the default-method parameter." ))) (section "Formatting API" (p "(require-extension mw-format)") (p "These procedures perform basic MediaWiki formatting") (procedure "(wiki-list c)" (p "formats a list in for the wiki") (dl (dt "c")(dd "A vector or proper list containing items to be formatted")) (p "The formatted wikitext is returned") (p "This only handles lists of scalar values, and cannot format nested list" " structures")) (procedure "(wiki-list->list lines)" (p "Extracts text values from a wiki list") (dl (dt "lines") (dd "a proper list containing a formatted wikitext list")) (p "A list of strings is returned")) (procedure "(wiki-list->vector lines)" (p "Extracts text values from a wiki list") (dl (dt "lines") (dd "a proper list containing a formatted wikitext list")) (p "A vector of strings is returned")) (procedure "(page->user-list wiki-text)" (p "Extracts a list of usernames from a wikitext list") (dl (dt "wiki-text") (dd "A string containing a list")) (p "Removes any html comments, removes any lines preceding the list," " and extracts the usernames from resulting lines in the form" " \"User:XXX\"")) (procedure "(wiki-clean wiki-content" (p "Removes html comments from wiki-text") (dl (dt "wiki-content") (dd "String containing the wikitext")) (p "Returns a string containing the cleaned up wikitext")) (procedure "(remove-list-preamble wiki-lines)" (p "Removes lines that don't contain elements of a wiki-list. Used to remove" " the preamble or introductory text from the list") (dl (dt "wiki-lines")(dd "List of lines")) (p "Returns the list with the preamble removed")) (procedure "(wiki-heading level title)" (p "Formats a wiki section heading") (dl (dt "level")(dd "Level number of the heading") (dt "title")(dd "Title text for the heading")) (p "Returns the formatted heading")) (procedure "(write-wiki-page page content edit-summary)" (p "Writes a wiki page as a simple s-expression") (dl (dt "page")(dd "Page name") (dt "content")(dd "The content of the page") (dt "edit-summary")(dd "A descriptive summary")) (p "The return value is unspecified")) (procedure "(canonical-page-name pagename)" (p "Converts a pagename to the canonical MediaWiki form") (dl (dt "pagename") (dd "pagename to be converted")) (p "Replaced underscores with spaces in a pagename")) (procedure "(canonical-username username)" (p "An alias for canonical-page-name")) (procedure "(userspace-owner pagename)" (p "Derive the owner of a page in user or user talk namespace") (dl (dt "pagename") (dd "pagename in user or user talk namespace")) (p "Returns a username")) (procedure "(wiki-unlink link)" (p "Derive the target at which a wiki-link points") (dl (dt "link")(dd "A formatted wiki-link")) (p "Extracts the name of the wiki page to which a wiki-link" " will direct the brower if the link is clicked")) (procedure "(wiki-link line . opt)" (p "Format a wiki-link to a target, with an optional piped name") (dl (dt "link") (dd "The name of the target page") (dt "opt") (dd "If given, text to be shown instead of the name of the target")) (p "The formatted wiki-link is returned")) (procedure "(wiki-external link . opt)" (p "Format an external to a target, with an optional piped name") (dl (dt "link") (dd "The URL of the external target") (dt "opt") (dd "If given, text to be shown instead of the bracketed number" " that is shown by default for external links")) (p "The formatted external link is returned")) (procedure "(wiki-category name . opt)" (p "Format a category link with an optional piped sort") (dl (dt "link") (dd "The name of the category") (dt "opt") (dd "If given, text to be used for sorting in category" " displays, instead of using the default ordering.")) (p "Returns the formatted category reference")) (procedure "(interwiki iwiki name)" (p "Format an interwiki link") (dl (dt "iwiki")(dd "The interwiki signifier (eg: \"fr\" for French Wikipedia)") (dt "name")(dd "The target pagename on the target wiki")) (p "The formatted interwiki link is returned.")) (procedure "(wiki-bold text)" (p "Format bold wikitext") (dl (dt "text")(dd "The text to be made bold")) (p "The formatted wikitext is returned")) (procedure "(wiki-italics text)" (p "Format italicized wikitext") (dl (dt "text")(dd "The text to be italicized")) (p "The formatted wikitext is returned")) (procedure "(wiki-username wiki-content)" (p "Extract a username from wiki content") (dl (dt "wiki-content")(dd "The content to be analyzed")) (p "Returns the username")) ) (section "License" (pre ,license)))))) (eggdoc->html doc)