ALD 0.1.0 → 0.1.1

data/lib/ALD/conditioned.rb

@@ -0,0 +1,216 @@
+require 'semantic'
+
+module ALD
+  class API
+    # Internal: used by Collection classes to work with special conditions in #where.
+    #
+    # Requires @conditions to be the instance's condition Hash.
+    module Conditioned
+      # Public: Filter the Collection's data.
+      # See the documentation on the individual classes for more information.
+      def where(conditions)
+        return self if conditions.nil? || conditions.empty?
+        new_conditions = merge_conditions(conditions)
+
+        if initialized? && Collection::LocalFilter.can_apply?(conditions, self.class::LOCAL_CONDITIONS)
+          self.class::new(
+            @api,
+            new_conditions,
+            Collection::LocalFilter.apply_conditions(@data, conditions)
+          )
+        else
+          self.class::new(@api, new_conditions)
+        end
+      end
+
+      private
+
+      # Internal: The HTTP query conditions for the range specified in the
+      # instance's conditions.
+      #
+      # Returns a Hash, that contains the query parameters matching the range
+      # specified in the conditions, or an empty Hash if there is no range
+      # specified.
+      def range_query
+        data = {}
+        if @conditions.key?(:range)
+          data['start'] = @conditions[:range].min
+          data['count'] = @conditions[:range].max - @conditions[:range].min + 1
+        end
+        data
+      end
+
+      # Internal: The HTTP query conditions for the sorting specified in the
+      # instance's conditions.
+      #
+      # Returns a Hash containing the query parameters matching the specified
+      # sorting, or an empty Hash if there's no sorting specified.
+      def sort_query
+        Hash[
+          present_conditions(%w[sort]).map { |cond| [cond, @conditions[cond.to_sym].map { |k, dir| "#{dir == :desc ? '-' : ''}#{k}" }.join(',')] }
+        ]
+      end
+
+      # Internal: The HTTP query conditions for exact queries for a set of
+      # given conditions.
+      #
+      # conds - an Array of Strings, containing the condition names to handle
+      #
+      # Returns a Hash with the query parameters matching the instance's values
+      # on the specified conditions, or an empty Hash, if there are none.
+      def exact_queries(conds)
+        Hash[
+          present_conditions(conds).map { |cond| [cond, @conditions[cond.to_sym]] }
+        ]
+      end
+
+      # Internal: The HTTP query conditions for queries for an array of values
+      # for the given conditions.
+      #
+      # conds - an Array of Strings, containing the condition names to handle
+      #
+      # Returns a Hash with the query parameters matching the instance's values
+      # on the specified conditions, or an empty Hash.
+      def array_queries(conds)
+        Hash[
+          present_conditions(conds).map { |cond| [cond, @conditions[cond.to_sym].join(',')] }
+        ]
+      end
+
+      # Internal: The HTTP query conditions for queries with conditions that
+      # can be switched on, off or indeterminate.
+      #
+      # conds - an Array of Strings, containing the condition names to handle
+      #
+      # Returns a Hash with the query parameters matching the instance's values
+      # on the specified conditions, or an empty Hash.
+      def switch_queries(conds)
+        map = {true => 'true', false => 'false', nil => 'both'}
+        Hash[
+          present_conditions(conds).map { |cond| [cond, map[@conditions[cond.to_sym]]] }
+        ]
+      end
+
+      # Internal: The HTTP query conditions for queries with conditions that
+      # allow specifying a range of values.
+      #
+      # conds - an Array of Strings, containing the condition names to handle
+      #
+      # Returns a Hash with the query parameters matching the instance's values
+      # on the specified conditions, or an empty Hash.
+      def range_condition_queries(conds)
+        Hash[
+          present_conditions(conds).map { |cond|
+            fields = @conditions[cond.to_sym].is_a?(Array) ? @conditions[cond.to_sym] : [@conditions[cond.to_sym]]
+            fields.map do |field|
+              match = RANGE_REGEX.match(field)
+              if match.nil? # just a specific field
+                [cond, field]
+              else # min or max
+                ["#{cond}-#{match[1] == '>=' ? 'min' : 'max'}", match[2]]
+              end
+            end
+          }.flatten(1)
+        ]
+      end
+
+      # Internal: Get the subset of conditions that are present on the instance
+      #
+      # conds - an Array of Strings, containing the condition names to check
+      #
+      # Returns an Array of Strings with a subset of the given conds, namely
+      # those that are present on @conditions.
+      def present_conditions(conds)
+        conds.select { |cond| @conditions.key?(cond.to_sym) }
+      end
+
+      # Internal: Merge new conditions with the current ones.
+      #
+      # conditions - the new condition Hash to merge
+      #
+      # Returns the merged Hash
+      #
+      # Raises ArgumentError if the conditions are incompatible
+      def merge_conditions(conditions)
+        @conditions.merge(conditions) do |key, old_value, new_value|
+          if self.class::RANGE_CONDITIONS.include?(key.to_s)
+            merge_ranges(key, old_value, new_value) # handle merging for cases like 'downloads >= 5' and 'downloads <= 9' etc.
+          elsif self.class::ARRAY_CONDITIONS.include?(key.to_s)
+            old_value + new_value
+          elsif key == :range # not a "range condition" in the sense used above
+            range_offset(new_value)
+          elsif key == :sort
+            new_value # enable re-sorting
+          else
+            raise ArgumentError # for other overwrites fail!
+          end
+        end
+      end
+
+      # Internal: A regex to determine if a range condition is specifying a range.
+      RANGE_REGEX = /^\s*(<\=|>\=)\s*(.*)$/
+
+      # Internal: Handle condition conflicts for range conditions. Used by #where.
+      #
+      # key - the Symbol key whose range is merged
+      # old - the old range condition value
+      # new - the new range condition value to be applied on top of the old one
+      #
+      # Returns the value that should be used in the merged conditions.
+      #
+      # Raises ArgumentError if the conflict cannot be resolved.
+      def merge_ranges(key, old, new)
+        constraints = [new, old]
+        data = constraints.map do |c|
+          match = RANGE_REGEX.match(c)
+          if match.nil?
+            [nil, c]
+          elsif key == :version
+            [match[1], Semantic::Version.new(match[2])]
+          else
+            [match[1], match[2]]
+          end
+        end
+        ops, values = data.map(&:first), data.map(&:last)
+
+        if ops[0] != ops[1] # one min, one max OR one min/max, one exact
+          constraints # => keep both
+
+        elsif ops.none?(&:'nil?') # two range constraints of same type
+          ops[0] == '>=' ? ">= #{values.max.to_s}" : "<= #{values.min.to_s}"
+
+        else # two exact values
+          if constraints[0].strip == constraints[1].strip # if both are the same, just keep one
+            constraints[0]
+          else # otherwise this can't be good - throw an error
+            raise ArgumentError
+          end
+        end
+      end
+
+      # Internal: Compute an absolute Range from a given relative Range. As
+      # ranges specified in #where are relative to this collection, they must
+      # be transformed to absolute ranges before being passed to ::new.
+      #
+      # new_range - the relative Range to transform
+      #
+      # Returns the absolute Range.
+      #
+      # Raises ArgumentError if the relative Range does not fit into this
+      # collection's Range.
+      def range_offset(new_range)
+        if @conditions[:range].nil?
+          min, max = 0, Float::Infinity
+        else
+          min, max = @conditions[:range].min, @conditions[:range].max
+        end
+
+        new_min = min + new_range.min
+        new_max = new_min + new_range.max - new_range.min # == new_min + new_range.size - 1
+        raise ArgumentError if new_min > max || new_max > max
+
+        (new_min..new_max)
+      end
+    end
+  end
+end

