birdwatcher 0.1.0

data/lib/birdwatcher/commands/workspace.rb

@@ -0,0 +1,176 @@
+module Birdwatcher
+  module Commands
+    class Workspace < Birdwatcher::Command
+      self.meta = {
+        :description => "Manage workspaces",
+        :names       => %w(workspace workspaces),
+        :usage       => "workspace [ACTION]"
+      }
+
+      def self.detailed_usage
+<<-USAGE
+Workspaces enable you to segment and manage users and data stored in the database.
+You can use workspaces to create logical separation between different users.
+For example, you may want to create a workspace for a company, a department or
+for a specific topic.
+
+There will always be a default workspace with the name #{Birdwatcher::Models::Workspace::DEFAULT_WORKSPACE_NAME.bold} which might be enough
+if you plan to use Birdwatcher for a small group of Twitter users.
+
+#{'USAGE:'.bold}
+
+#{'List available workspaces:'.bold}
+  workspace list
+
+#{'Create a new workspace:'.bold}
+  workspace create NAME [DESCRIPTION]
+
+#{'Switch to a workspace:'.bold}
+  workspace use NAME
+
+#{'Delete a workspace:'.bold}
+  workspace delete NAME
+
+#{'Rename a workspace'.bold}
+  workspace rename NAME NEW_NAME
+USAGE
+      end
+
+      def run
+        if !arguments?
+          info("Current workspace: #{current_workspace.name.bold} (database ID: #{current_workspace.id.to_s.bold})")
+          return true
+        end
+        action = arguments.first.downcase
+        case action
+        when "list"
+          list_workspaces
+        when "create", "add", "-a"
+          create_workspace
+        when "rename", "-r"
+          rename_workspace
+        when "select", "use"
+          select_workspace
+        when "delete", "destroy", "rm", "-d"
+          delete_workspace
+        else
+          select_workspace(arguments.first)
+        end
+      end
+
+      def list_workspaces
+        longest_workspace_name = Birdwatcher::Models::Workspace.all.map(&:name).max_by(&:length)
+        info("Available workspaces:\n")
+        Birdwatcher::Models::Workspace.order(:name).each do |workspace|
+          if current_workspace.id == workspace.id
+            workspace_name = "*".bold.light_green + "  #{workspace.name}"
+          else
+            workspace_name = "   #{workspace.name}"
+          end
+
+          output_formatted(" %-#{longest_workspace_name.bold.length}s  \t\t%s\n", workspace_name.bold, workspace.description)
+        end
+        newline
+      end
+
+      def select_workspace(name = nil)
+        name ||= arguments[1]
+
+        if !name
+          error("You must provide a workspace name")
+          return false
+        end
+
+        if workspace = Birdwatcher::Models::Workspace.first(:name => name)
+          self.current_workspace = workspace
+          info("Now using workspace: #{workspace.name.bold}")
+        else
+          error("There is no workspace with that name")
+        end
+      end
+
+      def create_workspace
+        name        = arguments[1]
+        description = arguments[2..-1].to_a.join(" ")
+        description = nil unless description
+
+        if !name
+          error("You must provide a workspace name")
+          return false
+        end
+
+        if Birdwatcher::Models::Workspace.first(:name => name)
+          error("There is already a workspace with that name")
+          return false
+        end
+
+        workspace = Birdwatcher::Models::Workspace.create(
+          :name        => name,
+          :description => description
+        )
+
+        info("Created workspace: #{workspace.name.bold}")
+        self.current_workspace = workspace
+      end
+
+      def rename_workspace
+        old_name = arguments[1]
+        new_name = arguments[2]
+
+        if !old_name || !new_name
+          error("You must provide workspace name and new name")
+          return false
+        end
+
+        if old_name == Birdwatcher::Models::Workspace::DEFAULT_WORKSPACE_NAME
+          error("Default workspace cannot be renamed")
+          return false
+        end
+
+        if !old_workspace = Birdwatcher::Models::Workspace.first(:name => old_name)
+          error("There is no workspace named #{old_name.bold}")
+          return false
+        end
+
+        if Birdwatcher::Models::Workspace.first(:name => new_name)
+          error("There is already a workspace named #{new_name.bold}")
+          return false
+        end
+
+        old_workspace.update(:name => new_name)
+        if old_workspace.id == current_workspace.id
+          self.current_workspace = old_workspace
+        end
+
+        info("Workspace #{old_name.bold} renamed to #{new_name.bold}")
+      end
+
+      def delete_workspace
+        name = arguments[1]
+
+        if !name
+          error("You must provide a workspace name")
+          return false
+        end
+
+        if workspace = Birdwatcher::Models::Workspace.first(:name => name)
+          return unless confirm("Are you sure you want to delete #{name.bold} and all associated data?")
+          workspace.destroy
+          info("Deleted workspace: #{workspace.name.bold}")
+          if workspace.default_workspace?
+            self.current_workspace = Birdwatcher::Models::Workspace.create_default_workspace!
+            return
+          end
+          if current_workspace.id == workspace.id
+            self.current_workspace = Birdwatcher::Models::Workspace.first(
+              :name => Birdwatcher::Models::Workspace::DEFAULT_WORKSPACE_NAME
+            )
+          end
+        else
+          error("There is no workspace with that name")
+          return false
+        end
+      end
+    end
+  end
+end

