Yii 1.1: The MrFisk IRC Bot

6 followers

Introduction

MrFisk is a sleek little bot hanging out in the official #yii IRC channel on freenode, meant to serve Yii users with documentation lookups and other things. This document intends to provide a summary of what MrFisk can do for you and how to use his fin^H^Heatures.

Please note: MrFisk is currently (2012-08-24) in a non-finished but working state. He's been put online and joined #yii earlier than what was originally intented, simply due to the original YiiBot having been absent for a over a week. We needed a bot in the channel, and this one was close to ready. What is missing is primarily fuzzy matching of !{doc,api} queries, editing of factoids and some other new features currently not present in any of the bots.

The !faq <query> command

This command returns the factoid for the given query. It's simply a quick way to make the bot spell out things we repeat often, and what not. Note: Currently the factoid database is static, based on what could be found in YiiBot's online list.

A list of the current faqs/factoids can be found here.

The !php <query> command

All this command does is return an URL to php.net's manual search result for the given query.

The !lmgtfy <query> command

All this command does is return an URL to a search for the given query at lmgtfy.com.

The !google <query> command

All this command does is return the results from Googling the given query. Note: This command does not work with the addressing and inline commands feature (see below). The reason for this is that the Google functionality is provided by another plugin than MrFisk.

The !doc <query> and !api <query> commands

These two commands work on the same data, but return slightly different results. Both of them ask for information about a class, property, method or even method parameters in the Yii core framework classes (i.e. the same stuff that you can find in the online API reference).

The results for the !doc command contain a summary of the found item's signature, a short description, and an URL to the online Yii API reference. This is the one you normally want to use.

The results for the !api command is more technical, containing the full signature of the found item, the short description, and then URL to the online Yii API reference. You probably only use this command when you want to quickly see the full signature for something.

The query for both of these commands should be written in one of the following ways:

  • fish = No special signs around the keyword asks for both classes, properties and methods named fish; There's no filtering of the result in this case.
  • foo. = A dot after the keyword asks for classes only.
  • .bar = A dot before the keyword asks for members (properties and methods) only.
  • $bar = A $ sign before the keyword asks for properties only.
  • bar() = Adding () after the keyword asks for methods only.
  • foo.bar = A class name before a member asks for members of that class only.
  • foo.$bar = A $ sign before the member keyword asks for a property only.
  • foo.bar() = Adding () after the member keyword asks for a method only.
  • foo.bar(2) = A number inside the () for a method asks for the parameter with that index.
  • foo.bar(ho) = Characters inside the () for a method asks for the parameter whos name matches the characters. This example would match bar($htmlOptions) and bar($home).

Note: In all examples above, the . can be substituted for :: or -> as well; foo::bar and foo->bar is the same as foo.bar.

If there is only one result (or "hit") from processing the query, that result is returned. If there is more than one result, a choice list is returned, asking you to narrow down the result. Choice lists are described later on in this document.

Multiple query words (quoting)

It's possible to supply more than one word in the query to most of the commands, by simply wrapping/delimiting the query in/with single or double quotes. For example !php 'pattern matching' and !php "pattern matching" would return the PHP manual URL for the search term "pattern matching".

To include a quote in the actual query without having it be used as a delimiter, there are two options; Either simply use the other type of quotes to delimit the query, or escape the quote with a backslash. For example, to provide a LMGTFY URL for a common phrase and retain its quoting, one could do !lmgtfy '"date.timezone"' or !lmgtfy '\'date.timezone\'' - both works.

Within quoted queries, beginning and ending whitespace is removed. Please also note that unbalanced quotes will not match, they have to be a pair and of the same type (i.e. a mix of ' and " won't work). If the query isn't correctly quoted, it will be parsed as a one-word query.

Inline commands

The commands !doc, !api, !faq and !php can be used "inline" as well, which is useful when you want to show another user something.

For example, if the user Bob wants to show the user Alice the where() function, he can do it like this: Alice: You can use the !doc where() method to do that. Try it, but not before reading the next section, about making the bot address other users!

Making the bot address another user

