The rpc4cl Reference Manual

Table of Contents

The rpc4cl Reference Manual

This is the rpc4cl Reference Manual, version 0.3.2, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:31:44 2018 GMT+0.

1 Introduction

Rpc4cl is an implementation of XML-RPC for CL using ,according to its
author, best of breed common lisp libraries to do most of the work.

These dependencies are as of version 0.3.0: drakma, cxml, cl-ppcre,
parse-number, babel, trivial-timeout

To run the tests you need hunchentoot in addition to the dependencies
for rpc4cl and a ruby installation. No good idea to only use rpc4cl to
test rpc4cl, right? Then just run rpc4cl:start-test-server and locate
and run client.rb from ./test/.

The test suite will also serve as an instructive example of how to
make use of rpc4cl.

This version of rpc4cl uses in addition to the already mentioned
dependencies: rfc3339-timestamp for parsing xml-rpc date-time strings
into a rfc3339:timestamp object.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 rpc4cl

Author

Peter Stiernström <peter@stiernstrom.se>

License

BSD

Description

A Common Lisp implementation of XML-RPC using best of breed libraries

Version

0.3.2

Dependencies

• drakma
• cxml
• cl-ppcre
• parse-number
• rfc3339-timestamp
• babel
• trivial-timeout

Source

rpc4cl.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 rpc4cl/src

Parent

rpc4cl (system)

Location

src/

Components

• package.lisp (file)
• condition.lisp (file)
• variable.lisp (file)
• utils.lisp (file)
• xml-rpc.lisp (file)
• conversion.lisp (file)
• encode.lisp (file)
• decode.lisp (file)
• interface.lisp (file)
• system.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 rpc4cl.asd

Location

rpc4cl.asd

Systems

rpc4cl (system)

4.1.2 rpc4cl/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

rpc4cl

4.1.3 rpc4cl/src/condition.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/condition.lisp

Exported Definitions

• xml-rpc-fault (condition)
• xml-rpc-parse-error (condition)

Internal Definitions

• fault-code-of (method)
• fault-string-of (method)
• fault-string-of (method)

4.1.4 rpc4cl/src/variable.lisp

Dependency

condition.lisp (file)

Parent

src (module)

Location

src/variable.lisp

Exported Definitions

*debug* (special variable)

Internal Definitions

• *empty-array* (special variable)
• *xml-rpc-interfaces* (special variable)

4.1.5 rpc4cl/src/utils.lisp

Dependency

variable.lisp (file)

Parent

src (module)

Location

src/utils.lisp

Internal Definitions

• assert-method (function)
• elements (function)
• find-element (function)
• find-xml-rpc-method (function)
• first-element (function)
• plist-keys (function)
• plist-p (function)
• plist-values (function)
• utf8-length (function)

4.1.6 rpc4cl/src/xml-rpc.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/xml-rpc.lisp

Internal Definitions

• base64-p (function)
• copy-xml-rpc-method (function)
• make-xml-rpc-method (function)
• xml-rpc-exchange (function)
• xml-rpc-method (structure)
• xml-rpc-method-documentation (function)
• (setf xml-rpc-method-documentation) (function)
• xml-rpc-method-equalp (function)
• xml-rpc-method-function (function)
• (setf xml-rpc-method-function) (function)
• xml-rpc-method-name (function)
• (setf xml-rpc-method-name) (function)
• xml-rpc-method-p (function)

4.1.7 rpc4cl/src/conversion.lisp

Dependency

xml-rpc.lisp (file)

Parent

src (module)

Location

src/conversion.lisp

Internal Definitions

• camel-craze (function)
• camel-craze-symbol (function)
• de-camel-craze (function)
• de-camel-craze-keyword (function)

4.1.8 rpc4cl/src/encode.lisp

Dependency

conversion.lisp (file)

Parent

src (module)

Location

src/encode.lisp

Internal Definitions