data/lib/birdwatcher/concerns/concurrency.rb

@@ -0,0 +1,25 @@
+module Birdwatcher
+  module Concerns
+    module Concurrency
+      # The default size of thread pool
+      # @private
+      DEFAULT_THREAD_POOL_SIZE = 10.freeze
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+      end
+
+      # Create a new thread pool
+      #
+      # @param size [Integer] OPTIONAL: The size of the thread pool (default size if not specified)
+      # @return [Thread::Pool]
+      # @see https://github.com/meh/ruby-thread#pool
+      def thread_pool(size = nil)
+        Thread.pool(size || DEFAULT_THREAD_POOL_SIZE)
+      end
+    end
+  end
+end

data/lib/birdwatcher/concerns/core.rb

@@ -0,0 +1,105 @@
+module Birdwatcher
+  module Concerns
+    module Core
+
+      # Location of the data directory
+      # @private
+      DATA_DIRECTORY = File.expand_path(
+        File.join(File.dirname(__FILE__), "..", "..", "..", "data")
+      ).freeze
+
+      class DataFileNotFoundError < StandardError; end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+      end
+
+      # Get the current Console instance
+      #
+      # @return [Birdwatcher::Console]
+      def console
+        Birdwatcher::Console.instance
+      end
+
+      # Get the currently active workspace model object
+      #
+      # The current workspace is represented by its Sequel data model and can be
+      # used to query for data associated with the workspace.
+      #
+      # Please read the Sequel gem documentation for more information about how
+      # to use the model.
+      #
+      # @return [Birdwatcher::Models::Workspace] instance of the currently active workspace
+      # @see http://sequel.jeremyevans.net/documentation.html
+      def current_workspace
+        Birdwatcher::Console.instance.current_workspace
+      end
+
+      # Set the current workspace
+      #
+      # @param workspace [Birdwatcher::Models::Workspace]
+      def current_workspace=(workspace)
+        Birdwatcher::Console.instance.current_workspace = workspace
+      end
+
+      # Get a Twitter API client
+      #
+      # The Twitter API is being queried with the Twitter gem which provides an
+      # easy and intuitive interface to the API and its data objects. Please see
+      # the Twitter gem documentation for information on how to use the Twitter
+      # gem.
+      #
+      # The method will return an instance configured with a random Twitter API
+      # keypair from the +~/.birdwatcherrc+ configuration file.
+      #
+      # @return instance of Twitter::REST::Client
+      # @see https://github.com/sferik/twitter
+      # @see http://www.rubydoc.info/gems/twitter
+      def twitter_client
+        Birdwatcher::Console.instance.twitter_client
+      end
+
+      # Get a Klout API client
+      #
+      # The Klout API provides information about Twitter users such as their
+      # general "social score", topics of interest and social influence graph.
+      #
+      # The method will return an instance configured with a random API key from
+      # the +~/.birdwatcherrc+ configuration file.
+      #
+      # @return [Birdwatcher::KloutClient]
+      # @see https://klout.com/s/developers/v2
+      def klout_client
+        Birdwatcher::Console.instance.klout_client
+      end
+
+      # Get the raw database client instance
+      #
+      # The raw database client object can be used to execute raw SQL queries
+      # against the configured database, however the {current_workspace} method
+      # should be used whenever possible to execute SQL queries through the
+      # current workspace's {Sequel::Model} instance instead. This ensures that
+      # the data returned is isolated to the current workspace.
+      #
+      # @return [Sequel::Database]
+      def database
+        Birdwatcher::Console.instance.database
+      end
+
+      # Get the contents of a data file
+      #
+      # @param name [String] file name to read
+      #
+      # @return contents of file in Birdwatcher's data directory
+      # @raise [Birdwatcher::Concerns::Core::DataFileNotFoundError] if the file doesn't exist
+      def read_data_file(name)
+        path = File.join(DATA_DIRECTORY, name)
+        fail(DataFileNotFoundError, "File #{name} was not found in data directory") unless File.exists?(path)
+        File.read(path)
+      end
+    end
+  end
+end

