The glacier Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The glacier Reference Manual

This is the glacier Reference Manual, version 0.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 11:10:05 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

glacier logo

ava fox

lightweight wrapper for making mastodon bots

Installation

clone this repo into your local system definitions or ~/common-lisp folder

Usage

create a bot object, passing it (at minimum) a path to your config file

then pass that bot object to (glacier:run-bot)

if you pass nothing else but the bot object, the framework will drop into a loop monitoring for updates and running the proper handlers from your bot (assuming you specified what handlers to run when creating your bot object)

you can pass code along with your bot to (glacier:run-bot) and it will run that code along with monitoring for streaming updates

NOTE: if you pass code that doesn't block forever, the bot will exit without doing anything

;; bad example
(glacier:run-bot (my-bot)
  (format t "my bot is running!")) ;; this doesn't block, so we print this and exit

see below for good examples

most objects that get passed around are tooter objects, so it probably wouldnt hurt to get acquainted with that library.

Examples

the following runs a bot (using the instance and access token specified in the config) that posts "trans rights are human rights" every 30 minutes

please see the example config for option names

(glacier:run-bot ((make-instance 'glacier:mastodon-bot :config-file "/path/to/bot.config"))
  (glacier:after-every (30 :minutes)
    (glacier:post "trans rights are human rights" :visibility :public)))

the following runs a bot that responds to a mention with a cordial hello

(defun maybe-respond (notification)
  "respond to a status from a mention NOTIFICATION"
  (when (glacier:mention-p notification)
    (glacier:reply (tooter:status notification) "hi! :3")))

(glacier:run-bot ((make-instance 'glacier:mastodon-bot :config-file "/path/to/bot.config"
                                                      :on-notification #'maybe-respond)))

the following runs a bot that will respond to posts with !hello in them with status personalized with their displayname

(defun cordial-reply (status)
  (glacier:reply status (format nil "hi, ~a! :3"
                        (tooter:display-name (tooter:account status)))))

(glacier:add-command "hello" #'cordial-reply)

(glacier:run-bot ((make-instance 'glacier:mastodon-bot :config-file "/path/to/bot.config")))

API

run-bot ((bot &key delete-command (with-websocket t)) &body body)

runs BOT, setting up websocket handlers and starting the streaming connection before executing BODY

if DELETE-COMMAND is non-nil, automatically adds a delete command if WITH-WEBSOCKET is non-nil (default), automatically starts up a websocket listener for realtime updates

NOTE: DELETE-COMMAND is ignored used if WITH-WEBSOCKET is nil

if BODY is not provided drops into a loop where we sleep until the user quits us, or our connection closes. this functionality does not happen if WITH-WEBSOCKET is nil.


mention-p (notification)

returns T if NOTIFICATION is a mention


fave-p (notification)

returns T if NOTIFICATION is a favourite


boost-p (notification)

returns T if NOTIFICATION is a boost


poll-ended-p (notification)

returns T if NOTIFICATION is from a poll ending


follow-request-p (notification)

returns T if NOTIFICATION is a follow-request


follow-p (notification)

returns T if NOTIFICATION is a follow


bot-post-p (status)

returns T if STATUS was posted by the bot


delete-parent (status)

deletes the parent to STATUS if it was made by the bot


after ((amount duration &key async) &body body)

runs BODY after AMOUNT of DURATION time has passed

if ASYNC is non-nil runs asynchronously

(after (3 :minutes) (print "hello"))

;; (after 3 minutes)
;;=> "hello"

after-every ((amount duration &key async run-immediately) &body body)

same as AFTER except repeats after every duration

if RUN-IMMEDIATELY is non-nil, executes BODY once before waiting for the next iteration


post (text &key (visibility :unlisted) cw media sensitive)

a thin wrapper around TOOTER:MAKE-STATUS

(post "hi~" :visibility :public)


reply (status text &key include-mentions media)

replys to STATUS with TEXT

if include-mentions is non-nil then the reply will contain all mentions from the original status

NOTE: reply will always include an @ to the person it's replying to


add-command (cmd function &key privileged add-prefix)

adds a command with CMD being the text to trigger the command and FUNCTION being the function that runs

FUNCTION needs to accept one parameter: a tooter:status object

if PRIVILEGED is non-nil, the bot needs to be following the account the mention comes from for the command to be triggered

if ADD-PREFIX is non-nil, adds *COMMAND-PREFIX* to the front of CMD


*command-prefix*

the string that prefixes commands.

defaults to "!"


terminate-connection

terminates the websocket connection that feeds the bot streaming updates

effectively terminates the bot


License

BSD 3-Clause


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 glacier

Author

ava fox

License

BSD 3-Clause

Description

lightweight mastodon bot framework

Version

0.3

Dependencies
Source

glacier.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 glacier.asd

Location

glacier.asd

Systems

glacier (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 glacier/package.lisp

Parent

glacier (system)

Location

package.lisp

Packages

glacier


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 glacier/bot.lisp

Dependency

package.lisp (file)

Parent

glacier (system)

Location

bot.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 glacier/extensions.lisp

Dependency

bot.lisp (file)

Parent

glacier (system)

Location

extensions.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 glacier/util.lisp

Dependency

extensions.lisp (file)

Parent

glacier (system)

Location

util.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.6 glacier/glacier.lisp

Dependency

util.lisp (file)

Parent

glacier (system)

Location

glacier.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 glacier

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *command-prefix*

character or string that prefixes a command

Package

glacier

Source

bot.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: after (AMOUNT DURATION &key ASYNC) &body BODY

runs BODY after AMOUNT of DURATION

if ASYNC is non-nil, runs asynchronously

Package

glacier

Source

util.lisp (file)

Macro: after-every (AMOUNT DURATION &key ASYNC RUN-IMMEDIATELY) &body BODY

runs BODY after every AMOUNT of DURATION

if ASYNC is non-nil, runs asynchronously
if RUN-IMMEDIATELY is non-nil, runs BODY once before waiting for next invocation

Package

glacier

Source

util.lisp (file)

Macro: run-bot (BOT &key DELETE-COMMAND WITH-WEBSOCKET) &body BODY

runs BOT, setting up websocket handlers and starting the streaming connection before executing BODY

if DELETE-COMMAND is non-nil, automatically adds a delete command
if WITH-WEBSOCKET is non-nil (default), automatically starts up a websocket listener for realtime updates

NOTE: DELETE-COMMAND is ignored used if WITH-WEBSOCKET is nil

if BODY is not provided drops into a loop where we sleep until the user quits us, or our connection closes. this functionality does not happen if WITH-WEBSOCKET is nil.

Package

glacier

Source

glacier.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: add-command CMD FUNCTION &key PRIVILEGED ADD-PREFIX

adds a command into our hash

CMD should be a string
FUNCTION should be a function that accepts a single parameter (a tooter:status object)

if PRIVILEGED is non-nil, command will only be triggered if mention is sent by an account the bot is following if ADD-PREFIX is non-nil, adds *COMMAND-PREFIX* to the front of CMD

Package

glacier

Source

util.lisp (file)

Function: agetf PLACE INDICATOR &optional DEFAULT

getf but for alists

Package

glacier

Source

util.lisp (file)

Function: boost-p NOTIFICATION

checks if NOTIFICATION is a boost

Package

glacier

Source

util.lisp (file)

Function: bot-post-p STATUS

checks if STATUS was posted by the bot

Package

glacier

Source

util.lisp (file)

Function: delete-parent STATUS

deletes the parent post of STATUS if it was posted by the bot

Package

glacier

Source

util.lisp (file)

Function: fave-p NOTIFICATION

checks if NOTIFICATION is a favourite

Package

glacier

Source

util.lisp (file)

Function: follow-p NOTIFICATION

checks if NOTIFICATION is a follow

Package

glacier

Source

util.lisp (file)

Function: follow-request-p NOTIFICATION

checks if NOTIFICATION is a follow request

Package

glacier

Source

util.lisp (file)

Function: mention-p NOTIFICATION

checks if NOTIFICATION is a mention

Package

glacier

Source

util.lisp (file)

Function: poll-ended-p NOTIFICATION

checks if NOTIFICATION is a poll

Package

glacier

Source

util.lisp (file)

Function: post TEXT &key VISIBILITY CW SENSITIVE MEDIA

a thin wrapper around tooter:make-status

see documentation for that function

Package

glacier

Source

extensions.lisp (file)

Function: terminate-connection ()

closes the websocket connection and clears the variable from memory

Package

glacier

Source

glacier.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Generic functions

Generic Function: bot-client OBJECT
Package

glacier

Methods
Method: bot-client (MASTODON-BOT mastodon-bot)

automatically generated reader method

Source

bot.lisp (file)

Generic Function: bot-on-delete OBJECT
Generic Function: (setf bot-on-delete) NEW-VALUE OBJECT
Package

glacier

Methods
Method: bot-on-delete (MASTODON-BOT mastodon-bot)

automatically generated reader method

Source

bot.lisp (file)

Method: (setf bot-on-delete) NEW-VALUE (MASTODON-BOT mastodon-bot)

automatically generated writer method

Source

bot.lisp (file)

Generic Function: bot-on-notification OBJECT
Generic Function: (setf bot-on-notification) NEW-VALUE OBJECT
Package

glacier

Methods
Method: bot-on-notification (MASTODON-BOT mastodon-bot)

automatically generated reader method

Source

bot.lisp (file)

Method: (setf bot-on-notification) NEW-VALUE (MASTODON-BOT mastodon-bot)

automatically generated writer method

Source

bot.lisp (file)

Generic Function: bot-on-update OBJECT
Generic Function: (setf bot-on-update) NEW-VALUE OBJECT
Package

glacier

Methods
Method: bot-on-update (MASTODON-BOT mastodon-bot)

automatically generated reader method

Source

bot.lisp (file)

Method: (setf bot-on-update) NEW-VALUE (MASTODON-BOT mastodon-bot)

automatically generated writer method

Source

bot.lisp (file)

Generic Function: bot-username OBJECT
Package

glacier

Methods
Method: bot-username (MASTODON-BOT mastodon-bot)

automatically generated reader method

Source

bot.lisp (file)

Generic Function: no-bot-p ID
Package

glacier

Methods
Method: no-bot-p (MENTION mention)

checks account found in MENTION to see if they have NoBot set

Source

extensions.lisp (file)

Method: no-bot-p (ACCOUNT account)

checks an account’s bio and profile fields to see if they contain a NoBot tag

Source

extensions.lisp (file)

Method: no-bot-p (ID integer)

checks an account’s bio and profile fields to see if they contain a NoBot tag

Source

extensions.lisp (file)

Method: no-bot-p (ID string)

checks an account’s bio and profile fields to see if they contain a NoBot tag

Source

extensions.lisp (file)

Generic Function: reply STATUS TEXT &key INCLUDE-MENTIONS MEDIA CW SENSITIVE VISIBILITY
Package

glacier

Methods
Method: reply (STATUS status) TEXT &key INCLUDE-MENTIONS MEDIA CW SENSITIVE VISIBILITY

replies to a STATUS with TEXT. copies the visibility and content warning as the post it’s replying to

if INCLUDE-MENTIONS is non-nil, include mentions besides the primary account being replied to

Source

extensions.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 Classes

Class: bot-client ()
Package

glacier

Source

bot.lisp (file)

Direct superclasses

client (class)

Direct Default Initargs
InitargValue
:name"glacierbot"
:website"https://github.com/compufox/glacier"
Class: mastodon-bot ()

bot superclass

Package

glacier

Source

bot.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: on-update
Initargs

:on-update

Readers

bot-on-update (generic function)

Writers

(setf bot-on-update) (generic function)

Slot: on-delete
Initargs

:on-delete

Readers

bot-on-delete (generic function)

Writers

(setf bot-on-delete) (generic function)

Slot: on-notification
Initargs

:on-notification

Readers

bot-on-notification (generic function)

Writers

(setf bot-on-notification) (generic function)

Slot: account-id
Readers

bot-account-id (generic function)

Slot: account-username
Readers

bot-username (generic function)

Slot: client
Readers

bot-client (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *bot*
Package

glacier

Source

glacier.lisp (file)

Special Variable: *commands*

hash table containing the bot’s commands

KEY is the command as a string
VALUE is a function that accepts a tooter:status object as a parameter

Package

glacier

Source

bot.lisp (file)

Special Variable: *no-bot-regex*

regex to check for the NoBot tag

Package

glacier

Source

extensions.lisp (file)

Special Variable: *privileged-commands*

hash table containing commands that will only be ran if the mention is from an account the bot follows

KEY is the command as a string
VALUE is a function that accepts a tooter:status object as a parameter

Package

glacier

Source

bot.lisp (file)

Special Variable: *websocket-client*
Package

glacier

Source

glacier.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: add-scheme DOMAIN

adds https scheme to DOMAIN if it isnt already there

Package

glacier

Source

util.lisp (file)

Function: api-request FRAGMENT &optional RESULT-TYPE

perform an API request

FRAGMENT is the fragment of the url that goes AFTER api/v1/
RESULT-TYPE (if provided) is the object type that we should use when parsing the response can be either a symbol (’account) or list ’(:list account)

if it is a list then we decode the response and collect and return them as a list

Package

glacier

Source

extensions.lisp (file)

Function: command-dispatch STATUS

parses STATUS content for a command word, and runs any function it has in *commands* with it as the argument

if STATUS comes from an account the bot is following, also checks for any command in *privileged-commands*

Package

glacier

Source

glacier.lisp (file)

Function: commandp WORD

checks if WORD is a command

Package

glacier

Source

util.lisp (file)

Function: dispatch MESSAGE

gets the type of MESSAGE we received and calls the appropriate functions on our bot with the proper tooter object

Package

glacier

Source

glacier.lisp (file)

Function: get-mastodon-streaming-url ()

gets the websocket url for the mastodon instance

Package

glacier

Source

util.lisp (file)

Function: parse-time AMOUNT DURATION

parses AMOUNT of DURATION into seconds

Package

glacier

Source

util.lisp (file)

Function: print-close &key CODE REASON

prints a message when the websocket is closed

Package

glacier

Source

util.lisp (file)

Function: print-open ()

prints a message when the websocket is connected

Package

glacier

Source

util.lisp (file)

Function: privileged-reply-p STATUS

returns T if STATUS is from an account that the bot follows

Package

glacier

Source

util.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: bot-account-id OBJECT
Package

glacier

Methods
Method: bot-account-id (MASTODON-BOT mastodon-bot)

automatically generated reader method

Source

bot.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   G   L  
Index Entry  Section

F
File, Lisp, glacier.asd: The glacier․asd file
File, Lisp, glacier/bot.lisp: The glacier/bot․lisp file
File, Lisp, glacier/extensions.lisp: The glacier/extensions․lisp file
File, Lisp, glacier/glacier.lisp: The glacier/glacier․lisp file
File, Lisp, glacier/package.lisp: The glacier/package․lisp file
File, Lisp, glacier/util.lisp: The glacier/util․lisp file

G
glacier.asd: The glacier․asd file
glacier/bot.lisp: The glacier/bot․lisp file
glacier/extensions.lisp: The glacier/extensions․lisp file
glacier/glacier.lisp: The glacier/glacier․lisp file
glacier/package.lisp: The glacier/package․lisp file
glacier/util.lisp: The glacier/util․lisp file

L
Lisp File, glacier.asd: The glacier․asd file
Lisp File, glacier/bot.lisp: The glacier/bot․lisp file
Lisp File, glacier/extensions.lisp: The glacier/extensions․lisp file
Lisp File, glacier/glacier.lisp: The glacier/glacier․lisp file
Lisp File, glacier/package.lisp: The glacier/package․lisp file
Lisp File, glacier/util.lisp: The glacier/util․lisp file

Jump to:   F   G   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   B   C   D   F   G   M   N   P   R   T  
Index Entry  Section

(
(setf bot-on-delete): Exported generic functions
(setf bot-on-delete): Exported generic functions
(setf bot-on-notification): Exported generic functions
(setf bot-on-notification): Exported generic functions
(setf bot-on-update): Exported generic functions
(setf bot-on-update): Exported generic functions

A
add-command: Exported functions
add-scheme: Internal functions
after: Exported macros
after-every: Exported macros
agetf: Exported functions
api-request: Internal functions

B
boost-p: Exported functions
bot-account-id: Internal generic functions
bot-account-id: Internal generic functions
bot-client: Exported generic functions
bot-client: Exported generic functions
bot-on-delete: Exported generic functions
bot-on-delete: Exported generic functions
bot-on-notification: Exported generic functions
bot-on-notification: Exported generic functions
bot-on-update: Exported generic functions
bot-on-update: Exported generic functions
bot-post-p: Exported functions
bot-username: Exported generic functions
bot-username: Exported generic functions

C
command-dispatch: Internal functions
commandp: Internal functions

D
delete-parent: Exported functions
dispatch: Internal functions

F
fave-p: Exported functions
follow-p: Exported functions
follow-request-p: Exported functions
Function, add-command: Exported functions
Function, add-scheme: Internal functions
Function, agetf: Exported functions
Function, api-request: Internal functions
Function, boost-p: Exported functions
Function, bot-post-p: Exported functions
Function, command-dispatch: Internal functions
Function, commandp: Internal functions
Function, delete-parent: Exported functions
Function, dispatch: Internal functions
Function, fave-p: Exported functions
Function, follow-p: Exported functions
Function, follow-request-p: Exported functions
Function, get-mastodon-streaming-url: Internal functions
Function, mention-p: Exported functions
Function, parse-time: Internal functions
Function, poll-ended-p: Exported functions
Function, post: Exported functions
Function, print-close: Internal functions
Function, print-open: Internal functions
Function, privileged-reply-p: Internal functions
Function, terminate-connection: Exported functions

G
Generic Function, (setf bot-on-delete): Exported generic functions
Generic Function, (setf bot-on-notification): Exported generic functions
Generic Function, (setf bot-on-update): Exported generic functions
Generic Function, bot-account-id: Internal generic functions
Generic Function, bot-client: Exported generic functions
Generic Function, bot-on-delete: Exported generic functions
Generic Function, bot-on-notification: Exported generic functions
Generic Function, bot-on-update: Exported generic functions
Generic Function, bot-username: Exported generic functions
Generic Function, no-bot-p: Exported generic functions
Generic Function, reply: Exported generic functions
get-mastodon-streaming-url: Internal functions

M
Macro, after: Exported macros
Macro, after-every: Exported macros
Macro, run-bot: Exported macros
mention-p: Exported functions
Method, (setf bot-on-delete): Exported generic functions
Method, (setf bot-on-notification): Exported generic functions
Method, (setf bot-on-update): Exported generic functions
Method, bot-account-id: Internal generic functions
Method, bot-client: Exported generic functions
Method, bot-on-delete: Exported generic functions
Method, bot-on-notification: Exported generic functions
Method, bot-on-update: Exported generic functions
Method, bot-username: Exported generic functions
Method, no-bot-p: Exported generic functions
Method, no-bot-p: Exported generic functions
Method, no-bot-p: Exported generic functions
Method, no-bot-p: Exported generic functions
Method, reply: Exported generic functions

N
no-bot-p: Exported generic functions
no-bot-p: Exported generic functions
no-bot-p: Exported generic functions
no-bot-p: Exported generic functions
no-bot-p: Exported generic functions

P
parse-time: Internal functions
poll-ended-p: Exported functions
post: Exported functions
print-close: Internal functions
print-open: Internal functions
privileged-reply-p: Internal functions

R
reply: Exported generic functions
reply: Exported generic functions
run-bot: Exported macros

T
terminate-connection: Exported functions

Jump to:   (  
A   B   C   D   F   G   M   N   P   R   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
A   C   O   S  
Index Entry  Section

*
*bot*: Internal special variables
*command-prefix*: Exported special variables
*commands*: Internal special variables
*no-bot-regex*: Internal special variables
*privileged-commands*: Internal special variables
*websocket-client*: Internal special variables

A
account-id: Exported classes
account-username: Exported classes

C
client: Exported classes

O
on-delete: Exported classes
on-notification: Exported classes
on-update: Exported classes

S
Slot, account-id: Exported classes
Slot, account-username: Exported classes
Slot, client: Exported classes
Slot, on-delete: Exported classes
Slot, on-notification: Exported classes
Slot, on-update: Exported classes
Special Variable, *bot*: Internal special variables
Special Variable, *command-prefix*: Exported special variables
Special Variable, *commands*: Internal special variables
Special Variable, *no-bot-regex*: Internal special variables
Special Variable, *privileged-commands*: Internal special variables
Special Variable, *websocket-client*: Internal special variables

Jump to:   *  
A   C   O   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   G   M   P   S  
Index Entry  Section

B
bot-client: Exported classes

C
Class, bot-client: Exported classes
Class, mastodon-bot: Exported classes

G
glacier: The glacier system
glacier: The glacier package

M
mastodon-bot: Exported classes

P
Package, glacier: The glacier package

S
System, glacier: The glacier system

Jump to:   B   C   G   M   P   S