brauser 3.3.2 → 4.0.0

data/doc/top-level-namespace.html

@@ -103,9 +103,9 @@
 </div>
 
     <div id="footer">
-  Generated on Thu May 22 12:11:27 2014 by
+  Generated on Mon Sep 29 16:43:31 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.8.7.4 (ruby-2.1.2).
+  0.8.7.4 (ruby-2.1.3).
 </div>
 
   </body>

data/lib/brauser.rb

@@ -1,26 +1,24 @@
-# encoding: utf-8
 #
 # This file is part of the brauser gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
 # Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
 #
 
 require "lazier"
+require "versionomy"
 
-Lazier.load!(:object, :boolean)
+::I18n.enforce_available_locales = false
+Lazier.load!(:object, :boolean, :string)
 
 require "brauser/version" unless defined?(Brauser::Version)
-require "brauser/queryable/chainers"
-require "brauser/queryable/queries"
-require "brauser/query"
-require "brauser/definitions/browsers"
-require "brauser/definitions/languages"
-require "brauser/definitions/platforms"
-require "brauser/definition"
-require "brauser/browseable/attributes"
-require "brauser/browseable/general"
-require "brauser/browseable/parsing"
-require "brauser/browseable/partial_querying"
-require "brauser/browseable/querying"
-require "brauser/browseable/register"
+require "brauser/definitions/base"
+require "brauser/definitions/browser"
+require "brauser/definitions/language"
+require "brauser/definitions/platform"
+require "brauser/value"
+require "brauser/parser"
 require "brauser/browser"
 require "brauser/hooks"
+
+require __dir__ + "/../default_definitions/browsers"
+require __dir__ + "/../default_definitions/platforms"
+require __dir__ + "/../default_definitions/languages"

data/lib/brauser/browser.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 #
 # This file is part of the brauser gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
 # Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
@@ -12,95 +11,225 @@ module Brauser
   #   @return [String] The raw User-Agent HTTP header.
   # @attribute accept_language
   #   @return [String] The raw Accept-Language HTTP header.
-  # @attribute languages
-  #   @return [Array] The accepted languages.
-  # @attribute name
-  #   @return [String] The current browser name.
-  # @attribute version
-  #   @return [String] The current browser version.
-  # @attribute platform
-  #   @return [String] The current browser platform.
+  # @attribute [r] name
+  #   @return [Symbol] The current browser name.
+  # @attribute [r] human_name
+  #   @return [String] The human-readable current browser name.
+  # @attribute [r] version
+  #   @return [Versionomy::Value] The current browser version.
+  # @attribute [r] platform
+  #   @return [Symbol] The current browser platform.
+  # @attribute [r] human_platform
+  #   @return [String] The human-readable current browser platform.
+  # @attribute [r] languages
+  #   @return [Hash] The accepted languages.
+  # @attribute [r] human_languages
+  #   @return [Hash] The human-readable list of accepted languages.
   class Browser
-    attr_accessor :agent
-    attr_accessor :accept_language
-    attr_accessor :languages
-    attr_accessor :name
-    attr_accessor :version
-    attr_accessor :platform
-
-    # Aliases
+    attr_accessor :agent, :accept_language
+    attr_reader :name, :human_name, :version, :platform, :human_platform, :languages, :human_languages
     alias_attribute :ua, :agent
 
-    include ::Brauser::Browseable::General
-    include ::Brauser::Browseable::Attributes
-    include ::Brauser::Browseable::DefaultDefinitions
-    include ::Brauser::Browseable::Register
-    include ::Brauser::Browseable::Parsing
-    include ::Brauser::Browseable::PartialQuerying
-    include ::Brauser::Browseable::Querying
-
     # Creates a new browser.
     #
     # @param agent [String] The User-Agent HTTP header.
     # @param accept_language [String] The Accept-Language HTTP header.
     def initialize(agent = "", accept_language = "")
-      ::Brauser::Browser.add_default_browsers
-      ::Brauser::Browser.add_default_platforms
-      ::Brauser::Browser.add_default_languages
-
       @agent = agent
       @accept_language = accept_language
-
-      @languages = parse_accept_language(@accept_language) if @accept_language
-      parse_agent(@agent) if @agent
-    end
-
-    # Get the current browser version (if called without arguments) or checks if the browser is a specific version.
-    #
-    # @see #is_version
-    # @param versions [String|Hash] A string in the form `operator version && ...` (example: `>= 7 && < 4`) or an hash with specific version to match against,
-    #   in form `{:operator => version}`, where operator is one of `:lt, :lte, :eq, :gt, :gte`.
-    # @return [String|Query] The browser version or a query which can evaluated for concatenation or result.
-    def version(versions = nil)
-      !versions ? @version : version_equals_to(versions)
+      parse
     end
 
