double_agent 0.2.3 → 1.0.0

data/CHANGELOG

@@ -1,3 +1,18 @@
+== Release 1.0.0 (November 11, 2012) ==
+
+* Changes to parser API
+* Add "mobile?" method to detect mobile OS's
+* Android's browser isn't part of the Chromium family
+* Android OS isn't part of the GNU/Linux family
+* iOS isn't part of the OS X family
+* Add iPhone and iPad
+* Add Kindle, Kindle Fire
+* Refactor the Logs module
+* Drop Stats module (use the "graphene" gem instead)
+* Drop Logs module
+* Drop icon methods - they just don't make much sense in the library
+* Drop support for Ruby 1.8
+
 == Release 0.2.3 (July 14, 2012) ==
 
 * Handle exceptions on encoding errors

data/README.rdoc

@@ -3,41 +3,50 @@
 double_agent is a library for parsing browser and operating system info out of user 
 agent strings. It is designed for parsing large sets for review or analysis.
 
-== Installation
+*NOTE* Support for Ruby 1.8 was dropped after version 0.2.3.
 
-    gem install double_agent
+== Installation
 
-== Loading
+    [sudo] gem install double_agent
+    # Or add "double_agent" to your Gemfile
 
-Double Agent is broken up into modules - Parser, Resources, Stats and Logs.
+Read the full documentation at http://jordanhollinger.com/docs/double_agent/
 
-    # Load the core modules (Parser, Resources)
-    require 'double_agent'
+== Parser
 
-    # Load modules individually
-    require 'double_agent/parser|resources|stats|logs|all'
+    user_agent = DoubleAgent.parse("Mozilla/5.0 (X11; Linux i686) AppleWebKit/535.19 (KHTML, like Gecko) Ubuntu/12.04 Chromium/18.0.1025.168 Chrome/18.0.1025.168 Safari/535.19")
 
-= Parser
+    user_agent.browser
+    => "Chrome 18"
 
-    ua_string = "I'm a user agent string for Chrome 11 on Ubuntu"
+    user_agent.browser_name
+    => "Chrome"
 
-    DoubleAgent.browser(ua_string)
-    => "Chrome 11"
+    user_agent.browser_version
+    => "18"
 
-    DoubleAgent.browser_family(ua_string)
+    user_agent.browser_family
     => "Chromium"
 
-    DoubleAgent.os(ua_string)
+    user_agent.os
     => "Ubuntu"
 
-    DoubleAgent.os_family(ua_string)
+    user_agent.os_family
     => "GNU/Linux"
 
-See the DoubleAgent module for more.
+    user_agent.mobile?
+    => false
+
+    # Or
 
-= Resources
+    DoubleAgent.browser("Mozilla/5.0 (X11; Linux i686) AppleWebKit/535.19 (KHTML, like Gecko) Ubuntu/12.04 Chromium/18.0.1025.168 Chrome/18.0.1025.168 Safari/535.19")
+    => "Chrome 18"
 
-DoubleAgent::Resource is a mix-in for objects with a user_agent method or attribute.
+See the DoubleAgent module for more info.
+
+== Resources
+
+DoubleAgent::Resource is a mix-in for objects with a user_agent method.
 It gives that class's objects all of the above methods and more.
 
     class Login
@@ -56,36 +65,13 @@ It gives that class's objects all of the above methods and more.
     login.os_family
     => "OS X"
 