data/lib/birdwatcher/concerns/outputting.rb

@@ -0,0 +1,114 @@
+module Birdwatcher
+  module Concerns
+    module Outputting
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+      end
+
+      # Output data to the console
+      #
+      # Simply outputs the given data to the console.
+      #
+      # For more convenient and consistant outputting, see the {info}, {task},
+      # {error}, {warn} and {fatal} methods.
+      def output(data)
+        Birdwatcher::Console.instance.output(data)
+      end
+
+      # Output formatted data to the console
+      #
+      # Outputs data with +printf+ formatting.
+      #
+      # @example
+      #    output_formatted("%-15s %s\n", title, description)
+      #
+      # @param *args Args to be passed
+      def output_formatted(*args)
+        Birdwatcher::Console.instance.output_formatted(*args)
+      end
+
+      # Output a newline to the console
+      #
+      # Used for consistant spacing in console output
+      def newline
+        Birdwatcher::Console.instance.newline
+      end
+
+      # Output a line to the console
+      #
+      # Used for consistant spacing and separation between console output
+      def line_separator
+        Birdwatcher::Console.instance.line_separator
+      end
+
+      # Output an informational message to the console
+      #
+      # @param message [String] Message to display
+      #
+      # Formats the message as an informational message
+      def info(message)
+        Birdwatcher::Console.instance.info(message)
+      end
+
+      # Output an informational message to the console that reports when a
+      # longer-running task is done.
+      #
+      # @param message [String] Message to display
+      # @param fatal [Boolean] OPTIONAL if an exception is raised, treat it as a fatal error
+      # @param block The code block to yield
+      #
+      # @example performing a long-running task
+      #    task("Performing a long, time consuming task...") do
+      #      long_running_task
+      #    end
+      def task(message, fatal = false, &block)
+        Birdwatcher::Console.instance.task(message, fatal, &block)
+      end
+
+      # Output an error message to the console
+      #
+      # @param message [String] Message to display
+      #
+      # Formats the message as an error message
+      def error(message)
+        Birdwatcher::Console.instance.error(message)
+      end
+
+      # Output a warning message to the console
+      #
+      # @param message [String] Message to display
+      #
+      # Formats the message as a warning message
+      def warn(message)
+        Birdwatcher::Console.instance.warn(message)
+      end
+
+      # Output a fatal message to the console
+      #
+      # @param message [String] Message to display
+      #
+      # Formats the message as a fatal message
+      def fatal(message)
+        Birdwatcher::Console.instance.fatal(message)
+      end
+
+      # Ask the user for confirmation
+      #
+      # @param question [String] Yes/No question to ask the user
+      #
+      # Waits for the user to answer Yes or No to a question. Useful for making
+      # the user confirm destructive actions before executing them.
+      #
+      # @example make user confirm division by zero
+      #    if confirm("Do you really want divide by zero?")
+      #      0 / 0
+      #    end
+      def confirm(question)
+        HighLine.agree("#{question} (y/n) ")
+      end
+    end
+  end
+end

data/lib/birdwatcher/concerns/persistence.rb

