The cl-fluidinfo Reference Manual

Table of Contents

The cl-fluidinfo Reference Manual

This is the cl-fluidinfo Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:46:37 2021 GMT+0.

1 Introduction

cl-fluiddb / cl-fluidinfo

cl-fluidinfo (cl-fluiddb is the old, original name) is a work-in-progress project of accessing the fluidinfo from Common Lisp. This is by no means done, expect breaking changes in the future.

I do all my work in SBCL, so this is the only implementation currently supported.

Requirements

You will need

• Drakma
• cl-json
• flexi-streams (is a dependency of drakma anyway)
• bordeaux-threads
• split-sequence
• All dependencies of those libs above.

You should use Quicklisp to get these dependencies. No, really. If you aren't using it yet, do yourself a favour and install it before proceeding.

There is also a beginning of some tests written in Lift, so you will need the lift library.

Licence

Copyright (c) 2011, Holger Durer 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.

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 HOLDER 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.

2 Systems

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

2.1 cl-fluidinfo

Author

<codemonkey@betareduction.info>

License

BSD 2-clause license - http://www.opensource.org/licenses/BSD-2-Clause

Description

Library to access the Fluidinfo database / storage and search platform

Version

0.1

Dependency

cl-fluiddb (system)

Source

cl-fluidinfo.asd (file)

Component

fluidinfo-defpackage.lisp (file)

2.2 cl-fluiddb

Author

<codemonkey@betareduction.info>

License

BSD 2-clause license - http://www.opensource.org/licenses/BSD-2-Clause

Description

Library to access the Fluidinfo database / storage and search platform

Version

0.1

Dependencies

• cl-json
• drakma
• flexi-streams
• bordeaux-threads
• split-sequence

Source

cl-fluiddb.asd (file)

Components

• defpackage.lisp (file)
• fluiddb.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 cl-fluidinfo.asd

Location

cl-fluidinfo.asd

Systems

cl-fluidinfo (system)

3.1.2 cl-fluiddb.asd

Location

cl-fluiddb.asd

Systems

cl-fluiddb (system)

Packages

cl-fluiddb-asd

Internal Definitions

*cl-fluiddb-version* (special variable)

3.1.3 cl-fluidinfo/fluidinfo-defpackage.lisp

Parent

cl-fluidinfo (system)

Location

fluidinfo-defpackage.lisp

Packages

cl-fluidinfo

3.1.4 cl-fluiddb/defpackage.lisp

Parent

cl-fluiddb (system)

Location

defpackage.lisp

Packages

cl-fluiddb

3.1.5 cl-fluiddb/fluiddb.lisp

Dependency

defpackage.lisp (file)

Parent

cl-fluiddb (system)

Location

fluiddb.lisp

Exported Definitions

• *call-timeout* (special variable)
• *credentials* (special variable)
• *proxy-credentials* (special variable)
• *proxy-server* (special variable)
• *use-https* (special variable)
• *user-agent* (special variable)
• change-namespace (function)
• change-tag (function)
• create-namespace (function)
• create-object (function)
• create-tag (function)
• delete-namespace (function)
• delete-object-about-tag-value (function)
• delete-object-tag-value (function)
• delete-objects-tag-values (function)
• delete-tag (function)
• error-body (method)
• (setf error-body) (method)
• error-class (method)
• (setf error-class) (method)
• get-namespace (function)
• get-namespace-permissions (function)
• get-object (function)
• get-object-about (function)
• get-object-about-tag-value (function)
• get-object-tag-value (function)
• get-policy (function)
• get-tag (function)
• get-tag-permissions (function)
• get-tag-value-permissions (function)
• get-user (function)
• object-about-tag-has-value-p (function)
• object-tag-has-value-p (function)
• query-objects (function)
• query-objects-tag-values (function)
• request-id (method)
• (setf request-id) (method)
• set-namespace-permissions (function)
• set-object-about-tag-value (function)
• set-object-tag-value (function)
• set-objects-tag-values (function)
• set-policy (function)
• set-tag-permissions (function)
• set-tag-value-permissions (function)
• status-code (method)
• (setf status-code) (method)
• status-message (method)
• (setf status-message) (method)
• url-format-namespace-or-tag (generic function)
• url-format-namespace-or-tag (method)
• url-format-namespace-or-tag (method)
• with-credentials (macro)

Internal Definitions

