tam_tam 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+ideas/*

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+script: bundle exec rake
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jimmy Cuadra
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,200 @@
+# TamTam
+
+[![Build Status](https://travis-ci.org/jimmycuadra/tam_tam.png?branch=master)](https://travis-ci.org/jimmycuadra/tam_tam)
+
+**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.
+
+## Installation
+
+On the command line:
+
+``` bash
+gem install tam_tam
+```
+
+Or via Bundler:
+
+``` ruby
+gem "tam_tam"
+```
+
+## Usage
+
+### Instantiation
+
+Create a new logs object with the default Adium adapter:
+
+``` ruby
+require "tam_tam"
+logs = TamTam.new
+```
+
+Specify an adapter:
+
+```ruby
+logs = TamTam.new(adapter: :messages)
+```
+
+List all registered adapters:
+
+``` ruby
+TamTam.adapters # [:adium, :messages]
+```
+
+Use a non-standard path for log files:
+
+``` ruby
+TamTam.new(path: "/path/to/logs")
+```
+
+#### Limiting the loaded adapters
+
+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:
+
+``` ruby
+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.
+
+### Filtering logs
+
+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.
+
+#### #as
+
+Limits logs to the account you were chatting as. Accepts any number of string arguments with the username of the account.
+
+``` ruby
+logs.as("MyAIMScreenName")
+logs.as("MyAIMScreenName", "google.talk@gmail.com")
+```
+
+#### #with
+
+Limits logs to the account you were chatting with. Like `as`, accepts any number of string arguments with the username of the account.
+
+``` ruby
+logs.with("MyFriendJoe")
+logs.with("MyFriendJoe", "my.secret.crush@gmail.com")
+```
+
+#### #on
+
+Limits logs to chats that occurred on a particular date. The date can be supplied as a string (any format [Chronic](https://github.com/mojombo/chronic "Chronic") accepts) or a temporal object (`Date`, `Time`, etc.)
+
+``` ruby
+logs.on("September 23, 2013")
+logs.on(Date.today)
+logs.on(Time.now)
+```
+
+#### #between
+
+Limits logs to chats that occurred within a date range. Takes two dates, which, like `on`, can be strings or temporal objects.
+
+``` ruby
+logs.between(5.days.ago, Date.today)
+```
+
+### Accessing messages
+
+Once you have filtered logs down to the set you want, you can examine the messages themselves:
+
+``` ruby
+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.
+
+### Filtering messages
+
+Messages can be filtered by contents. All the filter methods are chainable and return a new `TamTam::MessageSet` object with the filters applied.
+
+#### #including
+
+Limits messages to those that include the provided substring.
+
+``` ruby
+messages.including("how do you feel about")
+```
+
+#### #matching
+
+Limits messages to those that match the provided regular expression.
+
+``` ruby
+messages.matching(/^lol,?\s+/)
+```
+
+#### #sent_by
+
+Limits messages to those sent by the provided username.
+
+``` ruby
+messages.sent_by("MyFriendJoe")
+```
+
+### Analyzing logs
+
+These methods return interesting data about the messages.
+
+#### #by_count
+
+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.
+
+``` ruby
+messages.by_count # { "hi" => 4, "how's it going?" => 2 }
+```
+
+### Individual messages
+
+When enumerating messages, each message is a `TamTam::Message` object with the following attributes:
+
+#### #sender
+
+The username of the person who sent the message.
+
+#### #text
+
+The body of the message.
+
+#### #time
+
+The date and time the message was sent, as a `Time` object.
+
+## Custom adapters
+
+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:
+
+``` ruby
+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.
+
+## Contributing
+
+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`.
+
+## License
+
+TamTam is available under the MIT license. See the provided `LICENSE.txt` for details.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "cane/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+Cane::RakeTask.new(:quality) do |cane|
+  cane.add_threshold "coverage/covered_percent", :>=, 100
+end
+
+task :default => [:spec, :quality]

data/lib/tam_tam.rb

@@ -0,0 +1 @@
+require "tam_tam/adapters/adium"

data/lib/tam_tam/adapter.rb

@@ -0,0 +1,29 @@
+require "tam_tam/core"
+require "tam_tam/log_set"
+
+module TamTam
+  # An exception to raise when abstract methods have not been implemented.
+  class AbstractMethodError < StandardError; end
+
+  # An abstract base class for all adapters.
+  class Adapter
+    attr_accessor :path
+
+    def initialize(path = nil)
+      self.path = path || self.class.default_path
+    end
+
+    def to_s
+      %{#<#{self.class.name}:0x#{object_id.to_s(16)} path="#{path}">}
+    end
+    alias_method :inspect, :to_s
+
+    %w[default_matches load_messages as with on between].each do |method|
+      define_method(method) do
+        raise AbstractMethodError.new(
+          "##{method} must be defined in the adapter."
+        )
+      end
+    end
+  end
+end

data/lib/tam_tam/adapters/adium.rb

@@ -0,0 +1,58 @@
+require "tam_tam/adapter"
+
+require "nokogiri"
+
+module TamTam
+  module Adapters
+    # Adapter for Adium. http://adium.im/
+    class Adium < Adapter
+      def self.default_path
+        "#{Dir.home}/Library/Application Support/Adium 2.0/Users/Default/Logs"
+      end
+
+      def default_matches
+        Dir["#{path}/**/*.xml"]
+      end
+
+      def load_messages(matches)
+        matches.map do |log_path|
+          xml = File.read(log_path)
+          doc = Nokogiri.parse(xml)
+
+          doc.css("chat message").map do |message|
+            {
+              sender: message.attribute("sender").value,
+              text: message.text,
+              time: Chronic.parse(message.attribute("time").value)
+            }
+          end
+        end.flatten
+      end
+
+      def as(accounts)
+        Dir["#{path}/*\.{#{accounts.join(',')}}/**/*.xml"]
+      end
+
+      def with(participants)
+        Dir["#{path}/*\.*/{#{participants.join(',')}}/**/*.xml"]
+      end
+
+      def on(start)
+        Dir["#{path}/**/*#{start.to_date.to_s}*/*.xml"]
+      end
+
+      def between(start, stop)
+        start = start.to_date
+        stop = stop.to_date
+
+        default_matches.select do |log|
+          match = log.match(/(\d{4})-(\d{2})-(\d{2})/)
+          log_date = Time.new(match[1], match[2], match[3]).to_date
+          log_date >= start && log_date <= stop
+        end
+      end
+    end
+  end
+
+  register_adapter :adium, Adapters::Adium
+end

