dash-mario 0.15

data/CHANGELOG

@@ -0,0 +1,93 @@
+2010-09-07 v0.15 Renamed to DashFu::Mario
+
+2010-09-07 v0.14 RubyGems and Github identities
+
+RubyGems releases now identify RubyGems as the source of the activity.
+
+Github source includes github login name as identity.
+
+2010-08-31 v0.13 Github data source merges related commits
+
+Now it does.
+
+2010-08-31 v0.12 Github data source merges related commits
+
+Github data source merges related commits (same committer/time) into single
+activity and shows first line of all commit messages.
+
+Changed to coding/testing with Ruby 1.9.2, since this is the target
+environment.
+
+2010-08-30 v0.11 Changes to activity person, AS 3.0 support
+
+Activity's person name is now fullname, photo is photo_url and url is no
+longer, but we do accept multiple identities of the form domain:id, e.g
+twitter.com:assaf, linkedin.com:assafarkin.
+
+Test suite now allows validating metric, activity and person. Call the validate
+method to run validation and raise exception on error (with a helpful error
+message). Call valid? if you're only interested in true/false.
+
+Gem dependencies removed to allow running with ActiveSupport 3.0.
+
+2010-08-26 v0.10 Tags and better messages
+
+Activities can now include tags.
+
+Improvement all around to all the HTML messages.
+
+2010-08-25 v0.9 Better Github commit message
+
+2010-08-24 v0.8 Minor API change
+
+Attribute :id is now :uid.
+
+Activity content can be set using either :html or :text attribute.
+2010-08-24 v0.7 Added test suite and resources
+
+Each source can have an associated resources file (YAML), e.g. ruby_gems.rb
+would have ruby_gems.yml. The default implementation of methods like name,
+description and display pull content from the resource. Resources can support
+multiple languages, but we're starting with just EN.
+
+Some sources also need API keys. These are accessed using the method api_key
+that returns the API key value for the current source (often a string, but can
+also be hash or array). There's an api_keys.yml file which contains fake API
+keys. You can put a real key in there while generating a cassette for your test
+case.
+
+Test suite is here, using WebMock and VCR to rest API calls. Cassettes go in
+test/cassettes, fixtures in test/fixtures.
+
+2010-08-19 v0.6 Added Backtweet
+
+2010-08-19 v0.5 Added Github and Github issues
+
+2010-08-18 v0.4 Metrics that set and increment
+
+Revised setup method to change special values metric.name and metric.columns
+(was name and column).
+
+There are two types of metrics, those that collect totals and those that
+collect daily/hourly values. The setup method indicates that by setting the
+value metric.total (defaults to false).
+
+Revised update method to allow either setting current value (:set) or
+incrementing current value (:inc).
+
+2010-08-11 v0.3 Always be sending changes
+
+Changed: Collector update methods accepts inc and timestamp arguments (but set
+is gone).
+
+Fixed: Rubygems source captures most recent downloads count as meta-data,
+updates collector with change since last update.
+
+Fixed: Rubygems source can handle whatever name you throw at it and properly
+escapes it.
+
+2010-08-10 v0.2 Working Rubygems source
+
+Fixed: Rubygems source not updating meta data like authors, project info, URL.
+
+2010-08-09 v0.1 First release

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org/"
+gemspec
+
+group :development do
+  gem "rake"
+  gem "yard"
+end
+
+group :test do
+  gem "awesome_print"
+  gem "nokogiri"
+  gem "shoulda"
+  gem "timecop"
+  gem "vcr"
+  gem "webmock"
+end

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 Assaf Arkin
+
+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.rdoc