• encode-array (function)
• encode-date-time (function)
• encode-method-call (function)
• encode-method-fault (function)
• encode-method-response (function)
• encode-params (function)
• encode-string (function)
• encode-struct (function)
• encode-value (function)

4.1.9 rpc4cl/src/decode.lisp

Dependency

encode.lisp (file)

Parent

src (module)

Location

src/decode.lisp

Internal Definitions

• decode-array (function)
• decode-method-call-response (function)
• decode-params (function)
• decode-string (function)
• decode-struct (function)
• decode-value (function)

4.1.10 rpc4cl/src/interface.lisp

Dependency

decode.lisp (file)

Parent

src (module)

Location

src/interface.lisp

Exported Definitions

• add-call (method)
• define-rpc-call (macro)
• define-rpc-call-help (macro)
• empty-array (function)
• handle-rpc-call (function)
• multicall (class)
• perform-calls (method)
• rpc-call (function)
• with-api (macro)

Internal Definitions

• calls-of (method)
• (setf calls-of) (method)
• password-of (method)
• uri-of (method)
• username-of (method)

4.1.11 rpc4cl/src/system.lisp

Dependency

interface.lisp (file)

Parent

src (module)

Location

src/system.lisp

Internal Definitions

• system.get-capabilities (function)
• system.list-methods (function)
• system.method-help (function)
• system.method-signature (function)
• system.multicall (function)

5 Packages

Packages are listed by definition order.

5.1 rpc4cl

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *debug* (special variable)
• add-call (generic function)
• add-call (method)
• define-rpc-call (macro)
• define-rpc-call-help (macro)
• empty-array (function)
• handle-rpc-call (function)
• multicall (class)
• perform-calls (generic function)
• perform-calls (method)
• rpc-call (function)
• with-api (macro)
• xml-rpc-fault (condition)
• xml-rpc-parse-error (condition)

Internal Definitions

• *empty-array* (special variable)
• *xml-rpc-interfaces* (special variable)
• assert-method (function)
• base64-p (function)
• calls-of (generic function)
• calls-of (method)
• (setf calls-of) (method)
• (setf calls-of) (generic function)
• camel-craze (function)
• camel-craze-symbol (function)
• copy-xml-rpc-method (function)
• de-camel-craze (function)
• de-camel-craze-keyword (function)
• decode-array (function)
• decode-method-call-response (function)
• decode-params (function)
• decode-string (function)
• decode-struct (function)
• decode-value (function)
• elements (function)
• encode-array (function)
• encode-date-time (function)
• encode-method-call (function)
• encode-method-fault (function)
• encode-method-response (function)
• encode-params (function)
• encode-string (function)
• encode-struct (function)
• encode-value (function)
• fault-code-of (generic function)
• fault-code-of (method)
• fault-string-of (generic function)
• fault-string-of (method)
• fault-string-of (method)
• find-element (function)
• find-xml-rpc-method (function)
• first-element (function)
• make-xml-rpc-method (function)
• password-of (generic function)
• password-of (method)
• plist-keys (function)
• plist-p (function)
• plist-values (function)
• system.get-capabilities (function)
• system.list-methods (function)
• system.method-help (function)
• system.method-signature (function)
• system.multicall (function)
• uri-of (generic function)
• uri-of (method)
• username-of (generic function)
• username-of (method)
• utf8-length (function)
• xml-rpc-exchange (function)
• xml-rpc-method (structure)
• xml-rpc-method-documentation (function)
• (setf xml-rpc-method-documentation) (function)
• xml-rpc-method-equalp (function)
• xml-rpc-method-function (function)
• (setf xml-rpc-method-function) (function)
• xml-rpc-method-name (function)
• (setf xml-rpc-method-name) (function)
• xml-rpc-method-p (function)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *debug*

Setting this variable to t will result in debug information emitted on *standard-output* while calling xml-rpc-call

Package

rpc4cl