@@ -0,0 +1,101 @@
+module Birdwatcher
+  module Concerns
+    module Persistence
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+      end
+
+      # Save a Twitter status to the database
+      #
+      # @param status [Twitter::Tweet]
+      # @param user   [Birdwatcher::Models::User] Author of status
+      #
+      # The status will be linked to the current workspace. All URLs, hashtags
+      # and mentions will automatically be extracted and saved as separate models.
+      #
+      # @return [Birdwatcher::Models::Status]
+      def save_status(status, user)
+        current_workspace = Birdwatcher::Console.instance.current_workspace
+        db_status = current_workspace.add_status(
+          :user_id            => user.id,
+          :twitter_id         => status.id.to_s,
+          :text               => Birdwatcher::Util.strip_control_characters(Birdwatcher::Util.unescape_html(status.text)),
+          :source             => Birdwatcher::Util.strip_control_characters(Birdwatcher::Util.strip_html(status.source)),
+          :retweet            => status.retweet?,
+          :geo                => status.geo?,
+          :favorite_count     => status.favorite_count,
+          :retweet_count      => status.retweet_count,
+          :possibly_sensitive => status.possibly_sensitive?,
+          :lang               => status.lang,
+          :posted_at          => status.created_at,
+        )
+        if status.geo? && status.geo.coordinates
+          db_status.longitude = status.geo.coordinates.first
+          db_status.latitude  = status.geo.coordinates.last
+        end
+        if status.place?
+          db_status.place_type         = status.place.place_type
+          db_status.place_name         = Birdwatcher::Util.strip_control_characters(status.place.name)
+          db_status.place_country_code = Birdwatcher::Util.strip_control_characters(status.place.country_code)
+          db_status.place_country      = Birdwatcher::Util.strip_control_characters(status.place.country)
+        end
+        db_status.save
+        if status.hashtags?
+          status.hashtags.each do |hashtag|
+            tag = Birdwatcher::Util.strip_control_characters(hashtag.text)
+            db_hashtag = current_workspace.hashtags_dataset.first(:tag => tag) || current_workspace.add_hashtag(:tag => tag)
+            db_status.add_hashtag(db_hashtag)
+          end
+        end
+        if status.user_mentions?
+          status.user_mentions.each do |mention|
+            screen_name = Birdwatcher::Util.strip_control_characters(mention.screen_name)
+            name        = Birdwatcher::Util.strip_control_characters(mention.name)
+            db_mention  = current_workspace.mentions_dataset.first(:twitter_id => mention.id.to_s) || current_workspace.add_mention(:twitter_id => mention.id.to_s, :screen_name => screen_name, :name => name)
+            db_status.add_mention(db_mention)
+          end
+        end
+        if status.urls?
+          status.urls.each do |url|
+            expanded_url = Birdwatcher::Util.strip_control_characters(url.expanded_url.to_s)
+            db_url = current_workspace.urls_dataset.first(:url => expanded_url) || current_workspace.add_url(:url => expanded_url)
+            db_status.add_url(db_url)
+          end
+        end
+        db_status
+      end
+
+      # Save a Twitter user to the database
+      #
+      # @param user [Twitter::User]
+      #
+      # The user will be linked to the current workspace
+      #
+      # @return [Birdwatcher::Models::User]
+      def save_user(user)
+        Birdwatcher::Console.instance.current_workspace.add_user(
+          :twitter_id        => user.id.to_s,
+          :screen_name       => Birdwatcher::Util.strip_control_characters(user.screen_name),
+          :name              => Birdwatcher::Util.strip_control_characters(user.name),
+          :location          => Birdwatcher::Util.strip_control_characters(user.location),
+          :description       => Birdwatcher::Util.strip_control_characters(user.description),
+          :url               => (user.website_urls.first ? Birdwatcher::Util.strip_control_characters(user.website_urls.first.expanded_url.to_s) : nil),
+          :profile_image_url => user.profile_image_url_https.to_s,
+          :followers_count   => user.followers_count,
+          :friends_count     => user.friends_count,
+          :listed_count      => user.listed_count,
+          :favorites_count   => user.favorites_count,
+          :statuses_count    => user.statuses_count,
+          :utc_offset        => user.utc_offset,
+          :timezone          => user.time_zone,
+          :geo_enabled       => user.geo_enabled?,
+          :verified          => user.verified?,
+          :lang              => user.lang
+        )
+      end
+    end
+  end
+end

data/lib/birdwatcher/concerns/presentation.rb