data/lib/tam_tam/core.rb

@@ -0,0 +1,28 @@
+require "tam_tam/version"
+
+# The primary entry point for users.
+module TamTam
+  @adapters ||= {}
+
+  class << self
+    def new(options = {})
+      adapter_key = options[:adapter]
+      adapter_key = :adium if adapter_key.nil? && adapters.include?(:adium)
+      adapter_key = adapters.first if adapter_key.nil?
+      adapter = @adapters[adapter_key].new(options[:path])
+      LogSet.new(adapter)
+    end
+
+    def register_adapter(key, adapter)
+      @adapters[key] = adapter
+    end
+
+    def unregister_adapter(key)
+      @adapters.delete(key)
+    end
+
+    def adapters
+      @adapters.keys
+    end
+  end
+end

data/lib/tam_tam/log_set.rb

@@ -0,0 +1,59 @@
+require "tam_tam/message_set"
+
+require "chronic"
+
+module TamTam
+  # A set of chat logs. Responsible for filtering at the chat log level.
+  # Delegates to the adapter for client-specific behavior.
+  class LogSet
+    attr_accessor :adapter, :matches
+
+    def initialize(adapter)
+      self.adapter = adapter
+      self.matches = adapter.default_matches
+    end
+
+    def messages
+      @messages ||= MessageSet.new(adapter.load_messages(matches))
+    end
+
+    def as(*accounts)
+      filter(adapter.as(accounts))
+    end
+
+    def with(*participants)
+      filter(adapter.with(participants))
+    end
+
+    def on(start)
+      start = Chronic.parse(start) if start.is_a?(String)
+      filter(adapter.on(start))
+    end
+
+    def between(start, stop)
+      start = Chronic.parse(start) if start.is_a?(String)
+      stop = Chronic.parse(stop) if stop.is_a?(String)
+      filter(adapter.between(start, stop))
+    end
+
+    def to_s
+      %{#<#{self.class.name}:0x#{object_id.to_s(16)} adapter=#{adapter.to_s}>}
+    end
+    alias_method :inspect, :to_s
+
+    protected
+
+    def clear_messages_cache
+      @messages = nil if defined?(@messages)
+    end
+
+    private
+
+    def filter(filter_matches)
+      copy = dup
+      copy.clear_messages_cache
+      copy.matches = matches & filter_matches
+      copy
+    end
+  end
+end