-    # This method enables the use of dynamic queries in just one method.
+    # Returns an array of information about the browser. Information are strings which are suitable to use as CSS classes.
     #
-    # For example:
+    # For version, it will be included a class for every token of the version. For example, version `7.0.1.2` will return this:
     #
     # ```ruby
-    # browser.is_msie_v_gt_4_1_on_windows?
-    # #=> true
+    # ["version-7", "version-7_0", "version-7_0_1", "version-7_0_1_2"]
     # ```
     #
-    # If you don't provide a trailing `?`, you will get a Brauser::Query.
+    # If you provide a block (with accepts name, version and platform as arguments), it will be used for translating the name.
     #
-    # If the syntax is invalid, a `NoMethodError` exception will be raised.
+    # @param join [String|NilClass] If non falsy, the separator to use to join information. If falsy, informations will be returned as array.
+    # @param name [Boolean] If non falsy, the string to prepend to the name. If falsy, the name information will not be included.
+    # @param version [String|NilClass] If non falsy, the string to prepend to the version. If falsy, the version information will not be included.
+    # @param platform [String|NilClass] If non falsy, the string to prepend to the platform. If falsy, the platform information will not be included.
+    # @return [String|Array] CSS ready information of the current browser.
+    def classes(join = " ", name: true, version: true, platform: true)
+      rv = [name_to_str(name), version_to_str(version), platform_to_str(platform)].compact.uniq.flatten
+      join ? rv.join(join) : rv
+    end
+    alias_method :meta, :classes
+    alias_method :to_s, :classes
+
+    # Checks if the browser accepts a specific language or languages.
     #
-    # @param query [String] The query to issue. Use `_` in place of `.` in the version.
-    # @param arguments [Array] The arguments to pass the method. Unused from the query.
-    # @param block [Proc] A block to pass to the method. Unused from the query.
-    # @return [Boolean|Query|nil] A query or a boolean value (if `method` ends with `?`). If the query is not valid, `NoMethodError` will be raised.
-    def method_missing(query, *arguments, &block)
-      query_s = query.ensure_string
-      rv = execute_query(parse_query(query_s)) || Brauser::Query.new(self, false)
-      query_s =~ /\?$/ ? rv.result : rv
-    rescue NoMethodError
-      super(query, *arguments, &block)
+    # @param languages [Array] The list of languages.
+    # @return [Boolean] `true` if at least one of requested languages is accepted, `false` otherwise.
+    def accepts?(*languages)
+      languages = normalize_query_arguments(languages)
+      (@languages.keys & languages).present?
     end
 
-    private
+    # Checks if the browser matches a specific query.
+    #
+    # @param name [Symbol|Array] The list of names to check. Also, this meta-name is supported: `:tablet`.
+    # @param engine [Symbol|Array] Alias for `name`, **which has precedence over this.**
+    # @param version [String] The query to match the version.
+    #   It must be a query in the form is `OPERATOR VALUE && ..`, where `OPERATOR` is one of `["<", "<=", "=", "==", ">=", ">"]`.
+    #   You can also pass the value "capable", which will return true for Webkit browsers, IE 10 or above, Firefox 28 and above and Opera 15 and above.
+    # @param platform [Symbol|Array] The list of platforms to check.
+    # @param languages [Symbol|Array] The list of languages to check.
+    # @return [Boolean] `true` if browser match the query, `false` otherwise.
+    def is?(name: nil, engine: nil, version: nil, platform: nil, languages: nil)
+      name ||= engine
+      rv = name ? (@name == apply_aliases(normalize_query_arguments(name))) : true
+      rv &&= query_version(version) if version
+      rv &&= @platform == normalize_query_arguments(platform) if platform
+      rv &&= accepts?(normalize_query_arguments(languages)) if languages
+      rv
+    end
 
-    # Executes a parsed query
+    # Check if the browser is a specific one
     #
