The glacier Reference Manual

This is the glacier Reference Manual, version 0.4, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 18:14:50 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 glacier

lightweight mastodon bot framework

Author

ava fox

License

BSD 3-Clause

Version

0.4

Dependencies
  • dexador (system).
  • bordeaux-threads (system).
  • str (system).
  • websocket-driver (system).
  • simple-config (system).
  • cl-json (system).
  • tooter (system).
  • cl-ppcre (system).
  • alexandria (system).
Source

glacier.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 glacier/glacier.asd

Source

glacier.asd.

Parent Component

glacier (system).

ASDF Systems

glacier.


3.1.2 glacier/package.lisp

Source

glacier.asd.

Parent Component

glacier (system).

Packages

glacier.


3.1.3 glacier/variables.lisp

Dependency

package.lisp (file).

Source

glacier.asd.

Parent Component

glacier (system).

Public Interface

*command-prefix* (special variable).

Internals

3.1.4 glacier/util.lisp

Dependency

variables.lisp (file).

Source

glacier.asd.

Parent Component

glacier (system).

Public Interface
Internals

3.1.5 glacier/mappings.lisp

Dependency

util.lisp (file).

Source

glacier.asd.

Parent Component

glacier (system).

Internals

3.1.6 glacier/bot.lisp

Dependency

mappings.lisp (file).

Source

glacier.asd.

Parent Component

glacier (system).

Public Interface
Internals

bot-account-id (reader method).


3.1.7 glacier/extensions.lisp

Dependency

bot.lisp (file).

Source

glacier.asd.

Parent Component

glacier (system).

Public Interface
Internals

3.1.8 glacier/glacier.lisp

Dependency

extensions.lisp (file).

Source

glacier.asd.

Parent Component

