Topbot Zephyr Documentation

Topbot Documentation

Topbot is a zephyrbot for automatically recording "Top 10"-style lists. These lists may then be read from the Topbot List of Lists page.

Starting a list

Suppose a list has been forming in the "Top-10.things not to put on your Black Friday Statement" instance. You can tell Topbot to start recording list entries from this instance by sending a zephyrgram to either of the following:

"topbot.create.Top-10.things not to put on your Black Friday Statement"
"Top-10.things not to put on your Black Friday Statement.topbot.create"

Topbot will retroactively record any recent zephyrgrams on the list instance that look like legitimate list entries. In the body of the list creation zephyrgram, you must include a title to be used for the list. For example, if the body reads "Things Not to Put on your Black Friday Statement", that's how the title of the list will read. Topbot will respond with a message including

The new List ID. This List ID is useful for some operations such as retitling and deleting lists.
The zephyr instance currently being associated with the list.
The title of the list.

Note: Topbot will not only log list entries from the instance used to create the list, but will also include entries from instances with names that only differ in puncuation, letter case, etc.

Adding List Entries

To add an entry to a list that's been started, send a zephyrgram to the appropriate instance, e.g. "Top-10.things not to put on your Black Friday Statement". The zephyrgram must begin with an integer followed by a period: for example, "5." or "-10.", or it will be ignored by Topbot.

Removing List Entries

To remove an entry in a list, send a zephyrgram to the list instance, but with ".nuke" appended to it, e.g. "Top-10.things not to put on your Black Friday Statement.nuke". In the body of the zephyrgram, include a list of words that are all contained in the list entry you wish to remove.

Editing List Entries

To edit an entry in a list, send a zephyrgram to the list instance, but with ".edit" appended to it, e.g. "Top-10.things not to put on your Black Friday Statement.edit". In the body of the zephyrgram, you must include one of the following:

A Perl subsitution expression. For example, if the word "fraek" appears in a list entry, you might try "s/fraek/freak/".
"match: ..... replacement .....". The stuff after "match" should be a list of words included in the list entry you wish to edit. The stuff after "replacement:" should be the entire edited version of the list entry.

Undoing Edits and Removes

To undo a list entry edit or removal, send a zephyrgram to the list instance, but with ".undo" appended to it, e.g. "Top-10.things not to put on your Black Friday Statement.undo". The body of the zephyrgram should include a list of words that used to be in the edited/removed list entry.

Changing a List Title

In order to change the title of a list, you must know its "List ID". This List ID is mentioned by Topbot when the list is created, and generally looks something like "list00017".

Send a zephyrgram to the topbot.rename-list instance. In the body, first include the list ID, and then include the new title for the list. For example, if the body is "list00017 Ways to Freak Out your Advisor", the list with ID list00017 will have its title changed to "Ways to Freak Out your Advisor".

Destroying a List

To destroy an existing list, send a zephyrgram to the topbot.nuke-list instance. Include the ID (e.g. "list00017") of the list to destroy. NOTE: this operation cannot be undone. Use with extreme caution.

Associating a Zephyr Instance with an Existing List

You can have Topbot start associating a zephyr instance with an existing list. For example, if list00017 is "Ways to Freak Out Your Advisor", you can reopen this list on the "top ways to freak out your advisor" instance by sending a zephyrgram to one of the following two instances:

"topbot.reopen.top ways to freak out your advisor"
"top ways to freak out your advisor.topbot.reopen"

In the body of the zephyrgram, include the ID of the list you want associated with the instance, e.g. "list00017". As in the creation of new lists, Topbot will retroactively process list entries in recent zephyrgrams on the instance just associated with the list.