data/lib/ALD/item.rb

@@ -0,0 +1,186 @@
+require_relative 'collection_entry'
+require 'date'
+
+module ALD
+  class API
+    # Public: An item (e.g. a library or app) uploaded to an ALD server.
+    class Item < CollectionEntry
+
+      # Public: Get the ID of the item.
+      #
+      # Examples
+      #
+      #   puts item.id
+      #
+      # Returns a String of 32 characters, containing the item's GUID.
+      #
+      # Signature
+      #
+      #   item()
+
+      # Public: Get the name of the item.
+      #
+      # Examples
+      #
+      #   puts "Item: #{item.name}"
+      #
+      # Returns a String containing the item name.
+      #
+      # Signature
+      #
+      #   name()
+
+      # Public: Get the item version.
+      #
+      # Examples
+      #
+      #   puts "#{item.name} v#{item.version}"
+      #
+      # Returns a String containing the version of the item.
+      #
+      # Signature
+      #
+      #   version()
+
+      # Public: Get the item's summary text. This method might trigger a HTTP
+      # request.
+      #
+      # Returns a String summarizing the item's purpose and contents.
+      #
+      # Signature
+      #
+      #   summary()
+
+      # Public: Get the item's description text. This method might trigger a
+      # HTTP request.
+      #
+      # Returns a String with the item's description.
+      #
+      # Signature
+      #
+      #   description()
+
+      # Public: Get the time the item was uploaded. This method might trigger a
+      # HTTP request.
+      #
+      # Returns a DateTime describing the time the item was first uploaded to
+      # the ALD server.
+      #
+      # Signature
+      #
+      #   uploaded()
+
+      # Public: Get if the item has been marked as reviewed by the ALD server.
+      # This method might trigger a HTTP request.
+      #
+      # Returns a Boolean indicating if the item was revieed or not.
+      #
+      # Signature
+      #
+      #   reviewed()
+
+      # Public: Get the number of downloads for the item. This method might
+      # trigger a HTTP request.
+      #
+      # Returns an Integer indicating how often the item was downloaded.
+      #
+      # Signature
+      #
+      #  downloads()
+
+      # Public: Get the tags the item was tagged with. This method might
+      # trigger a HTTP request.
+      #
+      # Returns an Array of Symbols representing the tags.
+      #
+      # Signature
+      #
+      #   tags()
+
+      # Public: get author information from the item. This method might trigger
+      # a HTTP request.
+      #
+      # Returns an Array of Hashes describing the authors.
+      #
+      # Signature
+      #
+      #   authors()
+
+      # Public: Get the user who owns the item. This method might trigger a
+      # HTTP request.
+      #
+      # Returns the ALD::API::User who owns the item.
+      #
+      # Signature
+      #
+      #   user()
+
+      # Public: Get the ratings the item was given. This method might trigger a
+      # HTTP request.
+      #
+      # Returns an Array of Integers representing the ratings given to the item
+      # by users.
+      #
+      # Signature
+      #
+      #   ratings()
+
+      # Internal: Create a new instance for given data. This method should not
+      # called by library consumers. Instead access entries via API#item or
+      # ItemCollection#[].
+      #
+      # api         - the ALD::API instance this item belongs to
+      # data        - a Hash containing data concerning the item:
+      #               id      - the GUID of the item
+      #               name    - the name of the item
+      #               version - the semver version of the item
+      #               The above fields are mandatory. However, the hash may
+      #               contain a lot more data about the item.
+      # initialized - a Boolean indicating if data only contains the mandatory
+      #               fields or *all* data on the item.
+      def initialize(api, data, initialized = false)
+        raise ArgumentError unless Item.valid_data?(data)
+        super(api, data, initialized)
+      end
+
+      private
+
+      # Internal: If the item was initialized with only mandatory data, use the
+      # API to request all missing information.
+      #
+      # Returns nothing.
+      def request
+        @data = @api.request("/items/#{id}")
+        @data['uploaded'] = DateTime.parse(@data['uploaded'])
+        @data['tags'].map!(&:to_sym)
+        @data['user'] = @api.user(@data['user'])
+      end
+
+      # Internal: Ensure a Hash contains all information necessary to be passed
+      # to #new.
+      #
+      # data - the Hash to check for mandatory fields
+      #
+      # Returns true if the Hash is valid, false otherwise.
+      def self.valid_data?(data)
+        data.is_a?(Hash) && initialized_attributes.all? { |k| data.key?(k) }
+      end
+
+      # Internal: Override of CollectionEntry#initialized_attributes to enable
+      # automatic method definition, in this case #id, #name and #version.
+      #
+      # Returns an Array of attribute names (String)
+      def self.initialized_attributes
+        %w[id name version]
+      end
+
+      # Internal: Override of CollectionEntry#requested_attributes to enable
+      # automatic method definition.
+      #
+      # Returns an Array of attribute names (String)
+      def self.requested_attributes
+        %w[summary description uploaded reviewed downloads tags authors user ratings]
+      end
+    end
+  end
+end