Source

variable.lisp (file)

6.1.2 Macros

Macro: define-rpc-call API-NAME (CALL-NAME &rest PARAMETERS) &body BODY

Usage: (define-rpc-call :my-api (plus :int a :int b) (+ a b))

Defines a function, call-name which when called verifies its parameters and number of parameters and throws appropriate xml-rpc faults before executing it’s body.

For ’sloppy’ code the :any type may be used but then you better make sure yourself that you’ve got the expected type.

Package

rpc4cl

Source

interface.lisp (file)

Macro: define-rpc-call-help API-NAME (CALL-NAME) DOCUMENTATION

Define documentation that will be returned through system.methodHelp

Package

rpc4cl

Source

interface.lisp (file)

Macro: with-api (API-NAME) &body BODY

Bind *current-api* to api-name for future reference.

Package

rpc4cl

Source

interface.lisp (file)

6.1.3 Functions

Function: empty-array ()

Return the special *empty-array* value

Package

rpc4cl

Source

interface.lisp (file)

Function: handle-rpc-call DATA &key TIMEOUT

Handle an incoming xml-rpc call by looking up the methodName and then calling the function with the multiple values in the decoded <params></params>. Then encode the result to its string representation and return it.

Optionally throw an xml-rpc-fault with code 0 if timeout was reached before the end of the call.

Package

rpc4cl

Source

interface.lisp (file)

Function: rpc-call URI USERNAME PASSWORD METHOD-NAME &rest PARAMS

Call method-name with params. The encoded call is sent to uri and the decoded response parameters are returned as multiple values or in the case of a fault a xml-rpc-fault condition is raised. To make this function more ergonomic you should propbably wrap it up in your own which specifies uri, username and password as needed for you.

Package

rpc4cl

Source

interface.lisp (file)

6.1.4 Generic functions

Generic Function: add-call MULTICALL METHOD-NAME &rest PARAMS

Package

rpc4cl

Methods

Method: add-call (MULTICALL multicall) METHOD-NAME &rest PARAMS

Add a call to the multicall stack

Source

interface.lisp (file)

Generic Function: perform-calls MULTICALL

Package

rpc4cl

Methods

Method: perform-calls (MULTICALL multicall)

Perform all calls in the multicall stack in the order they were added

Source

interface.lisp (file)

6.1.5 Conditions

Condition: xml-rpc-fault ()

Condition thrown in the event of an XML-RPC fault

Package

rpc4cl

Source

condition.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• fault-string-of (method)
• fault-code-of (method)

Direct slots

Slot: fault-code

Initargs

:fault-code

Initform

(quote nil)

Readers

fault-code-of (generic function)

Slot: fault-string

Initargs

:fault-string

Initform

(quote nil)

Readers

fault-string-of (generic function)

Condition: xml-rpc-parse-error ()

Condition thrown in the event of an XML-RPC parse error

Package

rpc4cl

Source

condition.lisp (file)

Direct superclasses

condition (condition)

Direct methods

fault-string-of (method)

Direct slots

Slot: fault-string

Initargs

:fault-string

Initform

(quote nil)

Readers

fault-string-of (generic function)

6.1.6 Classes

Class: multicall ()

A stack for multiple calls using system.multicall

Package

rpc4cl

Source

interface.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• perform-calls (method)
• add-call (method)
• calls-of (method)
• calls-of (method)
• uri-of (method)
• password-of (method)
• username-of (method)

Direct slots

Slot: username

Initargs

:username

Readers

username-of (generic function)

Slot: password

Initargs

:password

Readers

password-of (generic function)

Slot: uri

Initargs

:uri

Initform

(error "an uri must be supplied")

Readers

uri-of (generic function)

Slot: calls

Readers

calls-of (generic function)

Writers

(setf calls-of) (generic function)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *empty-array*

Unique value used to represent an empty array

Package

rpc4cl

Source

variable.lisp (file)