@@ -0,0 +1,122 @@
+module Birdwatcher
+  module Concerns
+    module Presentation
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+      end
+
+      # Make a user summary output
+      #
+      # @param user [Birdwatcher::Models::User]
+      #
+      # @return [String] Short summary of the user
+      def make_user_summary_output(user)
+        "#{user.name.bold.light_green} (@#{user.screen_name}) #{user.verified ? '*'.bold.light_blue : ''}\n" +
+        "Description:".bold + " #{user.description || 'No description'}\n" +
+        "Location:".bold + " #{user.location || 'Unknown'}\n" +
+        "Followers:".bold + " #{user.followers_count} | " +
+        "Following:".bold + " #{user.friends_count} | " +
+        "Listed:".bold + " #{user.listed_count} | " +
+        "Favorites:".bold + " #{user.favorites_count} | " +
+        "Statuses:".bold + " #{user.statuses_count}\n"
+      end
+
+      # Output a user summary to the console
+      #
+      # @param user [Birdwatcher::Models::User]
+      def output_user_summary(user)
+        make_user_summary_output(user)
+      end
+
+      # Make user details output
+      #
+      # @param user [Birdwatcher::Models::User]
+      #
+      # @return [String] summary and details about a user
+      def make_user_details_output(user)
+        "#{user.name.bold.light_green} (@#{user.screen_name}) #{user.verified ? '*'.bold.light_blue : ''}\n\n" +
+
+        "Description:".bold + " #{user.description || 'No description'}\n" +
+        "   Location:".bold + " #{user.location || 'Unknown'}\n" +
+        "    Website:".bold + " #{user.url || 'None'}\n" +
+        "   Timezone:".bold + " #{user.timezone}\n" +
+        "   Language:".bold + " #{user.lang}\n\n" +
+
+        "Followers:".bold + " #{user.followers_count}\n" +
+        "Following:".bold + " #{user.friends_count}\n" +
+        "Favorites:".bold + " #{user.favorites_count}\n" +
+        " Statuses:".bold + " #{user.statuses_count}\n\n" +
+
+        "  Added:".bold + " #{time_ago_in_words(user.created_at)}\n" +
+        "Updated:".bold + (user.updated_at ? " #{time_ago_in_words(user.updated_at)}" : " Never") + "\n"
+      end
+
+      # Output user details to the console
+      #
+      # @param user [Birdwatcher::Models::User]
+      def output_user_details(user)
+        output make_user_details_output(user)
+      end
+
+      # Make status summary output
+      #
+      # @param status [Birdwatcher::Models::Status]
+      #
+      # @return [String] short summary of status
+      def make_status_summary_output(status)
+        "#{status.user.name.bold.light_green} (@#{status.user.screen_name}) #{status.user.verified ? '*'.bold.light_blue : ''} #{status.posted_at.strftime('%b %e, %H:%M')}\n" +
+        "#{status.text.bold}\n" +
+        "#{'Favorites:'.light_blue} #{status.favorite_count} | " +
+        "#{'Retweets:'.light_blue} #{status.retweet_count}\n"
+      end
+
+      # Output status summary to the console
+      #
+      # @param status [Birdwatcher::Models::Status]
+      def output_status_summary(status)
+        output make_status_summary_output(status)
+      end
+
+      # Make URL summary output
+      #
+      # @param url [Hash]
+      # @return [String] URL summary
+      def make_url_summary_output(url)
+        out  = "#{(url[:final_url] || url[:url]).bold}\n" +
+               "#{'Shares:'.bold} #{url[:count]}\n"
+        out += "#{'Title:'.bold} #{url[:title] || 'Unknown'}\n"
+        if url[:http_status]
+          case url[:http_status]
+          when 200..299
+            status = url[:http_status].to_s.bold.light_green
+          when 400..499
+            status = url[:http_status].to_s.bold.light_yellow
+          when 500..599
+            status = url[:http_status].to_s.bold.light_red
+          else
+            status = url[:http_status].to_s.bold
+          end
+          out += "#{'Status Code:'.bold} #{status}\n"
+        else
+          out += "#{'Status Code:'.bold} Unknown\n"
+        end
+        out += "#{'Content Type:'.bold} #{url[:content_type] || 'Unknown'}\n"
+        out
+      end
+
+      # Page potentially long output to the console
+      #
+      # @param text [String] Text to page
+      #
+      # If the text is long, it will be automatically paged with the system's
+      # currently configured pager command (usually `less`).
+      def page_text(text)
+        ::TTY::Pager::SystemPager.new.page(text)
+      rescue Errno::EPIPE
+      end
+    end
+  end
+end