Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
The glacier Reference Manual
This is the glacier Reference Manual, version 0.3, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:54:18 2022 GMT+0.
Table of Contents
Next: Systems, Previous: The glacier Reference Manual, Up: The glacier Reference Manual [Contents][Index]
1 Introduction
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-bot :instance "mastodon.social" :access-token "n0tArealT0KEn"))
(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-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-bot :config-file "/path/to/bot.config")))
API
make-bot (&key config-file instance access-token (strip-html t) strip-username (timeline "user") on-update on-delete on-notification)
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
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 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.
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
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
no-bot-p (account-or-mention)
returns T if ACCOUNT (or account from MENTION) has #NoBot in their profile's bio
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
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
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: Files, Previous: Introduction, Up: The glacier Reference Manual [Contents][Index]
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.3
- 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
- Child Components
- package.lisp (file).
- bot.lisp (file).
- extensions.lisp (file).
- util.lisp (file).
- glacier.lisp (file).
Next: Packages, Previous: Systems, Up: The glacier Reference Manual [Contents][Index]
3 Files
Files are sorted by type and then listed depth-first from the systems components trees.
3.1 Lisp
- glacier/glacier.asd
- glacier/package.lisp
- glacier/bot.lisp
- glacier/extensions.lisp
- glacier/util.lisp
- glacier/glacier.lisp
Next: glacier/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
3.1.1 glacier/glacier.asd
- Source
- Parent Component
glacier (system).
- ASDF Systems
Next: glacier/bot.lisp, Previous: glacier/glacier.asd, Up: Lisp [Contents][Index]
3.1.2 glacier/package.lisp
- Source
- Parent Component
glacier (system).
- Packages
Next: glacier/extensions.lisp, Previous: glacier/package.lisp, Up: Lisp [Contents][Index]
3.1.3 glacier/bot.lisp
- Dependency
package.lisp (file).
- Source
- Parent Component
glacier (system).
- Public Interface
- *command-prefix* (special variable).
- bot-client (reader method).
- bot-client (class).
- bot-on-delete (reader method).
- (setf bot-on-delete) (writer method).
- bot-on-notification (reader method).
- (setf bot-on-notification) (writer method).
- bot-on-update (reader method).
- (setf bot-on-update) (writer method).
- bot-username (reader method).
- initialize-instance (method).
- make-bot (function).
- mastodon-bot (class).
- Internals
- *bot* (special variable).
- *commands* (special variable).
- *privileged-commands* (special variable).
- bot-account-id (reader method).
Next: glacier/util.lisp, Previous: glacier/bot.lisp, Up: Lisp [Contents][Index]
3.1.4 glacier/extensions.lisp
- Dependency
bot.lisp (file).
- Source
- Parent Component
glacier (system).
- Public Interface
- Internals
- *no-bot-regex* (special variable).
- api-request (function).
- upload-media (function).
Next: glacier/glacier.lisp, Previous: glacier/extensions.lisp, Up: Lisp [Contents][Index]
3.1.5 glacier/util.lisp
- Dependency
extensions.lisp (file).
- Source
- Parent Component
glacier (system).
- Public Interface
- add-command (function).
- after (macro).
- after-every (macro).
- agetf (function).
- boost-p (function).
- bot-post-p (function).
- delete-parent (function).
- fave-p (function).
- follow-p (function).
- follow-request-p (function).
- mention-p (function).
- on (macro).
- poll-ended-p (function).
- Internals
- add-scheme (function).
- commandp (function).
- current-day (function).
- dow-for (function).
- get-mastodon-streaming-url (function).
- parse-time (function).
- print-close (function).
- print-open (function).
- privileged-reply-p (function).
- seconds-until (function).
- seconds-until-midnight (function).
- seconds-until-timestring (function).
Previous: glacier/util.lisp, Up: Lisp [Contents][Index]
3.1.6 glacier/glacier.lisp
- Dependency
util.lisp (file).
- Source
- Parent Component
glacier (system).
- Public Interface
- run-bot (macro).
- terminate-connection (function).
- Internals
- *websocket-client* (special variable).
- command-dispatch (function).
- dispatch (function).
Next: Definitions, Previous: Files, Up: The glacier Reference Manual [Contents][Index]
4 Packages
Packages are listed by definition order.
4.1 glacier
- Source
- Use List
common-lisp.
- Public Interface
- *command-prefix* (special variable).
- add-command (function).
- after (macro).
- after-every (macro).
- agetf (function).
- boost-p (function).
- bot-client (generic reader).
- bot-client (class).
- bot-on-delete (generic reader).
- (setf bot-on-delete) (generic writer).
- bot-on-notification (generic reader).
- (setf bot-on-notification) (generic writer).
- bot-on-update (generic reader).
- (setf bot-on-update) (generic writer).
- bot-post-p (function).
- bot-username (generic reader).
- delete-parent (function).
- fave-p (function).
- follow-p (function).
- follow-request-p (function).
- make-bot (function).
- mastodon-bot (class).
- mention-p (function).
- no-bot-p (generic function).
- on (macro).
- poll-ended-p (function).
- post (function).
- reply (generic function).
- run-bot (macro).
- terminate-connection (function).
- Internals
- *bot* (special variable).
- *commands* (special variable).
- *no-bot-regex* (special variable).
- *privileged-commands* (special variable).
- *websocket-client* (special variable).
- add-scheme (function).
- api-request (function).
- bot-account-id (generic reader).
- command-dispatch (function).
- commandp (function).
- current-day (function).
- dispatch (function).
- dow-for (function).
- get-mastodon-streaming-url (function).
- parse-time (function).
- print-close (function).
- print-open (function).
- privileged-reply-p (function).
- seconds-until (function).
- seconds-until-midnight (function).
- seconds-until-timestring (function).
- upload-media (function).
Next: Indexes, Previous: Packages, Up: The glacier Reference Manual [Contents][Index]
5 Definitions
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
5.1 Public Interface
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
5.1.1 Special variables
- Special Variable: *command-prefix* ¶
-
character or string that prefixes a command
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [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
- 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
- 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
- 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
- Source
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
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)
- Function: agetf (place indicator &optional default) ¶
-
getf but for alists
- Function: boost-p (notification) ¶
-
checks if NOTIFICATION is a boost
- Function: bot-post-p (status) ¶
-
checks if STATUS was posted by the bot
- Function: delete-parent (status) ¶
-
deletes the parent post of STATUS if it was posted by the bot
- Function: fave-p (notification) ¶
-
checks if NOTIFICATION is a favourite
- Function: follow-p (notification) ¶
-
checks if NOTIFICATION is a follow
- Function: follow-request-p (notification) ¶
-
checks if NOTIFICATION is a follow request
- Function: make-bot (&key config-file instance access-token strip-html strip-username timeline on-update on-delete on-notification) ¶
-
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
- Function: mention-p (notification) ¶
-
checks if NOTIFICATION is a mention
- Function: poll-ended-p (notification) ¶
-
checks if NOTIFICATION is a poll
- Function: post (text &key visibility cw sensitive media) ¶
-
a thin wrapper around tooter:make-status
see documentation for that function
- Package
- Source
- Function: terminate-connection () ¶
-
closes the websocket connection and clears the variable from memory
- Package
- Source
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
5.1.4 Generic functions
- Generic Reader: bot-client (object) ¶
-
- Package
- Methods
- Reader Method: bot-client ((mastodon-bot mastodon-bot)) ¶
-
automatically generated reader method
- Generic Reader: bot-on-delete (object) ¶
-
- Package
- Methods
- Reader Method: bot-on-delete ((mastodon-bot mastodon-bot)) ¶
-
automatically generated reader method
- Generic Writer: (setf bot-on-delete) (object) ¶
-
- Package
- Methods
- Writer Method: (setf bot-on-delete) ((mastodon-bot mastodon-bot)) ¶
-
automatically generated writer method
- Generic Reader: bot-on-notification (object) ¶
-
- Package
- Methods
- Reader Method: bot-on-notification ((mastodon-bot mastodon-bot)) ¶
-
automatically generated reader method
- Source
- Target Slot
- Generic Writer: (setf bot-on-notification) (object) ¶
-
- Package
- Methods
- Writer Method: (setf bot-on-notification) ((mastodon-bot mastodon-bot)) ¶
-
automatically generated writer method
- Source
- Target Slot
- Generic Reader: bot-on-update (object) ¶
-
- Package
- Methods
- Reader Method: bot-on-update ((mastodon-bot mastodon-bot)) ¶
-
automatically generated reader method
- Generic Writer: (setf bot-on-update) (object) ¶
-
- Package
- Methods
- Writer Method: (setf bot-on-update) ((mastodon-bot mastodon-bot)) ¶
-
automatically generated writer method
- Generic Reader: bot-username (object) ¶
-
- Package
- Methods
- Reader Method: bot-username ((mastodon-bot mastodon-bot)) ¶
-
automatically generated reader method
- Source
- Target Slot
- Generic Function: no-bot-p (id) ¶
-
- Package
- Methods
- Method: no-bot-p ((mention mention)) ¶
-
checks account found in MENTION to see if they have NoBot set
- Source
- Method: no-bot-p ((account account)) ¶
-
checks an account’s bio and profile fields to see if they contain a NoBot tag
- Source
- Method: no-bot-p ((id string)) ¶
-
checks an account’s bio and profile fields to see if they contain a NoBot tag
- Source
- Generic Function: reply (status text &key include-mentions media cw sensitive visibility) ¶
-
- Package
- 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
Next: Classes, Previous: Generic functions, Up: Public Interface [Contents][Index]
5.1.5 Standalone methods
- Method: initialize-instance :after ((bot mastodon-bot) &rest initargs &key config-file instance token strip-html strip-username timeline &allow-other-keys) ¶
-
- Source
Previous: Standalone methods, Up: Public Interface [Contents][Index]
5.1.6 Classes
- Class: bot-client ¶
- Class: mastodon-bot ¶
-
bot superclass
- Package
- Source
- Direct methods
- Direct slots
- Slot: on-update ¶
-
- Initargs
:on-update
- Readers
- Writers
- Slot: on-delete ¶
-
- Initargs
:on-delete
- Readers
- Writers
- Slot: on-notification ¶
-
- Initargs
:on-notification
- Readers
- Writers
- Slot: account-id ¶
-
- Readers
- Writers
This slot is read-only.
- Slot: account-username ¶
-
- Readers
- Writers
This slot is read-only.
- Slot: client ¶
-
- Readers
- Writers
This slot is read-only.
Previous: Public Interface, Up: Definitions [Contents][Index]
5.2 Internals
Next: Ordinary functions, Previous: Internals, Up: Internals [Contents][Index]
5.2.1 Special variables
- 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
- Special Variable: *no-bot-regex* ¶
-
regex to check for the NoBot tag
- Package
- Source
- 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
- Special Variable: *websocket-client* ¶
-
global websocket client
- Package
- Source
Next: Generic functions, Previous: Special variables, Up: Internals [Contents][Index]
5.2.2 Ordinary functions
- Function: add-scheme (domain) ¶
-
adds https scheme to DOMAIN if it isnt already there
- 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
- Source
- 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
- Source
- Function: dispatch (message) ¶
-
gets the type of MESSAGE we received and calls the appropriate functions on our bot with the proper tooter object
- Package
- Source
- Function: get-mastodon-streaming-url () ¶
-
gets the websocket url for the mastodon instance
- Function: parse-time (amount duration) ¶
-
parses AMOUNT of DURATION into seconds
- Function: print-close (&key code reason) ¶
-
prints a message when the websocket is closed
- Function: print-open () ¶
-
prints a message when the websocket is connected
- Function: privileged-reply-p (status) ¶
-
returns T if STATUS is from an account that the bot follows
- 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
- Function: seconds-until-midnight () ¶
-
returns how many seconds until it’s midnight
- 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
- 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
- Source
Previous: Ordinary functions, Up: Internals [Contents][Index]
5.2.3 Generic functions
- Generic Reader: bot-account-id (object) ¶
-
- Package
- Methods
- Reader Method: bot-account-id ((mastodon-bot mastodon-bot)) ¶
-
automatically generated reader method
- Source
- Target Slot
Previous: Definitions, Up: The glacier Reference Manual [Contents][Index]
Appendix A Indexes
A.2 Functions
| Jump to: | (
A B C D F G I M N O P R S T U |
|---|
| Jump to: | (
A B C D F G I M N O P R S T U |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
A.3 Variables
| Jump to: | *
A C O S |
|---|
| Jump to: | *
A C O S |
|---|
A.4 Data types
| Jump to: | B C E F G M P S U |
|---|
| Jump to: | B C E F G M P S U |
|---|