Special Variable: *xml-rpc-interfaces*

Package

rpc4cl

Source

variable.lisp (file)

6.2.2 Functions

Function: assert-method METHODNAME

Make sure that a method exists by looking it up its name

Package

rpc4cl

Source

utils.lisp (file)

Function: base64-p LIST

We expect base64 encoded content to be denoted as a two element lisp with the first element being the keyword :base64 and the second being the base64 encoded string contents.

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: camel-craze STRING

Convet a string containing dashes to its camelCased representation. CAMEL-CASE becomes camelCase.

Package

rpc4cl

Source

conversion.lisp (file)

Function: camel-craze-symbol SYMBOL

Do camel-crazing on a symbol returning a string

Package

rpc4cl

Source

conversion.lisp (file)

Function: copy-xml-rpc-method INSTANCE

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: de-camel-craze STRING

Convert camelCase string to what we would expect for lisp symbol name suitable for find-symbol. camelCase becomes CAMEL-CASE. This is the reverse of camel-crazing something

Package

rpc4cl

Source

conversion.lisp (file)

Function: de-camel-craze-keyword STRING

Decraze a string returning a keyword symbol

Package

rpc4cl

Source

conversion.lisp (file)

Function: decode-array ARRAY-DOM &aux ARRAY

Decode an array to a list

Package

rpc4cl

Source

decode.lisp (file)

Function: decode-method-call-response DOCUMENT

Decode a method call response and throw a xml-rpc-fault error if there is a fault in the response xml otherwise return the decoded params as multiple values.

Package

rpc4cl

Source

decode.lisp (file)

Function: decode-params DOCUMENT &aux PARAMS

Decode all the params one by one and return as multiple values

Package

rpc4cl

Source

decode.lisp (file)

Function: decode-string STRING

Restore any escaped string values

Package

rpc4cl

Source

decode.lisp (file)

Function: decode-struct VAL &aux STRUCT

Decode a struct to a plist

Package

rpc4cl

Source

decode.lisp (file)

Function: decode-value VAL

Decode the value by looking at the type node name

Package

rpc4cl

Source

decode.lisp (file)

Function: elements NODE

Package

rpc4cl

Source

utils.lisp (file)

Function: encode-array LIST

Encode an XML-RPC array from a list if you want to encode an actual array/vector you should coerce it to list first.

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-date-time TIMESTAMP

I haven’t read up on iso8601 and what it entails but this should at least be one valid format for encoding it.

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-method-call METHOD-NAME &rest PARAMS

Create a complete XML document representing a method call to method-name with any number of params

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-method-fault E

A XML-RPC fault is a struct with a faultCode and a faultString member inside a <fault> tag.

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-method-response &rest PARAMS

Encode the method response suitable for decoding by an XML-RPC client. In case an xml-rpc-fault is raised we encode it and return it.

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-params &rest PARAMS

Encode all arguments as a XML-RPC <params> tag

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-string STRING

Escape all & and < characters in a string with their respective HTML entities.

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-struct PLIST

Encode a struct (being a plist) and convert the plist keys to their camelcrazed representation.

Package

rpc4cl

Source

encode.lisp (file)

Function: encode-value THING

Convert lisp values to the closest XML-RPC supported type. For complex data types we call out to their respective encoding routines.

Package

rpc4cl

Source

encode.lisp (file)

Function: find-element NODE NAME

Package

rpc4cl

Source

utils.lisp (file)

Function: find-xml-rpc-method NAME

Find a method in *current-api* or :system

Package

rpc4cl

Source

utils.lisp (file)

Function: first-element NODE

Package

rpc4cl

Source

utils.lisp (file)

Function: make-xml-rpc-method &key (NAME NAME) (FUNCTION FUNCTION) (DOCUMENTATION DOCUMENTATION)

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: plist-keys PLIST

Return the keys of a plist

Package

rpc4cl

Source