glacier (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 glacier

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *command-prefix*

character or string that prefixes a command

Package

glacier.

Source

variables.lisp.


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.

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.

Macro: on ((day &key at async) &body body)

runs BODY on DAY, optionally AT a time

DAY is a keyword with the day of the week (e.g., :sunday, :monday, etc) AT is a string denoting a time (e.g., ’13:20’, ’4:20PM’, ’23:00’)

if ASYNC is non-nil code is executed asynchronously
if AT is nil, code is ran at midnight on DAY

Package

glacier.

Source

util.lisp.

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.


5.1.3 Ordinary 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 (defaults to t)

Package

glacier.

Source

util.lisp.

Function: agetf (place indicator &optional default)

getf but for alists

Package

glacier.

Source

util.lisp.

Function: boost-p (notification)

checks if NOTIFICATION is a boost

Package

glacier.

Source

util.lisp.

Function: bot-post-p (status)

checks if STATUS was posted by the bot

Package

glacier.

Source

util.lisp.

Function: delete-parent (status)

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

Package

glacier.

Source

util.lisp.

Function: fave-p (notification)

checks if NOTIFICATION is a favourite

Package

glacier.

Source

util.lisp.

Function: follow-p (notification)

checks if NOTIFICATION is a follow

Package

glacier.

Source

util.lisp.

Function: follow-request-p (notification)

checks if NOTIFICATION is a follow request

Package

glacier.

Source

util.lisp.

Function: make-bot (&key config-file instance access-token strip-html strip-username timeline on-update on-delete on-notification cw-mappings)

makes a bot and returns it.
INSTANCE, ACCESS-TOKEN, STRIP-HTML, STRIP-USERNAME, TIMELINE are all options that are typically in a config file
passing these values in allows the developer to skip specifying a config file and can pull values in from other places
e.g., command line arguments

CONFIG-FILE is a string or a path that denotes a glacier config file
INSTANCE is a mastodon instance domain name, with or without http scheme
ACCESS-TOKEN is an access token for a mastodon account on INSTANCE
STRIP-HTML if non-nil incoming posts will have their html stripped from them. defaults to T
STRIP-USERNAME if non-nil strips the bot’s username from incoming posts. defaults to NIL
TIMELINE string denoting which timeline should be used for the streaming websocket. can be one of ’user’, ’public’, ’direct’. defaults to ’user’
ON-UPDATE a function that accepts a single mastodon status. gets ran for every new post that streams in from TIMELINE
ON-DELETE a function that accepts a single status id. gets ran for every deleted status that streams in from TIMELINE
ON-NOTIFICATION a function that accepts a single mastodon notification. gets ran for every notification that streams in from TIMELINE
CW-MAPPINGS a pathname or list of files that contain mappings specially formatted for the bot to automatically provide content warnings for generated posts. please see provided content-warning.map.example for examples of the formatting

Package

glacier.

Source

bot.lisp.

Function: mention-p (notification)

checks if NOTIFICATION is a mention

Package

glacier.

Source

util.lisp.

Function: poll-ended-p (notification)

checks if NOTIFICATION is a poll

Package

glacier.

Source

util.lisp.

Function: post (text &key visibility cw sensitive media poll-options poll-timeout poll-hide-totals-p poll-multiple-choice-p)

a thin wrapper around tooter:make-status
will automatically generate a content warning if cw-mappings was provided when the bot was created

Note: POLL-TIMEOUT is the number of seconds until the poll ends

see documentation for that function

Package

glacier.

Source

extensions.lisp.

Function: terminate-connection ()

closes the websocket connection and clears the variable from memory

Package

glacier.

Source

glacier.lisp.

Function: time-to-seconds (&rest rest)

takes all values passed as REST, converts the time into seconds, and returns the total

REST should be arguments compatible with PARSE-TIME
example usage: (time-to-seconds 1 :day 2 :hours 30 :minutes)

Package

glacier.

Source

util.lisp.


5.1.4 Generic functions

Generic Reader: bot-client (object)
Package

glacier.

Methods
Reader Method: bot-client ((mastodon-bot mastodon-bot))

automatically generated reader method

Source

bot.lisp.

Target Slot

client.

Generic Reader: bot-on-delete (object)
Package

glacier.

Methods
Reader Method: bot-on-delete ((mastodon-bot mastodon-bot))

automatically generated reader method

Source

bot.lisp.

Target Slot

on-delete.

Generic Writer: (setf bot-on-delete) (object)
Package

glacier.

Methods
Writer Method: (setf bot-on-delete) ((mastodon-bot mastodon-bot))

automatically generated writer method

Source

bot.lisp.

Target Slot

on-delete.

Generic Reader: bot-on-notification (object)
Package

glacier.

Methods
Reader Method: bot-on-notification ((mastodon-bot mastodon-bot))

automatically generated reader method

Source

bot.lisp.

Target Slot

on-notification.

Generic Writer: (setf bot-on-notification) (object)
Package

glacier.

Methods
Writer Method: (setf bot-on-notification) ((mastodon-bot mastodon-bot))

automatically generated writer method

Source

bot.lisp.

Target Slot

on-notification.

Generic Reader: bot-on-update (object)
Package

glacier.

Methods
Reader Method: bot-on-update ((mastodon-bot mastodon-bot))

automatically generated reader method

Source

bot.lisp.

Target Slot

on-update.

Generic Writer: (setf bot-on-update) (object)
Package

glacier.

Methods
Writer Method: (setf bot-on-update) ((mastodon-bot mastodon-bot))

automatically generated writer method

Source

bot.lisp.

Target Slot

on-update.

Generic Reader: bot-username (object)
Package

glacier.

Methods
Reader Method: bot-username ((mastodon-bot mastodon-bot))

automatically generated reader method

Source

bot.lisp.

Target Slot

account-username.

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.

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.

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.

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.


5.1.5 Standalone methods

Method: initialize-instance :after ((bot mastodon-bot) &rest initargs &key config-file instance token strip-html strip-username timeline cw-mappings &allow-other-keys)
Source

bot.lisp.


5.1.6 Classes

Class: bot-client
Package

glacier.

Source

bot.lisp.

Direct superclasses

client.

Direct Default Initargs
InitargValue
:nameglacierbot
:websitehttps://github.com/compufox/glacier
Class: mastodon-bot

bot superclass

Package

glacier.

Source

bot.lisp.

Direct methods
Direct slots
Slot: on-update
Initargs

:on-update

Readers

bot-on-update.

Writers

(setf bot-on-update).

Slot: on-delete
Initargs

:on-delete

Readers

bot-on-delete.

Writers

(setf bot-on-delete).

Slot: on-notification
Initargs

:on-notification

Readers

bot-on-notification.

Writers

(setf bot-on-notification).

Slot: account-id
Readers

bot-account-id.

Writers

This slot is read-only.

Slot: account-username
Readers

bot-username.

Writers

This slot is read-only.

Slot: client
Readers

bot-client.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Special variables

Special Variable: *bot*

global bot object

Package

glacier.

Source

variables.lisp.

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

variables.lisp.

Special Variable: *cw-mappings*
Package

glacier.

Source

variables.lisp.

Special Variable: *mappings-write-date*
Package

glacier.

Source

variables.lisp.

Special Variable: *no-bot-regex*

regex to check for the NoBot tag

Package

glacier.

Source

extensions.lisp.

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

variables.lisp.

Special Variable: *websocket-client*

global websocket client

Package

glacier.

Source

glacier.lisp.


5.2.2 Ordinary functions

Function: add-scheme (domain)

adds https scheme to DOMAIN if it isnt already there

Package

glacier.

Source

util.lisp.

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.

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.

Function: commandp (word)

checks if WORD is a command

Package

glacier.

Source

util.lisp.

Function: current-day ()

returns the current day of the week

Package

glacier.

Source

util.lisp.

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.

Function: dow-for (day)

returns the day of the week for DAY

Package

glacier.

Source

util.lisp.

Function: ensure-list (obj)

ensures that OBJ is a list

Package

glacier.

Source

util.lisp.

Function: generate-cw (status-text mappings)

returns a content warning based off of our cw-mappings and the STATUS-TEXT

Package

glacier.

Source

mappings.lisp.

Function: get-mastodon-streaming-url ()

gets the websocket url for the mastodon instance

Package

glacier.

Source

util.lisp.

Function: load-mapping-files (files)

loads the content warning mappings from FILES

returns an alist containing all mappings

Package

glacier.

Source

mappings.lisp.

Function: mappings-updated-p (files)

checks to see if any mapping FILES has been updated since our last check

Package

glacier.

Source

mappings.lisp.

Function: parse-mapping-file (file)

parses mapping FILE, returning an alist of the mappings of the from (CW (words))

Package

glacier.

Source

mappings.lisp.

Function: parse-time (amount duration)

parses AMOUNT of DURATION into seconds

Package

glacier.

Source

util.lisp.

Function: print-close (&key code reason)

prints a message when the websocket is closed

Package

glacier.

Source

util.lisp.

Function: print-open ()

prints a message when the websocket is connected

Package

glacier.

Source

util.lisp.

Function: privileged-reply-p (status)

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

Package

glacier.

Source

util.lisp.

Function: seconds-until (hours minutes &optional seconds)

determines how many seconds until HOURS MINUTES and SECONDS
if the time has already passed it returns 0 instead of a negative time

Package

glacier.

Source

util.lisp.

Function: seconds-until-midnight ()

returns how many seconds until it’s midnight

Package

glacier.

Source

util.lisp.

Function: seconds-until-timestring (time-string)

parses TIME-STRING and returns how long until the time specified TIME-STRING is of the form ’12:04’, ’18:30’, ’1:10PM’, etc

Package

glacier.

Source

util.lisp.

Function: upload-media (media)

uploads MEDIA to the defined mastodon server.
returns a list that can be passed into POST or REPLY
MEDIA may be a list containing pathnames, or lists of the form (PATH-TO-FILE IMAGE-DESCRIPTION) if it is like the latter, the description will be applied to the image upon uploading

Package

glacier.

Source

extensions.lisp.


5.2.3 Generic functions

Generic Reader: bot-account-id (object)
Package

glacier.

Methods
Reader Method: bot-account-id ((mastodon-bot mastodon-bot))

automatically generated reader method

Source

bot.lisp.

Target Slot

account-id.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   B   C   D   E   F   G   I   L   M   N   O   P   R   S   T   U  
Index Entry  Section

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

A
add-command: Public ordinary functions
add-scheme: Private ordinary functions
after: Public macros
after-every: Public macros
agetf: Public ordinary functions
api-request: Private ordinary functions

B
boost-p: Public ordinary functions
bot-account-id: Private generic functions
bot-account-id: Private generic functions
bot-client: Public generic functions
bot-client: Public generic functions
bot-on-delete: Public generic functions
bot-on-delete: Public generic functions
bot-on-notification: Public generic functions
bot-on-notification: Public generic functions
bot-on-update: Public generic functions
bot-on-update: Public generic functions
bot-post-p: Public ordinary functions
bot-username: Public generic functions
bot-username: Public generic functions

C
command-dispatch: Private ordinary functions
commandp: Private ordinary functions
current-day: Private ordinary functions

D
delete-parent: Public ordinary functions
dispatch: Private ordinary functions
dow-for: Private ordinary functions

E
ensure-list: Private ordinary functions

F
fave-p: Public ordinary functions
follow-p: Public ordinary functions
follow-request-p: Public ordinary functions
Function, add-command: Public ordinary functions
Function, add-scheme: Private ordinary functions
Function, agetf: Public ordinary functions
Function, api-request: Private ordinary functions
Function, boost-p: Public ordinary functions
Function, bot-post-p: Public ordinary functions
Function, command-dispatch: Private ordinary functions
Function, commandp: Private ordinary functions
Function, current-day: Private ordinary functions
Function, delete-parent: Public ordinary functions
Function, dispatch: Private ordinary functions
Function, dow-for: Private ordinary functions
Function, ensure-list: Private ordinary functions
Function, fave-p: Public ordinary functions
Function, follow-p: Public ordinary functions
Function, follow-request-p: Public ordinary functions
Function, generate-cw: Private ordinary functions
Function, get-mastodon-streaming-url: Private ordinary functions
Function, load-mapping-files: Private ordinary functions
Function, make-bot: Public ordinary functions
Function, mappings-updated-p: Private ordinary functions
Function, mention-p: Public ordinary functions
Function, parse-mapping-file: Private ordinary functions
Function, parse-time: Private ordinary functions
Function, poll-ended-p: Public ordinary functions
Function, post: Public ordinary functions
Function, print-close: Private ordinary functions
Function, print-open: Private ordinary functions
Function, privileged-reply-p: Private ordinary functions
Function, seconds-until: Private ordinary functions
Function, seconds-until-midnight: Private ordinary functions
Function, seconds-until-timestring: Private ordinary functions
Function, terminate-connection: Public ordinary functions
Function, time-to-seconds: Public ordinary functions
Function, upload-media: Private ordinary functions

G
generate-cw: Private ordinary functions
Generic Function, (setf bot-on-delete): Public generic functions
Generic Function, (setf bot-on-notification): Public generic functions
Generic Function, (setf bot-on-update): Public generic functions
Generic Function, bot-account-id: Private generic functions
Generic Function, bot-client: Public generic functions
Generic Function, bot-on-delete: Public generic functions
Generic Function, bot-on-notification: Public generic functions
Generic Function, bot-on-update: Public generic functions
Generic Function, bot-username: Public generic functions
Generic Function, no-bot-p: Public generic functions
Generic Function, reply: Public generic functions
get-mastodon-streaming-url: Private ordinary functions

I
initialize-instance: Public standalone methods

L
load-mapping-files: Private ordinary functions

M
Macro, after: Public macros
Macro, after-every: Public macros
Macro, on: Public macros
Macro, run-bot: Public macros
make-bot: Public ordinary functions
mappings-updated-p: Private ordinary functions
mention-p: Public ordinary functions
Method, (setf bot-on-delete): Public generic functions
Method, (setf bot-on-notification): Public generic functions
Method, (setf bot-on-update): Public generic functions
Method, bot-account-id: Private generic functions
Method, bot-client: Public generic functions
Method, bot-on-delete: Public generic functions
Method, bot-on-notification: Public generic functions
Method, bot-on-update: Public generic functions
Method, bot-username: Public generic functions
Method, initialize-instance: Public standalone methods
Method, no-bot-p: Public generic functions
Method, no-bot-p: Public generic functions
Method, no-bot-p: Public generic functions
Method, reply: Public generic functions

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

O
on: Public macros

P
parse-mapping-file: Private ordinary functions
parse-time: Private ordinary functions
poll-ended-p: Public ordinary functions
post: Public ordinary functions
print-close: Private ordinary functions
print-open: Private ordinary functions
privileged-reply-p: Private ordinary functions

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

S
seconds-until: Private ordinary functions
seconds-until-midnight: Private ordinary functions
seconds-until-timestring: Private ordinary functions

T
terminate-connection: Public ordinary functions
time-to-seconds: Public ordinary functions

U
upload-media: Private ordinary functions