@@ -0,0 +1,100 @@
+{Dash-fu}[http://dash-fu.com] sources need to get their data somehow: enter
+Marios. Marios are the brave workers that go out and collect data from vaious
+data sources and report them back in the form of activities and metrics.
+
+
+== Setup
+
+A Mario is setup in four steps. First, the display method returns an HTML form
+which will be displayed to the user. In fact, this method returns two values:
+
+* inputs -- HTML input controls for setting up a new controller.
+* notes -- Additional setup notes, e.g. other steps that need to be
+  followed, what values to supply, etc.
+
+Wrap input controls within the label and use the source[..param..] notation for
+the name attribute. For example, for Twitter:
+
+  <label>Screen name <input type="text" name="source[screen_name]" size="30"></label>
+
+When the form is filled, the setup method is called with a context and values
+from the form fields. Since the Mario needs to store state information, it uses
+the context for that. The context is a Hash that can store basic Ruby values
+(nil, String, boolean, Numeric, Array and Hash).
+
+Some sources collect metrics. These sources must set three specific values
+(during setup):
+
+* metric.name -- The name of the metric, e.g. Twitter source might use the
+  name "Twitter mentions of @dash_fu".
+* metric.columns -- Specifies the columns (at least one) that make up this
+  metric. The value if an array where each item describes a single column, see
+  below for more details.
+* metric.totals -- True if this metric collects totals (life-time values,
+  e.g. downloads, user accounts), false if it only collects daily values (e.g.
+  average response time, number of instances in cluster).
+
+For metric.columns, each item can use the following keys:
+
+* id -- Column identifier (if missing, derived from column name)
+* name -- Column name (required)
+
+Shortly after setup, the validate method is called with the same context.  If it
+raises any exception, the error is displayed to the user and the source is
+discarded. Otherwise, register is called with a Webhook URL.  Some Marios use
+that to register the Webhook with another service.
+
+
+== Updates
+
+Periodically, the Mario will be asked to update the source by calling the update
+method. This method is called with the same context and a block.  If data comes
+from a webhook, then the second argument to update is a Rack::Request object.
+
+The block passed to update can be used to update the source by yielding to it
+with a hash of named arguments. A single update may yield any number of times
+with any combination of arguments.
+
+The named arguments are:
+
+* set -- Columns to set (metric). Records the most recent value for this
+  metric. This is a hash where the keys are column ids (or indexes), the values
+  are integers or floats.
+* inc -- Columns to increment (metric). Records a change in value which may
+  be positive or negative. This is a hash where the keys are column ids (or
+  indexes), the values are integers or floats.
+* timestamp -- The Time (if missing, uses the current system time).
+* activity -- Activity to show in the stream. See below.
+
+Activity can specify the following attributes:
+
+* uid -- Unique identifier (within the scope of this source). For example,
+  if activity is a release, this could be the version number.
+* html -- HTML contents of the activity.
+* text -- Text contents of the activity (can be used instead of html).
+* url -- URL for original resource (e.g. blog post, tweet).
+* tags -- Any number of tags for filtering activities like this (e.g.
+  twitter, mention). Tags are lowercased and can contain alphanumeric, dashes
+  and underscore.
+* person -- Person who performed this activity. A hash with the (all
+  optional) values :name, :email, :url and :photo.
+* timestamp -- Timestamp activity occurred.
+
+HTML can contain links (HTTP/S and email), images, bold, italics, paragraphs,
+block quotes, lists, tables, pre-formatted text, video and a few other elements.
+Scripts, objects, styles are obviously not allowed. 
+
+Occasionally, the meta method is called. This method is used to display
+meta-data from the most recent state (i.e. last update). It returns an array of
+fields, each being a hash with the following values:
+
+* title -- Title for this field (not required)
+* text -- Text to show as value of the field
+* url -- Link (not required)
+
+
+== Teardown
+
+Eventually the source is destroyed and the Webhook is unregistered by
+calling unregister.
+

data/Rakefile

@@ -0,0 +1,34 @@
+require "rake/testtask"
+
+# -- Building stuff --
+
+spec = Gem::Specification.load(Dir["*.gemspec"].first)
+
+desc "Build the Gem"
+task :build do
+  sh "gem build #{spec.name}.gemspec"
+end
+
+desc "Install #{spec.name} locally"
+task :install=>:build do
+  sudo = "sudo" unless File.writable?( Gem::ConfigMap[:bindir])
+  sh "#{sudo} gem install #{spec.name}-#{spec.version}.gem"
+end
+
+desc "Push new release to gemcutter and git tag"
+task :push=>["test", "build"] do
+  sh "git push"
+  puts "Tagging version #{spec.version} .."
+  sh "git tag v#{spec.version}"
+  sh "git push --tag"
+  puts "Building and pushing gem .."
+  sh "gem push #{spec.name}-#{spec.version}.gem"
+end
+
+
+task :default=>:test
+Rake::TestTask.new do |task|
+  task.test_files = FileList['test/**/*_test.rb']
+  #task.warning = true
+  task.verbose = true
+end

data/dash-mario.gemspec

@@ -0,0 +1,22 @@
+Gem::Specification.new do |spec|
+  spec.name           = "dash-mario"
+  spec.version        = "0.15"
+  spec.author         = "Assaf Arkin"
+  spec.email          = "assaf@labnotes.org"
+  spec.homepage       = "http://dash-fu.com"
+  spec.summary        = "Hopping around collecting data, keeping your dashes dashing"
+
+  spec.files          = Dir["{bin,lib,test}/**/*", "CHANGELOG", "MIT-LICENSE", "README.rdoc", "Rakefile", "Gemfile", "*.gemspec"]
+
+  spec.has_rdoc         = true
+  spec.extra_rdoc_files = "README.rdoc", "CHANGELOG"
+  spec.rdoc_options     = "--title", "DashFu::Mario #{spec.version}", "--main", "README.rdoc",
+                          "--webcvs", "http://github.com/assaf/#{spec.name}"
+
+  spec.required_ruby_version = '>= 1.8.7'
+  spec.add_dependency "activesupport"
+  spec.add_dependency "json"
+  spec.add_dependency "nokogiri"
+  spec.add_dependency "rack"
+  spec.add_dependency "i18n"
+end

data/lib/dash-fu/mario.rb

@@ -0,0 +1,154 @@
+require "active_support"
+require "json"
+require "net/http"
+require "rack"
+require "uri"
+
+# See http://dash-fu.com
+module DashFu
+
+  # The README covers it all.
+  module Mario
+
+    class << self
+      attr_accessor :logger
+
+      # Returns all available marios.
+      def all
+        @marios ||= {}
+      end
+
+      # Returns Mario by its identifier.
+      def find(id)
+        all[id]
+      end
+
+      # Loads all the Marios from the given directory. The Mario identifier is
+      # derived from the filename (e.g. all/my_hero.rb becomes "my_hero"). The
+      # Mario class must map to the source identifier within the Mario module,
+      # e.g. DashFu::Mario::MyHero).
+      def load_marios(path = File.dirname(__FILE__) + "/marios")
+        Dir["#{path}/*.rb"].each do |file|
+          id = File.basename(file, ".rb")
+          fail "Mario #{id} already loaded" if all[id]
+          load file
+          klass = Mario.const_get(id.camelize)
+          all[id] = klass.new
+          logger.info "Loaded Mario #{id}: #{klass}"
+        end
+      end
+
+      # API keys (see instance method api_key).
+      attr_accessor :api_keys
+
+      def included(klass)
+        klass.extend ClassMethods
+      end
+    end
+
+
+    module ClassMethods
+      # Mario identifier.
+      def mario_id
+        @mario_id ||= name.demodulize.underscore
+      end
+    end
+
+
+    # Returns the display name for this Mario.
+    #
+    # Uses the resource 'name', and fallbacks on the class name (e.g
+    # Mario::OneUp becomes "One Up").
+    def name
+      resources["name"] || mario_id.titleize
+    end
+
+    # Returns additional information about this source.
+    #
+    # A good description helps the user identity source and decide whether or
+    # not to use it.
+    #
+    # Uses the resource 'description'.
+    def description
+      resources["description"]
+    end
+
+    # This method returns a hash with two values:
+    # * inputs -- HTML fragment for a setup form
+    # * notes -- HTML fragment for setup notes
+    #
+    # Uses the resources 'inputs' and 'notes'.
+    def display
+      { :inputs=>resources["inputs"], :notes=>resources["notes"] }
+    end
+
+    # Called to setup a new source with parameters from the HTML form (see
+    # #display). If there are any missing values, report them when #validate is
+    # called.
+    def setup(source, params)
+    end
+
+    # Called to validate the source. If there are any error, raise an
+    # exception. A good error message will help the user understand which value
+    # is missing or invalid and how to correct that.
+    def validate(source)
+    end
+
+    # Called to register a Webhook (for sources that need it)
+    def register(source, url)
+    end
+
+    # Called to update the source. This method will be called periodically with
+    # a source and a block. When triggered by a Webhook, it will be called with
+    # source, Rack::Request and a block. It can yield to the block any number of
+    # times with any combination of the supported named arguments for updating
+    # the source.
+    def update(source, request, &block)
+    end
+
+    # Called to unregister a Webhook (for sources that don't need it).
+    def unregister(source, url)
+    end
+
+    # Returns meta-data to be displayed alongside any other data. This method
+    # should return an array of hashes, each with the keys title (optional),
+    # text and url (optional). Good meta-data provides timely and relevant
+    # information that is not available in the raw data.
+    def meta(source)
+      []
+    end
+
+  protected
+
+    # Source identifier.
+    def mario_id
+      self.class.mario_id
+    end
+
+    # Logger. Dump messages that can help with troubleshooting.
+    def logger
+      DashFu::Mario.logger
+    end
+
+    # Returns I18n resources for this gem.
+    def resources
+      unless @resources
+        file_name = File.dirname(__FILE__) + "/marios/#{mario_id}.yml"
+        @resources = File.exist?(file_name) ? YAML.load_file(file_name)["en"] : {}
+      end
+      @resources
+    end
+
+    # Shortcut for Rack::Utils.escape_html
+    def escape_html(text)
+      Rack::Utils.escape_html(text.to_s)
+    end
+    alias :h :escape_html
+
+    # Returns API key for this source. May return string or hash, depending on
+    # the API.
+    def api_key
+      @api_key ||= DashFu::Mario.api_keys[mario_id] or raise "No API key for #{mario_id}"
+    end
+  end
+end