-= Stats
-
-Calculate browser and OS shares for large sets of DoubleAgent::Resource objects with DoubleAgent::Stats::percentages_for.
-
-    logins = Login.all
-    p logins.size
-    => 1000
-
-    stats = DoubleAgent::Stats.percentages_for(logins, :browser_family, :os_family)
-    p stats
-    => [["Firefox", "Windows", 50.0, 500], ["Internet Explorer", "Windows", 20.0, 200], ["Safari", "OS X", 20.0, 200], ["Firefox", "GNU/Linux", 10.0, 100]]
-
-    stats.each do |browser_family, os_family, percent, real_num|
-      puts "#{browser_family} on #{os_family} - #{percent}% (#{real_num} hits)"
-    end
-    => "Firefox on Windows - 50% (500 hits)"
-    => "Internet Explorer on Windows - 20% (200 hits)"
-    => "Safari on OS X - 20% (200 hits)"
-    => "Firefox on GNU/Linux - 10% (100 hits)"
-
-= Logs
+See the DoubleAgent::Resource module for more info.
 
-DoubleAgent::Logs::entries parses through Apache and Nginx access logs, instantiating each log line into a DoubleAgent::Logs::Entry
-object. It even reads gzipped logs (requires zlib)! Since the DoubleAgent::Logs::Entry class mixes in DoubleAgent::Resource, you
-can easily calculate browser and/or OS share on your site.
+== Where did stats and logs go?
 
-    entries = DoubleAgent::Logs.entries("/var/log/nginx/my-site.access.log*")
-    stats = DoubleAgent::Stats.percentages_for(entries, :browser)
+As of version 1.0.0, double_agent underwent a downsizing. Stats were dropped and moved to their own more generic gem called Graphene. More info at https://github.com/jhollinger/graphene. Logs were also dropped; there are several HTTP log parsers for Ruby, including http-log-parser and Beaver.
 
-    p stats
-    => [["Firefox 4", 20.0, 650], ["Internet Explorer 8", 18.0, 587], ...]
+== License
+Copyright 2011 Jordan Hollinger
 
-Check out the DoubleAgent::Logs::Entry class for more methods besides user_agent.
+Licensed under the Apache License

data/data/browsers.yml

@@ -1,65 +1,69 @@
 # The ordering is very important; matches are performed in the specified order.
 # This allows for greatly simplified regexes.
 
-- :name: Internet Explorer %s
-  :sym: :msie
+:msie:
+  :name: Internet Explorer
   :regex: msie \d+
   :version: (?<=msie )[0-9]+
-  :safe_version: ["msie [0-9]+", "[0-9]+"]
 
-- :name: Chrome %s
-  :sym: :chrome
+:epiphany:
+  :name: Epiphany
+  :regex: epiphany
+  :version: (?<=epiphany/)[0-9]+
+
+:chrome:
+  :name: Chrome
   :family_sym: :chromium
   :regex: chrome/\d+
   :version: (?<=chrome/)[0-9]+
-  :safe_version: ["chrome/[0-9]+", "[0-9]+"]
 
-- :name: Chromium %s
-  :sym: :chromium
+:chromium:
+  :name: Chromium
   :regex: chromium/\d+
   :version: (?<=chromium/)[0-9]+
-  :safe_version: ["chromium/[0-9]+", "[0-9]+"]
 
-- :name: Opera %s
-  :sym: :opera
+:opera:
+  :name: Opera
   :regex: opera
   :version: ((?<=version/)[0-9]+)|((?<=opera )[0-9]+)
-  :safe_version: ["(version/[0-9]+)|(opera [0-9]+)", "[0-9]+"]
 
-- :name: Firefox %s
-  :sym: :firefox
+:firefox:
+  :name: Firefox
   :regex: firefox
   :version: (?<=firefox/)[0-9]+
-  :safe_version: ["firefox/[0-9]+", "[0-9]+"]
 
-- :name: Android %s
-  :sym: :android
-  :family_sym: :chromium
+:kindle_fire_silk:
+  :name: Kindle Fire (Silk)
+  :family_sym: :kindle
+  :regex: silk-accelerated
+
+:kindle_fire:
+  :name: Kindle Fire
+  :family_sym: :kindle
+  :regex: kindle fire
+
+:kindle:
+  :name: Kindle
+  :regex: kindle
+
+:android:
+  :name: Android
   :regex: android
   :version: (?<=android )[0-9]+(\.[0-9]+)?
