TamTam

TamTam is a Ruby gem to parse, filter, and analyze logs from chat clients. You can filter by various factors: date, participants, or contents.

TamTam is agnostic to operating system and chat client, and ships with adapters for:

• Adium (OS X)

Additional adapters are planned, and welcome via pull request.

On the command line:

gem install tam_tam

Or via Bundler:

gem "tam_tam"

Create a new logs object with the default Adium adapter:

require "tam_tam"
logs = TamTam.new

Specify an adapter:

logs = TamTam.new(adapter: :messages)

List all registered adapters:

TamTam.adapters # [:adium, :messages]

Use a non-standard path for log files:

TamTam.new(path: "/path/to/logs")

When you require "tam_tam", all the included adapters are loaded. If you want to save memory and require only the one(s) you need, you may do so:

require "tam_tam/adapters/adium"

logs = TamTam.new

If an adapter is not provided when calling .new, TamTam defaults to the Adium adapter, or the first registered adapter if the Adium adapter has not been loaded. Details on using custom adapters are included later in this guide.

Logs can be filtered by participants and date. All the filter methods are chainable, and return a new TamTam::Logs object with the filters applied.

Limits logs to the account you were chatting as. Accepts any number of string arguments with the username of the account.

logs.as("MyAIMScreenName")
logs.as("MyAIMScreenName", "google.talk@gmail.com")

Limits logs to the account you were chatting with. Like as, accepts any number of string arguments with the username of the account.

logs.with("MyFriendJoe")
logs.with("MyFriendJoe", "my.secret.crush@gmail.com")

Limits logs to chats that occurred on a particular date. The date can be supplied as a string (any format Chronic accepts) or a temporal object (Date, Time, etc.)

logs.on("September 23, 2013")
logs.on(Date.today)
logs.on(Time.now)

Limits logs to chats that occurred within a date range. Takes two dates, which, like on, can be strings or temporal objects.

logs.between(5.days.ago, Date.today)

Once you have filtered logs down to the set you want, you can examine the messages themselves:

messages = logs.messages

At this point, the logs on disk are loaded into memory, so the first call to messages may take a while, depending on how many logs are being loaded. The messages object is enumerable, and can receive any of the usual iteration and transformation methods.

Messages can be filtered by contents. All the filter methods are chainable and return a new TamTam::MessageSet object with the filters applied.

Limits messages to those that include the provided substring.

messages.including("how do you feel about")

Limits messages to those that match the provided regular expression.

messages.matching(/^lol,?\s+/)

Limits messages to those sent by the provided username.

messages.sent_by("MyFriendJoe")

These methods return interesting data about the messages.

Returns a hash of all the messages grouped by text and the number of times a message with that text was sent. Useful for seeing what messages/phrases you and your chat buddies say most often.

messages.by_count # { "hi" => 4, "how's it going?" => 2 }

When enumerating messages, each message is a TamTam::Message object with the following attributes:

The username of the person who sent the message.

The body of the message.

The date and time the message was sent, as a Time object.

An adapter is a class that inherits from TamTam::Adapter and implements its abstract interface. Once you have defined your adapter class, register it with TamTam:

TamTam.register_adapter(:crazy_chat, CrazyChatAdapter)

Adapters must define the following methods:

• .default_path
• #default_matches
• #load_messages
• #as
• #with
• #on
• #between

See any of the included adapters for examples.

Issues and pull requests are welcome! If you're opening a pull request, please make sure your branch maintains full test coverage (open coverage/index.html after running the specs), and that you don't get any warnings from running cane.

TamTam is available under the MIT license. See the provided LICENSE.txt for details.