• *connection* (special variable)
• *server-url* (special variable)
• *using-sandbox* (special variable)
• call-error (condition)
• copy-json-alist (function)
• do-send-request (function)
• json-alist (structure)
• json-alist-p (function)
• json-alist-values (function)
• (setf json-alist-values) (function)
• make-json-alist (function)
• make-permission-object (function)
• send-request (function)
• throw-call-error (function)
• to-boolean (function)
• to-string (function)
• url-encode (function)

4 Packages

Packages are listed by definition order.

4.1 cl-fluidinfo

Source

fluidinfo-defpackage.lisp (file)

Use List

cl-fluiddb

4.2 cl-fluiddb-asd

Source

cl-fluiddb.asd

Use List

• asdf/interface
• common-lisp

Internal Definitions

*cl-fluiddb-version* (special variable)

4.3 cl-fluiddb

Source

defpackage.lisp (file)

Use List

common-lisp

Used By List

cl-fluidinfo

Exported Definitions

• *call-timeout* (special variable)
• *credentials* (special variable)
• *proxy-credentials* (special variable)
• *proxy-server* (special variable)
• *use-https* (special variable)
• *user-agent* (special variable)
• change-namespace (function)
• change-tag (function)
• create-namespace (function)
• create-object (function)
• create-tag (function)
• delete-namespace (function)
• delete-object-about-tag-value (function)
• delete-object-tag-value (function)
• delete-objects-tag-values (function)
• delete-tag (function)
• error-body (generic function)
• error-body (method)
• (setf error-body) (method)
• (setf error-body) (generic function)
• error-class (generic function)
• error-class (method)
• (setf error-class) (method)
• (setf error-class) (generic function)
• get-namespace (function)
• get-namespace-permissions (function)
• get-object (function)
• get-object-about (function)
• get-object-about-tag-value (function)
• get-object-tag-value (function)
• get-policy (function)
• get-tag (function)
• get-tag-permissions (function)
• get-tag-value-permissions (function)
• get-user (function)
• object-about-tag-has-value-p (function)
• object-tag-has-value-p (function)
• query-objects (function)
• query-objects-tag-values (function)
• request-id (generic function)
• request-id (method)
• (setf request-id) (method)
• (setf request-id) (generic function)
• set-namespace-permissions (function)
• set-object-about-tag-value (function)
• set-object-tag-value (function)
• set-objects-tag-values (function)
• set-policy (function)
• set-tag-permissions (function)
• set-tag-value-permissions (function)
• status-code (generic function)
• status-code (method)
• (setf status-code) (method)
• (setf status-code) (generic function)
• status-message (generic function)
• status-message (method)
• (setf status-message) (method)
• (setf status-message) (generic function)
• url-format-namespace-or-tag (generic function)
• url-format-namespace-or-tag (method)
• url-format-namespace-or-tag (method)
• with-credentials (macro)

Internal Definitions