-  :safe_version: ["android [0-9]+(\\.[0-9]+)?", "[0-9]+(\\.[0-9]+)?"]
 
-- :name: BlackBerry
-  :sym: :blackberry
+:blackberry:
+  :name: BlackBerry
   :regex: blackberry
 
-- :name: Epiphany
-  :sym: :epiphany
-  :regex: epiphany
-  :version: (?<=epiphany/)[0-9]+
-  :safe_version: ["epiphany/[0-9]+", "[0-9]+"]
-
-- :name: Safari %s
-  :sym: :safari
+:safari:
+  :name: Safari
   :regex: safari
   :version: (?<=version/)[0-9]+
-  :safe_version: ["version/[0-9]+", "[0-9]+"]
 
-- :name: Konqueror
-  :sym: :konqueror
+:konqueror:
+  :name: Konqueror
   :regex: konqueror
 
-- :name: Unknown
-  :sym: :unknown
+:unknown:
+  :name: Unknown
   :regex: .*
-  :version: .*

data/data/oses.yml

@@ -1,72 +1,98 @@
-- :name: Windows 8
-  :sym: :windows_8
+:windows_8:
+  :name: Windows 8
   :family_sym: :windows
   :regex: windows nt 6\.2
-  :icon: windows
 
-- :name: Windows 7
-  :sym: :windows_7
+:windows_7:
+  :name: Windows 7
   :family_sym: :windows
   :regex: windows nt 6\.1
-  :icon: windows
 
-- :name: Windows Vista
-  :sym: :windows_vista
+:windows_vista:
+  :name: Windows Vista
   :family_sym: :windows
   :regex: windows nt 6\.0
-  :icon: windows
 
-- :name: Windows XP
-  :sym: :windows_xp
+:windows_xp:
+  :name: Windows XP
   :family_sym: :windows
   :regex: windows nt 5\.[12]
-  :icon: windows
 
-- :name: Windows
-  :sym: :windows
+:windows:
+  :name: Windows
   :regex: windows
 
-- :name: iOS
-  :sym: :ios
-  :family_sym: :osx
-  :regex: (iphone)|(ipad)
+:kindle_fire:
+  :name: Kindle Fire
+  :family_sym: :kindle
+  :regex: (kindle fire)|(silk-accelerated)
+  :mobile: true
 