data/lib/ALD/item_collection.rb

@@ -0,0 +1,169 @@
+require_relative 'collection'
+require_relative 'conditioned'
+require_relative 'local_filter'
+
+module ALD
+  class API
+    # Public: Represents a (possibly filtered) set of items on an ALD server
+    class ItemCollection < Collection
+      include Conditioned
+
+      # Internal: Create a new instance. This should not be called by library
+      # consumers. Instead use API#items or #where to get a new instance.
+      #
+      # api        - the ALD::API instance this collection belongs to
+      # conditions - a Hash of conditions items in this collection must meet
+      # data       - an Array of Hashes representing the items in this
+      #              collection:
+      #              id      - the GUID of the item
+      #              name    - the item's name
+      #              version - the item's semver version
+      def initialize(api, conditions = {}, data = nil)
+        super(api, conditions, data)
+      end
+
+      # Public: Access an individual item by ID, name and version or index in
+      # the collection. This method may trigger a HTTP request.
+      #
+      # Examples
+      #
+      #   items['185d265f24654545aad3f88e8a383339'] # access the item with this ID
+      #   items['MyApp', '0.1.2'] # access a specific version of an item
+      #   items[4] # access the 5th item in the collection (zero-based index)
+      #            # This makes most sense in an explicitly ordered collection
+      #
+      # Returns the corresponding ALD::API::Item instance, or nil if not found
+      #
+      # Signature
+      #
+      #   [](id)
+      #   [](name, version)
+      #   [](index)
+      #
+      # id      - a GUID String uniquely identifying the item
+      # name    - a String containing the item's name
+      # version - a String containing the item's semver version
+      # index   - an Integer with the item's zero-based index within the
+      #           collection.
+
+      # Internal: filter conditions that allow specifying a range, like
+      # 'version-min=0.2.1&version-max=3.4.5'
+      RANGE_CONDITIONS = %w[version downloads rating]
+
+      # Internal: filter conditions that allow specifying an array.
+      ARRAY_CONDITIONS = %w[tags]
+
+      # Internal: filter conditions that can be handled locally.
+      LOCAL_CONDITIONS = %w[name version]
+
+      # Public: Filter and/or sort this collection and return a new collection
+      # containing a subset of its items.
+      #
+      # conditions - a Hash of conditions to filter for
+      #              :name      - filter for items with this name (String)
+      #              :user      - only return items by this user (given the user
+      #                           name or the ID) (String)
+      #              :type      - only return items of this type (String)
+      #              :downloads - If given only a number, return only items with
+      #                           this number of downloads. More commonly, pass
+      #                           a string like '>= 4' or '<= 5' (or an array of
+      #                           such strings) to select items in a range of
+      #                           download counts.
+      #              :rating    - Select items with a given rating. Like
+      #                           for :downloads, ranges can be specified.
+      #              :version   - Only items with a given semver version number.
+      #                           Here as well, ranges can be specified. Semver
+      #                           rules are taken into account when sorting.
+      #              :stable    - Set to true to only return items whose semver
+      #                           version indicates they're stable.
+      #              :reviewed  - Set to true to filter for items that are marked
+      #                           as reviewed by the server.
+      #              :tags      - A tag or an array of tags to filter for.
+      #              :sort      - an Array of sorting criteria, in descending
+      #                           order of precedence; or a Hash where the keys
+      #                           are the sorting criteria, and the values (:asc,
+      #                           :desc) indicate sorting order.
+      #              :range     - A zero-based Range of items to return. This
+      #                           makes most sense in combination with sorting.
+      #                           Note that the range is relative to the
+      #                           collection the operation is performed upon.
+      #
+      # Returns a new ItemCollection instance (or self, if conditions is nil)
+      #
+      # Raises ArgumentError if the conditions are invalid or incompatible with
+      # this collection's conditions.
+      #
+      # Signature
+      #
+      #   where(conditions)
+
+      private
+
+      # Internal: Make a HTTP request to the ALD server to get the list of item
+      # hashes matching this collection's conditions.
+      #
+      # Returns nothing.
+      def request
+        data = [
+          exact_queries(%w[name user type]),
+          switch_queries(%w[stable reviewed]),
+          array_queries(%w[tags]),
+          range_condition_queries(%w[downloads rating version]),
+          sort_query,
+          range_query
+        ].reduce({}, :merge)
+
+        url = "/items/#{data.empty? ? '' : '?'}#{URI.encode_www_form(data)}"
+        @data = @api.request(url).map do |hash|
+          hash['id'] = @api.normalize_id(hash['id'])
+          hash
+        end
+      end
+
+      # Internal: Make a HTTP request to the ALD server to get a single item.
+      # Used by Collection#[].
+      #
+      # filter - a filter Hash as returned by #entry_filter
+      #
+      # Returns a Hash with all information about the item.
+      #
+      # Raises ArgumentError if the filters cannot be handled.
+      def request_entry(filter)
+        url = if filter.key?(:id)
+          "/items/#{filter[:id]}"
+        elsif %w[name version].all? { |k| filter.key?(k.to_sym) }
+          "/items/#{filter[:name]}/#{filter[:version]}"
+        else
+          raise ArgumentError
+        end
+
+        @api.request(url)
+      end
+
+      # Internal: Used by Collection#each and Collection#[] to create new items.
+      #
+      # hash        - a Hash describing the item, with the keys 'id', 'name'
+      #               and 'version'.
+      # initialized - a Boolean indicating if the given Hash already contains
+      #               all information about the item or only name and id.
+      def entry(hash, initialized = false)
+        @api.item(hash, initialized)
+      end
+
+      # Internal: Implements item access for #[]. See Collection#entry_filter
+      # for more information.
+      #
+      # ItemCollection allows access by ID (String) or name and version
+      # (both String).
+      def entry_filter(args)
+        if args.length == 1 && args.first.is_a?(String)
+          { id: @api.normalize_id(args.first) }
+        elsif args.length == 2
+          { name: args.first, version: args.last }
+        else
+          raise ArgumentError
+        end
+      end
+    end
+  end
+end