• *connection* (special variable)
• *server-url* (special variable)
• *using-sandbox* (special variable)
• call-error (condition)
• copy-json-alist (function)
• do-send-request (function)
• json-alist (structure)
• json-alist-p (function)
• json-alist-values (function)
• (setf json-alist-values) (function)
• make-json-alist (function)
• make-permission-object (function)
• send-request (function)
• throw-call-error (function)
• to-boolean (function)
• to-string (function)
• url-encode (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *call-timeout*

Timeout (in seconds) to use for any call to the FluidDB server.
If a timeout happens, a bordeaux-threads:timeout condition will be raised. A value of nil means not to use any timeout.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Special Variable: *credentials*

User credentidals to be used for a request.
Should be either nil (anonymous access) or a list of two strings (username password)

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Special Variable: *proxy-credentials*

Credentials to be used to authenticate against the proxy configured via *proxy-server*

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Special Variable: *proxy-server*

Information about the proxy server to use for requests.
Should be either nil (direct access), a string (the server to use), or a list of two values (server port)

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Special Variable: *use-https*

Flag whether to use HTTPS or just HTTP

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Special Variable: *user-agent*

The string to be used as your user agent when making request.
This might allow FluidInfo to better monitor what app is using their service

Package

cl-fluiddb

Source

fluiddb.lisp (file)

5.1.2 Macros

Macro: with-credentials (USERNAME PASSWORD) &body BODY

Perform body with the passed fluiddb credentials in place

Package

cl-fluiddb

Source

fluiddb.lisp (file)

5.1.3 Functions

Function: change-namespace NAMESPACE NEW-DESCRIPTION

Change the description of the given namespace

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: change-tag TAG DESCRIPTION

Change the description of the given tag

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: create-namespace PARENT-NAMESPACE NAMESPACE-NAME DESCRIPTION

Create a new sub-namespace within the passed namespace

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: create-object &optional ABOUT

Create a new object (anonymous if no about is specified)

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: create-tag NAMESPACE TAG-NAME DESCRIPTION INDEXED

Create a new tag withing the given namespace

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: delete-namespace NAMESPACE

Delete the given namespace

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: delete-object-about-tag-value ABOUT TAG

Delete the specified tag value on the object with the given about tag

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: delete-object-tag-value ID TAG

Delete the specified tag value on the object with the given id

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: delete-objects-tag-values QUERY TAGS-LIST

Perform a query and delete the specified tag values on the matching objects

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: delete-tag TAG

Delete the given tag

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-namespace NAMESPACE &key RETURN-DESCRIPTION RETURN-NAMESPACE RETURN-TAGS

Retrieve information about the given namespace

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-namespace-permissions NAMESPACE ACTION

Retrieve the permission information for the given namespace and action. Action can be one of create, update, delete, list, control.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-object ID &key SHOW-ABOUT

Retrieve an object by its id

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-object-about ABOUT

Retrieve an object by its about tag

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-object-about-tag-value ABOUT TAG &key WANT-JSON ACCEPT

Retrieve the object’s tag value for the object with the given about tag

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-object-tag-value ID TAG &key WANT-JSON ACCEPT

Retrieve the object’s tag value for the object with the given id

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-policy USER-NAME CATEGORY ACTION

Retrieve the user’s default policy for the given category and action. Possible values for categorie/actions are:
- namespaces: create, update, delete, and list.
- tags: update and delete.
- tag-values: create, read, and delete.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-tag TAG &key RETURN-DESCRIPTION

Retrieve information about the given tag

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-tag-permissions TAG ACTION

Retrieve the permission information for the given tag and action. Action can be one of update, delete, control.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-tag-value-permissions TAG ACTION

Retrieve the permission information for the given tag value and action. Action can be one of create, read, delete, control.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: get-user NAME

Retrieve information about the user with the given name

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: object-about-tag-has-value-p ABOUT TAG

Check if the object with the given about tag has the specified tag value set. Returns nil or the mime type of the value.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: object-tag-has-value-p ID TAG

Check if the object with the given id has the specified tag value set. Returns nil or the mime type of the value.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: query-objects QUERY

Perform a query for all object matching

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: query-objects-tag-values QUERY TAGS-LIST

Perform a query and retrieve all objects matching plus the specified tag values on them

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: set-namespace-permissions NAMESPACE ACTION POLICY EXCEPTIONS

Set the permission information for the given namespace and action. Action can be one of create, update, delete, list, control. Policy can be either open or closed.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: set-object-about-tag-value ABOUT TAG CONTENT &optional CONTENT-TYPE

Set the specified tag value on the object with the given about tag. Content is either presumed to be pre-formatted (if content-type is given) or will be JSON encoded and passed a fluiddb primitive type.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: set-object-tag-value ID TAG CONTENT &optional CONTENT-TYPE

Set the specified tag value on the object with the given id.
Content is either presumed to be pre-formatted (if content-type is given) or will be JSON encoded and passed as a fluiddb primitive type.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: set-objects-tag-values QUERY TAGS-VALUES-LIST

Perform a query and set the specified tag values on the matching objects

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: set-policy USER-NAME CATEGORY ACTION POLICY EXCEPTIONS

Set the user’s default policy for the given category and action. Possible values for categorie/actions are:
- namespaces: create, update, delete, and list.
- tags: update and delete.
- tag-values: create, read, and delete.
Policy can be either open or closed.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: set-tag-permissions TAG ACTION POLICY EXCEPTIONS

Set the permission information for the given tag and action. Action can be one of update, delete, control.
Policy can be either open or closed.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: set-tag-value-permissions TAG ACTION POLICY EXCEPTIONS

Set the permission information for the given tag value and action. Action can be one of create, read, delete, control.
Policy can be either open or closed.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

5.1.4 Generic functions

Generic Function: error-body CONDITION

Generic Function: (setf error-body) NEW-VALUE CONDITION

Package

cl-fluiddb

Methods

Method: error-body (CONDITION call-error)

Method: (setf error-body) NEW-VALUE (CONDITION call-error)

Source

fluiddb.lisp (file)

Generic Function: error-class CONDITION

Generic Function: (setf error-class) NEW-VALUE CONDITION

Package

cl-fluiddb

Methods

Method: error-class (CONDITION call-error)

Method: (setf error-class) NEW-VALUE (CONDITION call-error)

Source

fluiddb.lisp (file)

Generic Function: request-id CONDITION

Generic Function: (setf request-id) NEW-VALUE CONDITION

Package

cl-fluiddb

Methods

Method: request-id (CONDITION call-error)

Method: (setf request-id) NEW-VALUE (CONDITION call-error)

Source

fluiddb.lisp (file)

Generic Function: status-code CONDITION

Generic Function: (setf status-code) NEW-VALUE CONDITION

Package

cl-fluiddb

Methods

Method: status-code (CONDITION call-error)

Method: (setf status-code) NEW-VALUE (CONDITION call-error)

Source

fluiddb.lisp (file)

Generic Function: status-message CONDITION

Generic Function: (setf status-message) NEW-VALUE CONDITION

Package

cl-fluiddb

Methods

Method: status-message (CONDITION call-error)

Method: (setf status-message) NEW-VALUE (CONDITION call-error)

Source

fluiddb.lisp (file)

Generic Function: url-format-namespace-or-tag TAG

Helper function to convert some object into a (url-escaped) string ready to be used as part of the path in the request URL

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Methods

Method: url-format-namespace-or-tag (TAG list)

Method: url-format-namespace-or-tag (TAG string)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *cl-fluiddb-version*

A string denoting the current version of this package. Used for diagnostic output.

Package

cl-fluiddb-asd

Source

cl-fluiddb.asd

Special Variable: *connection*

A store for any existing connection to the server that can be re-used

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Special Variable: *server-url*

Base URL (without the http:// or https:// protocol bit) for the server to call

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Special Variable: *using-sandbox*

Package

cl-fluiddb

Source

fluiddb.lisp (file)

5.2.2 Functions

Function: copy-json-alist INSTANCE

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: do-send-request PATH &key BODY-DATA QUERY-DATA ACCEPT METHOD CONTENT-TYPE

Lower-level routine to send a request to FluidDB.
Set accept to the content-type you want ("*/*" if you don’t know).

This does not interpret the results and just returns the HTTP response. It may still throw errors on network problems, timeouts etc.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: json-alist-p OBJECT

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: json-alist-values INSTANCE

Function: (setf json-alist-values) VALUE INSTANCE

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: make-json-alist &key (VALUES VALUES)

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: make-permission-object POLICY EXCEPTIONS

Return a JSON encoded string representing the passed permission. Policy should be either open or closed.

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: send-request PATH &key BODY-DATA QUERY-DATA ACCEPT METHOD CONTENT-TYPE

Send a request to FluidDB.
Set accept to the content-type you want ("*/*" if you don’t know).

We inspect the return data and convert it to a lisp data structure if it is json

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: throw-call-error STATUS-CODE STATUS-TEXT HEADERS RESPONSE-BODY

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: to-boolean VALUE

Convert a lisp value to something the JSON encode will convert to true or false

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: to-string SOMETHING

Do sensible conversion to a string

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Function: url-encode STRING

URL encode a string so it’s safe to include in an URL

Package

cl-fluiddb

Source

fluiddb.lisp (file)

5.2.3 Conditions

Condition: call-error ()

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Direct superclasses

error (condition)

Direct methods

• error-body (method)
• error-body (method)
• request-id (method)
• request-id (method)
• error-class (method)
• error-class (method)
• status-message (method)
• status-message (method)
• status-code (method)
• status-code (method)

Direct slots

Slot: status-code

Initargs

:status-code

Readers

status-code (generic function)

Writers

(setf status-code) (generic function)

Slot: status-message

Initargs

:status-message

Readers

status-message (generic function)

Writers

(setf status-message) (generic function)

Slot: error-class

Initargs

:error-class

Readers

error-class (generic function)

Writers

(setf error-class) (generic function)

Slot: request-id

Initargs

:request-id

Readers

request-id (generic function)

Writers

(setf request-id) (generic function)

Slot: error-body

Initargs

:error-body

Readers

error-body (generic function)

Writers

(setf error-body) (generic function)

5.2.4 Structures

Structure: json-alist ()

Package

cl-fluiddb

Source

fluiddb.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

encode-json (method)

Direct slots

Slot: values

Readers

json-alist-values (function)

Writers

(setf json-alist-values) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types