-- :name: OS X
-  :sym: :osx
+:kindle:
+  :name: Kindle
+  :regex: kindle
+  :mobile: true
+
+:ipod:
+  :name: iPod
+  :family_sym: :ios
+  :regex: \(ipod;
+  :mobile: true
+
+:iphone:
+  :name: iPhone
+  :family_sym: :ios
+  :regex: \(iphone;
+  :mobile: true
+
+:ipad:
+  :name: iPad
+  :family_sym: :ios
+  :regex: \(ipad;
+  :mobile: true
+
+:ios:
+  :name: iOS
+  :regex: \(i\w+; .* like mac os x;
+  :mobile: true
+
+:osx:
+  :name: OS X
   :regex: macintosh
 
-- :name: Android
-  :sym: :android
-  :family_sym: :linux
+:android:
+  :name: Android
   :regex: android
+  :mobile: true
 
-- :name: Ubuntu
-  :sym: :ubuntu
+:ubuntu:
+  :name: Ubuntu
   :family_sym: :linux
   :regex: ubuntu
 
-- :name: Fedora
-  :sym: :fedora
+:fedora:
+  :name: Fedora
   :family_sym: :linux
   :regex: fedora
 
-- :name: Slackware
-  :sym: :slackware
+:slackware:
+  :name: Slackware
   :family_sym: :linux
   :regex: slackware
 
-- :name: GNU/Linux
-  :sym: :linux
+:linux:
+  :name: GNU/Linux
   :regex: linux
 
-- :name: FreeBSD
-  :sym: :freebsd
+:freebsd:
+  :name: FreeBSD
   :regex: freebsd
 
-- :name: BlackBerry
-  :sym: :blackberry
+:blackberry:
+  :name: BlackBerry
   :regex: blackberry
+  :mobile: true
 
-- :name: Unknown
-  :sym: :unknown
+:unknown:
+  :name: Unknown
   :regex: .*

data/lib/double_agent/double_agent.rb

@@ -0,0 +1,60 @@
+# A browser user agent string parser. Use DoubleAgent.parse(user_agent) to return a DoubleAgent::UserAgent object, which you can 
+# query with methods like "browser_name" or "os". The DoubleAgent module itself responds to those same method - just
+# pass the user agent string as an argument.
+module DoubleAgent
+  # A hash of browser data, the basis for browser parsing. You may edit this data and call load_browsers! to customize parsing.
+  BROWSER_DATA = Psych.load_file(File.expand_path('../../../data/browsers.yml', __FILE__))
+
+  # A hash of OS hashes, the basis for OS parsing. You may edit this data and call load_oses! to customize parsing.
+  OS_DATA = Psych.load_file(File.expand_path('../../../data/oses.yml', __FILE__))
+
+  BROWSER_PARSERS, OS_PARSERS = {}, {} # :nodoc:
+
+  # Returns a new UserAgent object
+  def self.parse(user_agent_string)
+    UserAgent.new(user_agent_string)
+  end
+
+  # Forwards calls to a UserAgent object
+  def self.method_missing(method, *args, &block)
+    parse(args.first).send(method)
+  end
+
+  # Transforms BROWSER_DATA into a case statement inside of the _browser_sym method
+  def self.load_browsers!
+    BROWSER_PARSERS.clear.merge! Hash[BROWSER_DATA.map { |sym, data| [sym, BrowserParser.new(sym, data)] }]
+
+    module_eval <<-CODEZ
+      def self._browser_sym(user_agent)
+        case user_agent.to_s
+          #{BROWSER_DATA.map { |sym, data| "when %r{#{data[:regex]}}i then :\"#{sym}\"" }.join("\n")}
+        end
+      end
+    CODEZ
+  end
+
+  # Transforms OS_DATA into a case statement inside of the _os_sym method
+  def self.load_oses!
+    OS_PARSERS.clear.merge! Hash[OS_DATA.map { |sym, data| [sym, OSParser.new(sym, data)] }]
+
+    module_eval <<-CODEZ
+      def self._os_sym(user_agent)
+        case user_agent.to_s
+          #{OS_DATA.map { |sym, data| "when %r{#{data[:regex]}}i then :\"#{sym}\"" }.join("\n")}
+        end
+      end
+    CODEZ
+  end
+
+  private
+
+  # Returns the correct BrowerParser for the given user agent or symbol
+  def self.browser_parser(ua_or_sym)
+    BROWSER_PARSERS[ua_or_sym.is_a?(Symbol) ? ua_or_sym : _browser_sym(ua_or_sym)]
+  end
+
+  # Returns the correct OSParser for the given user agent or symbol
+  def self.os_parser(ua_or_sym)
+    OS_PARSERS[ua_or_sym.is_a?(Symbol) ? ua_or_sym : _os_sym(ua_or_sym)]
+  end
+end

data/lib/double_agent/parser.rb

@@ -1,192 +1,72 @@
-begin
-  require 'psych'
-rescue LoadError
-end
-require 'yaml'
-
 module DoubleAgent
-  # An array of "browser knowledge hashes," the basis of browser parsing. You may edit this data and call load_browsers! to customize parsing.
-  BROWSER_DATA = YAML.load_file(File.expand_path('../../../data/browsers.yml', __FILE__))
-
-  # An array of "OS knowledge hashes," the basis of OS parsing. You may edit this data and call load_oses! to customize parsing.
-  OS_DATA = YAML.load_file(File.expand_path('../../../data/oses.yml', __FILE__))
-
-  # An array of BrowserParser objects created from the data in BROWSER_DATA.
-  BROWSERS = {}
-
-  # An array of OSParser objects created from the data in OS_DATA.
-  OSES = {}
-
   # Each browser in BROWSER_DATA gets its own BrowserParser object. These 
   # parser objects are then used to parse specific data out of a user agent string.
-
   class BrowserParser
-    BLANK = ''
-    MIN_VERSION = '1.9.2'
-    attr_reader :sym, :family_sym, :icon
+    # The browser name
+    attr_reader :name
+    # The browser name as a symbol
+    attr_reader :sym
+    # The browser family name as a symbol
+    attr_reader :family_sym
 
     # Instantiate a new BrowserParser using a "browser family" element from BROWSER_DATA
-    def initialize(attrs={})
-      @sym = attrs[:sym]
+    def initialize(sym, attrs={})
+      @sym = sym
       @family_sym = attrs[:family_sym] || @sym
       @name = attrs[:name]
-      @icon = attrs[:icon] || @sym
-      if RUBY_VERSION < MIN_VERSION and attrs[:safe_version]
-        @safe_version = attrs[:safe_version].map { |r| Regexp.new r, Regexp::IGNORECASE }
-      elsif attrs[:version]
-        @version = Regexp.new(attrs[:version], Regexp::IGNORECASE)
+      if attrs[:version]
+        @version_pattern = Regexp.new(attrs[:version], Regexp::IGNORECASE)
       end
     end
 
     # Returns the browser's name. If you provide a user agent string as an argument,
     # it will attempt to also return the major version number. E.g. "Firefox 4".
     def browser(ua=nil)
-      if ua and (@version or @safe_version)
-        @name % version(ua)
-      else
-        (@name % BLANK).rstrip
-      end
+      (ua and @version_pattern) ? "#{name} #{version(ua)}" : name
+    end
+
+    # Attempts to parse and return the browser's version from a user agent string. Returns
+    # nil if nothing is found.
+    def version(ua)
+      ua.slice(@version_pattern)
     end
 
     # Returns the BrowserParser for this BrowserParser object's Family. E.g. the Chrome 
     # BrowserParser would return the Chromium BrowserParser. For browsers that are their 
     # own family (e.g. Firefox, IE) it will end up returning itself.
     def family
-      BROWSERS[@family_sym]
-    end
-    
-    private
-
-    # Attempts to parse and return the browser's version from a user agent string. Returns
-    # nil if nothing is found.
-    def version(ua)
-      if @safe_version
-        ua.slice(@safe_version[0]).slice(@safe_version[1]) rescue nil
-      else
-        ua.slice(@version)
-      end
+      BROWSER_PARSERS[family_sym]
     end
   end
 
-  # Each OS in OS_DATA gets its own OSParser object. In theory, these parser
-  # objects can then be used to grab further info from user agent strings, though
-  # that is not currently happening.
-
+  # Each OS in OS_DATA gets its own BrowserParser object. These 
+  # parser objects are then used to parse specific data out of a user agent string.
   class OSParser
-    attr_reader :os, :sym, :family_sym, :icon
+    # The operating system name
+    attr_reader :os
+    # The operating system name as a symbol
+    attr_reader :sym
+    # The operating system family name as a symbol
+    attr_reader :family_sym
 
     # Instantiate a new OSParser using an "OS family" element from OS_DATA
-    def initialize(attrs={})
-      @sym = attrs[:sym]
+    def initialize(sym, attrs={})
+      @sym = sym
       @family_sym = attrs[:family_sym] || @sym
       @os = attrs[:name]
-      @icon = attrs[:icon] || @sym
+      @mobile = attrs[:mobile] || false
+    end
+
+    # Returs true if this is mobile OS, false if not
+    def mobile?
+      @mobile
     end
 
     # Returns the OSParser for this OSParser object's Family. E.g. the Ubuntu
     # OSParser would return the GNU/Linux OSerParser. For OSes that are their own
     # family (e.g. OS X) it will end up returning itself.
     def family
-      OSES[@family_sym]
-    end
-  end
-
-  # Returns the browser's name, possibly including the version number, e.g. "Chrome 12"
-  def self.browser(ua)
-    browser_parser(ua).browser(ua)
-  end
-
-  # Returns the browser's symbol name, e.g. :chrome
-  def self.browser_sym(user_agent)
-    # This method is overwitten by load_browsers!
-  end
-
-  # Returns the browser's icon name, e.g. :chrome
-  def self.browser_icon(ua)
-    browser_parser(ua).icon
-  end
-
-  # Returns the browser's family name, e.g. "Chromium"
-  def self.browser_family(ua)
-    browser_parser(ua).family.browser
-  end
-
-  # Returns the browser's family's symbol name, e.g. :chromium
-  def self.browser_family_sym(ua)
-    browser_parser(ua).family_sym
-  end
-
-  # Returns the browser's family's icon name, e.g. :chromium
-  def self.browser_family_icon(ua)
-    browser_parser(ua).family.icon
-  end
-
-  # Returns the OS's name, e.g. "Ubuntu"
-  def self.os(ua)
-    os_parser(ua).os
-  end
-
-  # Returns the OS's symbol name, e.g. :ubuntu
-  def self.os_sym(user_agent)
-    # This method is overwitten by load_oses!
-  end
-
-  # Returns the OS's icon name, e.g. :ubuntu
-  def self.os_icon(ua)
-    os_parser(ua).icon
-  end
-
-  # Returns the OS's family, e.g. "GNU/Linux"
-  def self.os_family(ua)
-    os_parser(ua).family.os
-  end
-
-  # Returns the OS's family's symbol name, e.g. :linux
-  def self.os_family_sym(ua)
-    os_parser(ua).family_sym
-  end
-
-  # Returns the OS's family's symbol icon, e.g. :linux
-  def self.os_family_icon(ua)
-    os_parser(ua).family.icon
-  end
-
-  # Returns the correct BrowerParser for the given user agent or symbol
-  def self.browser_parser(ua_or_sym)
-    BROWSERS[ua_or_sym.is_a?(Symbol) ? ua_or_sym : browser_sym(ua_or_sym)]
-  end
-
-  # Returns the correct OSParser for the given user agent or symbol
-  def self.os_parser(ua_or_sym)
-    OSES[ua_or_sym.is_a?(Symbol) ? ua_or_sym : os_sym(ua_or_sym)]
-  end
-
-  # Parses BROWSER_DATA into BROWSERS, a hash of BrowserParser objects indexed by their symbol names.
-  # Parses and evals BROWSER_DATA into a case statement inside of the browser_sym method.
-  def self.load_browsers!
-    BROWSERS.clear
-    str = "case user_agent.to_s\n"
-    BROWSER_DATA.each do |data|
-      BROWSERS[data[:sym]] = BrowserParser.new(data)
-      str << "  when %r{#{data[:regex]}}i then :#{data[:sym]}\n"
+      OS_PARSERS[family_sym]
     end
-    str << 'end'
-    module_eval "def self.browser_sym(user_agent); #{str}; end"
-  end
-
-  # Parses OS_DATA into OSES, a hash of OSParser objects indexed by their symbol names.
-  # Parses and evals OS_DATA into a case statement inside of the os_sym method.
-  def self.load_oses!
-    OSES.clear
-    str = "case user_agent.to_s\n"
-    OS_DATA.each do |data|
-      OSES[data[:sym]] = OSParser.new(data)
-      str << "  when %r{#{data[:regex]}}i then :#{data[:sym]}\n"
-    end
-    str << 'end'
-    module_eval "def self.os_sym(user_agent); #{str}; end"
   end
 end
-
-DoubleAgent.load_browsers!
-DoubleAgent.load_oses!