This is an awesome feature. When giving the bot a command, you can make it return the result to another user by providing their nick in one of the following ways:

  • nick: message or command
  • @nick message or command
  • @ nick message or command
  • message or command @nick
  • message or command @ nick

For example, !doc where() @ Alice will address the result to the user Alice, and so will Alice: Check out !doc where(). It works with inline commands as well.

There is one exception to this addressing feature; When a query, for example !doc getdata, returns a choice list, that list is always returned to the use who made the request to the bot. This is intentional. However, when a choice is made from the list, the final result is returned to the user that was initially addressed (or the one making the query, if no addressing was done).

Choice lists and the !<n> [nick] command

As mentioned before, some commands may return a list of choices. When that happens, the user who made the query can make a choice by giving the command !<n>, where <n> is the number of the item in the list that should be used.

If there are too many choices to fit in one response, there will be a [>>] choice listed at the very end. Selecting this choice will make the list continue in a subsequent reponse. Please try it.

Note: You do not need to request a list more than one time in order to make multiple choices; Just pick for example !3 followed by !5 and !2 if you want or need to.

If you ever see a choice list being generated for a query someone else does, and you are curious about one of its items, you can pick a choice from that list even if it doesn't belong to you. You do that by adding the other user's nick to the command. For example, if Bob wants to pick the third choice from a list Alice was given, he can do !3 Alice. Alice's list will then be copied to Bob as well, so each user will have their own separate list to play with.

If a choice list is never used (i.e. no choice is being made), it will expire after a while. If a choice is made, it will take longer to expire, but will eventually. When lists are copied, as mentioned previously, they will have their own expiry timers.

Questions and answers

Q: Why do results look weird (for example Foo->$bar instead of Foo::bar)?
A: Because Foo->$bar provides additional info that Foo::bar does not. Instead of the conventional notations Foo::bar and Foo.bar it is more informative and less confusing if we adhere to the following:

  • :: = Static member follows
  • -> = Non-static member follows
  • $ = Used to denote a property, even when following a class and :: or ->

An example of otherwise potential confusion is whether Foo::bar would mean a property or method.
An example of otherwise potential ambiguity is whether Foo::bar is really a static member or not.
In the example of Foo->$bar we directly know that bar is a) a property and b) non-static.

Q: Who created MrFisk?
A: MrFisk is based on Phergie (it's actually a plugin to it), so for that part all the credit goes to the Phergie authors.

The actual MrFisk idea and code is however the creation of rawtaz, a frequent idler in #yii, with the help from tom[] who spent a lot of time providing comments, ideas and helping out with testing. tom[] also compiled the initial factoid database, out of the online (and outdated) one from YiiBot. Thank you very much!

Naturally credit also goes out to tydeas and ciss for creating the first bot of #yii - YiiBot, which has been serving the channel very well for over two years.

Hadn't blindMoe been so busy eating sushi he might have made it to this list too ;-)

Q: Why was MrFisk created? Didn't we have a bot already?
A: Indeed we did. There's no specific reason for this bot coming into existance, other than the desire of its author to do some hobby coding, and the idea to make a much cooler bot than the old one (where cooler means much more flexible commands, query parsing and searching, as well as other things that are planned).

As of 2012-08-28 YiiBot is officially retired. MrFisk will keep serving the channel.

Changelog

2013-11-05: Added support for multi-word queries in the !faq, !php, !lmgtfy, !doc and !api commands, both inline and not inline.

2013-08-29: Added the !lmgtfy command.

2013-01-16: Made nick addressing not trigger on nick, as it was often conflicting with messages like "btw, check out !faq foo".

2012-08-27: Changed !api command to return an URL to the online API reference instead of to the source code for the result.

Be the first person to leave a comment

Please to leave your comment.

Write new article
  • Written by: rAWTAZ
  • Category: Others
  • Yii Version: 1.1
  • Votes: +5
  • Viewed: 11,929 times
  • Created on: Aug 23, 2012
  • Last updated: Nov 4, 2013
  • Tags: MrFisk, YiiBot, IRC, bot