bitsa 0.10

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    bitsa (0.10.beta3)
+      gdata (= 1.1.1)
+      trollop (= 1.15)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    fakeweb (1.2.8)
+    gdata (1.1.1)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+    trollop (1.15)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bitsa!
+  bundler (>= 1.0.0)
+  fakeweb (~> 1.2.8)
+  gdata (= 1.1.1)
+  rspec (~> 2.0.0.beta.22)
+  trollop (= 1.15)

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.10 25 April 2011
+
+* 1 major enhancement:
+  * Initial release

data/README.md

@@ -0,0 +1,117 @@
+# Bitsa
+
+* <http://github.com/colbell/bitsa>
+
+
+A command line tool to access your GMail/Google Apps contacts. Designed to be used
+from Mutt but should be able to be used from any email client that
+supports calling external programs.
+
+
+## Installation
+
+    gem install bitsa
+
+
+## Configuration 
+
+Bitsa is configured through the configuration file
+`~/.bitsa_config.yml`. Use your GMail (or Google Apps) email address
+for the login.
+
+    ---
+    :login: myself@gmail.com
+    :password: mypassword
+    :cache_file_path: ~/.bitsa_cache.yml
+
+The configuration file is not mandatory, you can pass in your email address
+and password on the command line, see [Usage](#usage).    
+
+If you have no configuration file or if `cache_file_path` is not specified in the
+configuration file it will default to `~/.bitsa_cache.yml`
+
+If you store your email password in the configuration file you should
+ensue that it is only readable by you:
+
+    chmod 0600 .bitsa_config.yml
+
+
+## <a name="usage">Usage</a>
+
+    Usage: bitsa [global-options] [subcommand] [command-opts]
+    
+    Global options are:
+      --config-file, -c <s>:   Configuration file (default: ~/.bitsa_config.yml)
+            --login, -l <s>:   Login
+         --password, -p <s>:   Password
+    
+    bitsa sub-commands
+       update: get the latest changes from Gmail
+       reload: Clear all cached addresses and reload from Gmail
+       search: Search for the passed string
+    
+    Information about this program
+              --version, -v:   Print version and exit
+                 --help, -h:   Show this message
+    
+
+To search for all contacts that contain the string rob:
+
+    $ bitsa search rob
+    
+    Rob_Smith@example.com.au	Robert Smith
+    Rob_Smith@example.com  	Robert Smith
+    robert@example.com	        Robert Jones
+    jeff@example.net	Robert Smith
+    bob@robertsystems	Robert Brown
+
+The first time you run Bitsa and then if it has been more than a day
+since it was last updated it will get the latest changes from your
+GMail contacts and copy them to a local cache (~/.bitsa_cache.yml).
+
+You can update your cache with the latest changes at any time by using
+the `update` sub-command:
+
+    $ bitsa update
+
+If you want to clear your local cache and reload from GMail use the
+`reload` sub-command:
+
+    $ bitsa reload
+
+## Usage - Mutt
+
+To use for address lookup (&lt;ctrl&gt; t) in Mutt put the following in your
+`~/.muttrc` file:
+
+    set query_command = "bitsa search '%s'"
+
+## Testing
+
+To run the tests after cloning the repository you first need to
+install the required libraries:
+
+    bundle install
+
+And then you can run the tests:
+
+    rake spec
+
+## License:
+
+Copyright 2011 Colin Bell.
+
+Bitsa is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+* * * * *

data/Rakefile

@@ -0,0 +1,10 @@
+#require 'rubygems'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'fileutils'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require './lib/bitsa'
+
+Dir['tasks/**/*.rake'].each { |t| load t }

data/bin/bitsa

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+#
+#
+# Copyright 2011 Colin Noel Bell.
+#
+# This file is part of Bitsa.
+#
+# Bitsa is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# begin
+#   require 'rubygems'
+# rescue LoadError
+# end
+
+require "bitsa"
+require "bitsa/args_processor"
+
+args = Bitsa::ArgsProcessor.new
+args.parse(ARGV)
+
+app = Bitsa::BitsaApp.new
+app.run(args.global_opts, args.cmd, args.search_data)
+

data/bitsa.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "bitsa/version"
+
+Gem::Specification.new do |s|
+  s.name        = "bitsa"
+  s.version     = Bitsa::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Colin Noel Bell"]
+  s.email       = ["col@baibell.org"]
+  s.homepage    = "https://github.com/colbell/bitsa"
+  s.summary     = %q{Command line GMail Contacts lookup tool.}
+  s.description = %q{Allows you to lookup GMail contacts and cache contacts locally from the command line.}
+
+  s.required_rubygems_version = ">= 1.3.6"
+
+  s.add_dependency "trollop", "1.15"
+  s.add_dependency "gdata", "1.1.1"
+
+  s.add_development_dependency "bundler", ">= 1.0.0"
+  s.add_development_dependency "rspec", "~> 2.0.0.beta.22"
+  s.add_development_dependency "fakeweb", "~> 1.2.8"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_path  = "lib"
+end

data/lib/bitsa.rb

@@ -0,0 +1,50 @@
+# Copyright 2011 Colin Bell.
+#
+# This file is part of Bitsa.
+#
+# Bitsa is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require "bitsa/config_file"
+require "bitsa/contacts_cache"
+require "bitsa/gmail_contacts_loader"
+require "bitsa/settings"
+
+module Bitsa
+
+  # Application entry point.
+  class BitsaApp
+
+    # Run application.
+    def run(global_opts, cmd, search_data)
+      settings = Settings.new
+      settings.load(ConfigFile.new(global_opts[:config_file]), global_opts)
+      cache = ContactsCache.new(settings.cache_file_path, 1)
+
+      if cmd == "reload"
+        cache.clear!
+      end
+
+      if ["reload", "update"].include?(cmd) || cache.stale?
+        loader = GmailContactsLoader.new(settings.login, settings.password)
+        loader.update_cache(cache)
+      end
+
+      if cmd == "search"
+        puts "" # Force first entry to be displayed in mutt
+        cache.search(search_data).each {|k,v| puts "#{k}\t#{v}"}
+      end
+    end
+  end
+
+end

data/lib/bitsa/args_processor.rb

@@ -0,0 +1,80 @@
+# Command line arguments handler
+#
+# Copyright (C) 2011 Colin Noel Bell.
+#
+# This file is part of Bitsa.
+#
+# Bitsa is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "trollop"
+
+require "bitsa/version"
+
+module Bitsa #:nodoc:
+
+  # Arguments passed on the command line. Trollop http://trollop.rubyforge.org
+  # is used to handle the parsing.
+  class ArgsProcessor
+    # Valid commands.
+    SUB_COMMANDS = %w(update reload search)
+
+    # Global options passed on the command line.
+    attr_reader :global_opts
+
+    # The command to execute
+    attr_reader :cmd
+
+    # Data to search cached contacts for.
+    attr_reader :search_data
+
+    # Parse arguments and setup attributes. If invalid data is passed a
+    # Trollop exception is thrown and the program terminated.
+    #
+    # It also handles showing the Help and Version information.
+    def parse(args)
+      @global_opts = Trollop::options(args) do
+        version "bitsa v#{Bitsa::VERSION}"
+        banner <<EOS
+Usage: bitsa [global-options] [subcommand] [command-opts]
+
+Global options are:
+EOS
+        opt :config_file, "Configuration file", :default => "~/.bitsa_config.yml"
+        opt :login, "Login", :type => String
+        opt :password, "Password", :type => String
+
+        stop_on SUB_COMMANDS
+
+        banner <<EOS
+
+bitsa subcommands
+   update: get the latest changes from Gmail
+   reload: Clear all cached addresses and reload from Gmail
+   search: Search for the passed string
+
+Information about this program
+EOS
+      end
+
+      @cmd = args.shift || ''
+      @search_data = ''
+
+      if cmd == "search"
+        @search_data << args.shift unless args.empty?
+      elsif !["search", "update", "reload"].include?(cmd)
+        Trollop::die "unknown subcommand '#{cmd}'"
+      end
+    end
+  end
+end

data/lib/bitsa/config_file.rb

@@ -0,0 +1,39 @@
+# Loads configuration data from configuration file.
+#
+# Copyright (C) 2011 Colin Noel Bell.
+#
+# This file is part of Bitsa.
+#
+# Bitsa is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "yaml"
+
+module Bitsa #:nodoc:
+
+  # Loads configuration data from a yaml file.
+  class ConfigFile
+
+    # Loaded configuration data as a Hash.
+    attr_reader :data
+
+    # Load data from passed file path.
+    def initialize(config_file_path_name)
+      c_f_n = File.expand_path(config_file_path_name)
+      if File.exist?(c_f_n)
+        @data = YAML.load_file(c_f_n)
+      end
+      @data = {} unless @data
+    end
+  end
+end

data/lib/bitsa/contacts_cache.rb

@@ -0,0 +1,100 @@
+# Cache of Contacts.
+#
+# Copyright (C) 2011 Colin Noel Bell.
+#
+# This file is part of Bitsa.
+#
+# Bitsa is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "forwardable"
+
+module Bitsa #:nodoc:
+
+  # Cache of Contacts.
+  class ContactsCache
+    extend Forwardable
+
+    # Number of entries in cache.
+    def_delegator :@addresses, :size
+
+    # True if cache is empty.
+    def_delegator :@addresses, :empty?
+
+    # Date/Time cache was last updated.
+    attr_accessor :source_last_modified
+
+    # Load cache from file system. After <tt>lifespan_days</tt> the cache is considered stale. 
+    def initialize(cache_file_path, lifespan_days)
+      @cache_file_path = File.expand_path(cache_file_path || "~/.bitsa_cache.yml")
+      @lifespan_days = lifespan_days
+      @addresses = {}
+      @source_source_last_modified = nil
+      load_from_file_system
+    end
+
+    def stale?
+      (@source_last_modified.nil? ||
+       (DateTime.parse(@source_last_modified)+@lifespan_days) < DateTime.now)
+    end
+
+    # Remove all entries from cache.
+    def clear!
+      @addresses.clear
+      @source_last_modified = nil
+    end
+
+    def get(id)
+      @addresses[id]
+    end
+
+    def search(qry)
+      qry ||= ""
+      rg = Regexp.new(qry, Regexp::IGNORECASE)
+
+      # Flattens.each_slices to an array with [email1, name1, email2, name2] etc.
+      results = @addresses.values.flatten.each_slice(2).find_all do |e, n|
+        e.match(rg) || n.match(rg)
+      end
+
+      # Sort by case-insensitive email address
+      results.sort{|a,b| a[0].downcase <=> b[0].downcase}
+    end
+
+    def update(id, name, addresses)
+      @addresses[id] = addresses.map { | a | [a, name]}
+    end
+
+    def delete(id)
+      @addresses.delete(id)
+    end
+
+    def save
+      File.open(@cache_file_path, "w") do |f|
+        f.write(YAML::dump([@source_last_modified, @addresses]))
+      end
+    end
+
+    private
+
+    def load_from_file_system
+      if File.exist?(@cache_file_path)
+        @source_last_modified, @addresses = YAML::load_file(@cache_file_path)
+        unless @addresses
+          @addresses = {}
+          @source_last_modified = nil
+        end
+      end
+    end
+  end
+end