utils.lisp (file)

Function: plist-p POSSIBLE-PLIST

Try to determine if possible-plist is a valid plist by making sure the list contains even pairs and that all keys are keywords.

Package

rpc4cl

Source

utils.lisp (file)

Function: plist-values PLIST

Return the values of a plist

Package

rpc4cl

Source

utils.lisp (file)

Function: system.get-capabilities &rest NO-SUCH-PARAMETERS

Package

rpc4cl

Source

system.lisp (file)

Function: system.list-methods &rest NO-SUCH-PARAMETERS

Package

rpc4cl

Source

system.lisp (file)

Function: system.method-help METHOD-NAME &rest NO-SUCH-PARAMETERS

Package

rpc4cl

Source

system.lisp (file)

Function: system.method-signature METHOD &rest NO-SUCH-PARAMETERS

Package

rpc4cl

Source

system.lisp (file)

Function: system.multicall CALLS &rest NO-SUCH-PARAMETERS

Package

rpc4cl

Source

system.lisp (file)

Function: utf8-length STRING

Determine content-length for an UTF-8 string using babel for portability.

Package

rpc4cl

Source

utils.lisp (file)

Function: xml-rpc-exchange URI XML &optional USERNAME PASSWORD &aux CONTENT-LENGTH

Use drakma to perform an HTTP POST request with the supplied xml in the body and optionally with basic auth if username and password are non-nil.

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: xml-rpc-method-documentation INSTANCE

Function: (setf xml-rpc-method-documentation) VALUE INSTANCE

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: xml-rpc-method-equalp A B

Method are equal if their functions match

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: xml-rpc-method-function INSTANCE

Function: (setf xml-rpc-method-function) VALUE INSTANCE

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: xml-rpc-method-name INSTANCE

Function: (setf xml-rpc-method-name) VALUE INSTANCE

Package

rpc4cl

Source

xml-rpc.lisp (file)

Function: xml-rpc-method-p OBJECT

Package

rpc4cl

Source

xml-rpc.lisp (file)

6.2.3 Generic functions

Generic Function: calls-of OBJECT

Generic Function: (setf calls-of) NEW-VALUE OBJECT

Package

rpc4cl

Methods

Method: calls-of (MULTICALL multicall)

automatically generated reader method

Source

interface.lisp (file)

Method: (setf calls-of) NEW-VALUE (MULTICALL multicall)

automatically generated writer method

Source

interface.lisp (file)

Generic Function: fault-code-of CONDITION

Package

rpc4cl

Methods

Method: fault-code-of (CONDITION xml-rpc-fault)

Source

condition.lisp (file)

Generic Function: fault-string-of CONDITION

Package

rpc4cl

Methods

Method: fault-string-of (CONDITION xml-rpc-parse-error)

Source

condition.lisp (file)

Method: fault-string-of (CONDITION xml-rpc-fault)

Source

condition.lisp (file)

Generic Function: password-of OBJECT

Package

rpc4cl

Methods

Method: password-of (MULTICALL multicall)

automatically generated reader method

Source

interface.lisp (file)

Generic Function: uri-of OBJECT

Package

rpc4cl

Methods

Method: uri-of (MULTICALL multicall)

automatically generated reader method

Source

interface.lisp (file)

Generic Function: username-of OBJECT

Package

rpc4cl

Methods

Method: username-of (MULTICALL multicall)

automatically generated reader method

Source

interface.lisp (file)

6.2.4 Structures

Structure: xml-rpc-method ()

Package

rpc4cl

Source

xml-rpc.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: name

Readers

xml-rpc-method-name (function)

Writers

(setf xml-rpc-method-name) (function)

Slot: function

Readers

xml-rpc-method-function (function)

Writers

(setf xml-rpc-method-function) (function)

Slot: documentation

Readers

xml-rpc-method-documentation (function)

Writers

(setf xml-rpc-method-documentation) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types