-    # @param query [Array] And array of `[method, arguments]` entries.
-    # @return [Brauser::Query] The result of the query.
-    def execute_query(query)
-      query.reduce(Brauser::Query.new(self, true)) { |rv, call|
-        break unless rv.result
-        rv.send(call[0], *call[1])
+    # @param method The browser engine to check.
+    # @param args [Array] **unused.**
+    # @param block [Proc] **unused.**
+    # @return [Boolean] `true` if browser match the engine, `false` otherwise.
+    def method_missing(method, *args, &block)
+      method.to_s =~ /(.+)\?$/ ? is?(name: Regexp.last_match[1]) : super(method, *args, &block)
+    end
+
+    private
+
+    # :nodoc:
+    VERSION_TOKEN = /(?<operator>>=|<=|<|>|!=|(={1,2}))\s*(?<version>.+)/
+
+    # :nodoc:
+    def parse
+      parser = Brauser::Parser.new
+      parse_agent(parser)
+      parse_languages(parser)
+    end
+
+    # :nodoc:
+    def parse_agent(parser)
+      agent = parser.parse_agent(@agent)
+
+      if agent
+        @name, @version, @platform = *agent
+        @human_name = Brauser::Definitions.browsers[@name].try(:name) || "Unknown Browser"
+        @human_platform = Brauser::Definitions.platforms[@platform].try(:name) || "Unknown Platform"
+      else
+        @name = @platform = Brauser::Value.new(:unknown)
+        @human_name = @human_platform = Brauser::Value.new("Unknown")
+        @version = Brauser::Value.new(Versionomy.parse("0.0"))
+      end
+    end
+
+    # :nodoc:
+    def parse_languages(parser)
+      languages = parser.parse_accept_language(@accept_language)
+      @languages = languages
+      @human_languages = languages.reduce({}) { |rv, (code, priority)|
+        rv[Brauser::Definitions.languages[code].name] = priority
+        rv
       }
     end
+
+    # :nodoc:
+    def name_to_str(name)
+      if name
+        name = "" if name.is_a?(TrueClass)
+        rv = @name
+        rv = [:msie_compatibility, :msie] if rv == :msie_compatibility
+        rv.ensure_array(no_duplicates: true) { |n| "#{name}#{n}" }
+      else
+        nil
+      end
+    end
+
+    # :nodoc:
+    def version_to_str(version)
+      if version
+        version = "version-" if version.is_a?(TrueClass)
+        version_str = @version.values_array.reduce([]) { |rv, current|
+          rv << [rv.last, current].compact.join("_")
+          rv
+        }
+
+        version_str.map { |v| "#{version}#{v}" }
+      else
+        nil
+      end
+    end
+
+    # :nodoc:
+    def platform_to_str(platform)
+      if platform
+        platform = "platform-" if platform.is_a?(TrueClass)
+        "#{platform}#{@platform}"
+      else
+        nil
+      end
+    end
+
+    # :nodoc:
+    def normalize_query_arguments(arguments)
+      sanitizer = ->(a) { a.ensure_string.downcase.gsub("_", "-").to_sym }
+      arguments ? arguments.ensure_array(no_duplicates: true, compact: true, flatten: true, &sanitizer) : nil
+    end
+
+    # :nodoc:
+    def apply_aliases(names)
+      names << [:msie, :msie_compatibility] if (names & [:ie, :msie]).present?
+      names << [:chromium] if names.include?(:chrome)
+      names << [:ipad, :android, :kindle] if names.include?(:tablet)
+      names.flatten.compact.uniq
+    end
+
+    # :nodoc:
+    def query_version(version)
+      version.ensure_string.strip.parameterize.to_sym == :capable ? check_capable_browser : check_version(version)
+    end
+
+    # :nodoc:
+    def check_version(version)
+      parser = StringScanner.new(version)
+      rv = true
+
+      until parser.eos?
+        token = parser.scan_until(/(?=&&)|\Z/)
+        parser.skip_until(/&&|\Z/)
+        operator, version = parse_version_token(token)
+
+        rv &&= @version.send(operator, Versionomy.parse(version))
+        break unless rv
+      end
+
+      rv
+    end
+
+    # :nodoc:
+    def check_capable_browser
+      check_capable_browser_engines || check_capable_browser_recents
+    end
+
+    # :nodoc:
+    def check_capable_browser_engines
+      chrome? || safari? || check_capable_browser_recents
+    end
+
+    # :nodoc:
+    def check_capable_browser_recents
+      (firefox? && @version >= "28") || (msie? && @version >= "10") || (opera? && @version >= "15")
+    end
+
+    # :nodoc:
+    def parse_version_token(token)
+      mo = VERSION_TOKEN.match(token)
+      raise ArgumentError, "Invalid version check: #{token}." unless mo
+      [mo["operator"], mo["version"]].map(&:strip)
+    end
   end
 end

data/lib/brauser/definitions/base.rb

@@ -0,0 +1,71 @@
+#
+# This file is part of the brauser gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Brauser
+  # Definitions used by brauser.
+  module Definitions
+    # Registers a new definition.
+    #
+    # @param type [Symbol] The type of the definition. Can be `:browser`, `:language`, `:platform`.
+    # @param args [Array] The arguments of the definition.
+    # @param kwargs [Hash] The keyword arguments of the definition.
+    # @param block [Proc] The block of the definition.
+    def self.register(type, *args, **kwargs, &block)
+      klass =
+        case type
+        when :browser then Brauser::Definitions::Browser
+        when :language then Brauser::Definitions::Language
+        when :platform then Brauser::Definitions::Platform
+        else raise(ArgumentError, "Invalid definition type \"#{type}\".")
+        end
+
+      @definitions ||= {browsers: {}, languages: {}, platforms: {}}
+      definition = klass.new(*args, **kwargs, &block)
+      @definitions["#{type}s".to_sym][definition.id] = definition
+    end
+
+    # Returns the list of browser that can be recognized.
+    #
+    # The keys are the ids, the values are the definitions.
+    #
+    # @return [Hash] The list of browser that can be recognized.
+    def self.browsers
+      @definitions[:browsers]
+    end
+
+    # Returns the list of platforms that can be recognized.
+    #
+    # The keys are the ids, the values are the definitions.
+    #
+    # @return [Hash] The list of platform that can be recognized.
+    def self.platforms
+      @definitions[:platforms]
+    end
+
+    # Returns the list of languages that can be recognized.
+    #
+    # The keys are the ids, the values are the definitions.
+    #
+    # @return [Hash] The list of languages that can be recognized.
+    def self.languages
+      @definitions[:languages]
+    end
+
+    # A class which hold a definition of a browser, a platform or a language.
+    #
+    # @attribute [r] id
+    #   @return The id of the definition.
+    class Base
+      attr_reader :id
+
+      # Performs a match of this definition.
+      #
+      # @return [Object|NilClass] A non falsy value if match succeeded, `false` or `nil` otherwise.
+      def match(_, *_, **_)
+        raise "Must be overridden by a subclass."
+      end
+    end
+  end
+end

data/lib/brauser/definitions/browser.rb

@@ -0,0 +1,80 @@
+#
+# This file is part of the brauser gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Brauser
+  module Definitions
+    # A definition of a platform.
+    #
+    # @attribute [r] name
+    #   @return [String] The platform name.
+    # @attribute [r] engine_matcher
+    #   @return [Regexp|Proc] The pattern or the block to recognize the engine.
+    # @attribute [r] version_matcher
+    #   @return [Regexp|Proc] The pattern or the block to recognize the version.
+    class Browser < Base
+      attr_reader :name, :engine_matcher, :version_matcher
+
+      # Creates a new definition.
+      #
+      # @param id [Symbol] The platform id.
+      # @param name [String] The platform name.
+      # @param engine_matcher [Regexp|Proc] The pattern or the block to recognize the engine.
+      # @param version_matcher [Regexp|Proc] The pattern or the block to recognize the version.
+      def initialize(id, name, engine_matcher, version_matcher, **_)
+        @id = id
+        @name = name
+        @engine_matcher = engine_matcher
+        @version_matcher = version_matcher
+      end
+
+      # Matches against an header.
+      #
+      # @param header [String] The header to match
+      # @return [Array|NilClass] An array with the engine and the version if match succeeded, `false` or `nil` otherwise.
+      def match(header)
+        # First of all, match the engine
+        engine = perform_match(@engine_matcher, header) ? @id : nil
+
+        if engine
+          version = extract_version(perform_match(@version_matcher, header))
+          platform = extract_platform(header, engine)
+          [Brauser::Value.new(engine), Brauser::Value.new(version), Brauser::Value.new(platform)]
+        else
+          nil
+        end
+      end
+
+      private
+
+      # :nodoc:
+      def perform_match(pattern, subject)
+        method = pattern.is_a?(Regexp) ? :match : :call
+        pattern.send(method, subject)
+      end
+
+      # :nodoc:
+      # @private
+      def extract_version(version)
+        # Adjust version
+        version = "0.0" if version.blank?
+        version = version.to_a.last if version.is_a?(::MatchData)
+        Versionomy.parse(version)
+      rescue
+        version
+      end
+
+      # :nodoc:
+      def extract_platform(header, engine)
+        catch(:result) {
+          Brauser::Definitions.platforms.each do |platform, definition|
+            throw(:result, platform) if definition.match(header, engine)
+          end
+
+          nil
+        }
+      end
+    end
+  end
+end