arduino-library 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3b5c76ad31ff11fa46db661d9c15bdd0491d371a
-  data.tar.gz: 15c6b0b9857623d65d41bd3f6b0364f42ffc34c6
+  metadata.gz: a59d64cfdecdeda3f42ddc545b3f55cce2edd407
+  data.tar.gz: a4c1df07773fb1e7934c70716eb574fe0a5d1836
 SHA512:
-  metadata.gz: 233b52e36e5128b7ca9dc5373d5d2f5254e79c25226261d8c0cbbdaf5257275b1d2649e1fcddfc83f1928fc94274826b94ed26cdc8775f68fb9cdaee4930dbfa
-  data.tar.gz: 4ccc781670970f5ba2178842e08cbe9233c5415c8bf226e8e5b26e7b08ac364449b980a3a33802c93b2ee6e65018fb611ecf146cd11622ff27fa0f2a17ef27e2
+  metadata.gz: 06e70b8fd17d082f88ee8b82881c408dc70bae39848038a998ba7b0f4f3c486980d377f8012cb6e17344ddeec32c430236c0d3e9ca741751c8c82c038758e282
+  data.tar.gz: db35e120cdb2f0560427da52ce67db60148814eaec96966c3c0533ef397974fc47f27a75274d4a97895ecfa43ee09c794d4b09812252df9ceb14a6ab759cf181

data/README.md

@@ -39,29 +39,33 @@ Current version only contains Ruby-based API and is meant to be consumed by othe
 ### Configuration
 
 The gem database can be configured to download the default database from a custom URL, 
-keep a local cache in a custom file. It always downloads the index locally, and next time
-it's invoked, the local file is used (if and only if it's size is identical 
-to the remote file).
+and to cache it in a local file. Next time the lookup is invoked local file is checked first. Library automatically checks the size of the remote index file, and re-downloads it if the file has changed.
 
-You can change the configuration in two ways:
+You can modify the source of the default database and the local cache location using one of two methods:
 
- 1. Set environment variables before invoking the gem
- 2. Configure the `DefaultDatabase` class variables
+ 1. By settin the environment variables before invoking the gem;
+ 2. Or by configuring the `DefaultDatabase` class variables.
 
-#### Environment Variables
+#### Setting Environment Variables
 
  * `ARDUINO_CUSTOM_LIBRARY_PATH` can be used to change local top-level path to the libraries folder.
  * `ARDUINO_LIBRARY_INDEX_PATH` can be used to change the location of the cached index file.
 
-#### Class Variables
+#### Change Class Variables for `DefaultDatabase` Class
+
+The following class variables can be changed, like so:
 
 ```ruby
-require 'arduino/library'
-Arduino::Library::DefaultDatabase.library_index_path =
-Arduino::Library::DefaultDatabase.library_index_url  =
-Arduino::Library::DefaultDatabase.library_path       =
+Arduino::Library::DefaultDatabase.library_index_url = ''
+```
+
+ * `library_index_url` — URL to download compressed JSON index.
+ * `library_index_path` — local path to the cached compressed JSON index.
+ * `library_path` — local top-level folder where your Arduino libraries are.
+
+If you change any of the above, please reload the database with:
 
-# then reload the database:
+```ruby
 Arduino::Library::DefaultDatabase.instance.setup
 ```
 
@@ -79,26 +83,29 @@ DEFAULT_ARDUINO_LIBRARY_INDEX_PATH =
     (ENV['HOME'] + '/Documents/Arduino/Libraries/index.json.gz')
 ```
 
-### Using the top-level module
+### Finding and Resolving Arduino Libraries
 
-If you prefer not to have hard-coded dependencies on the `Arduino::Library::*` sub-classes and sub-modules, you can use the top level module, which proxies several shortcut methods.
+Top level module `Arduino::Library` provides a convenient Facáde into the library functionality. Therefore you can use the library by calling these methods directly, such as `Arduino::Library.library_from(..)` or by including the module in your current context.
 
-You can access these methods in two different ways:
+Below we'll include the top level module, and use the shortcut methods to explore available functionality. That said, if you prefer not to include the top level module, you can call the same functions directly on the module itself.
 
-  1. As class methods on `Arduino::Library`, for example `Arduino::Library.db_default`
-  2. By including the top-level module in your context, and using methods as instance methods in the current context, eg. `#db_default`
+There are two ways to include the DSL in your context:
 
-Below we'll focus on the second usage, but if you prefer to use the first syntax, it's there and available for you.
+```ruby
+require 'arduino/library'
+class Foo
+  include Arduino::Library::InstanceMethods
+end
+```
 
-You can require the library for use in the DSL:
+Or, perhaps easier:
 
 ```ruby
 class Foo
-  # this loads the library, and includes its methods in the current context
   require 'arduino/library/include
 end
 ```
-
+### Facáde Methods
 
 #### Using `db_from`
 
@@ -150,6 +157,15 @@ search(database = db_default, **opts)
 
 **Examples**
 
+Here is searching for 'AudioZero' and sorting results by the version number:
+
+```ruby
+search(name: 'AudioZero').sort.first.version #=> "1.0.0"
+search(name: 'AudioZero').sort.last.version  #=> "1.1.1"
+```
+
+You can search by any attribute, not just name and number:
+
 ```ruby
 results = search(
   # direct string equality

data/arduino-library.gemspec

@@ -32,4 +32,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rspec-its'
+  spec.add_development_dependency 'irbtools'
 end

data/lib/arduino/library.rb

@@ -2,13 +2,15 @@ require 'open-uri'
 
 module Arduino
   module Library
-    DEFAULT_ARDUINO_LIBRARY_INDEX_URL  =
-      'http://downloads.arduino.cc/libraries/library_index.json.gz'
-    DEFAULT_ARDUINO_LIBRARY_PATH       =
-      ENV['ARDUINO_CUSTOM_LIBRARY_PATH'] || (ENV['HOME'] + '/Documents/Arduino/Libraries')
-    DEFAULT_ARDUINO_LIBRARY_INDEX_PATH =
-      ENV['ARDUINO_LIBRARY_INDEX_PATH'] ||
-        (ENV['HOME'] + '/Documents/Arduino/Libraries/index.json.gz')
+    unless defined?(DEFAULT_ARDUINO_LIBRARY_INDEX_URL)
+      DEFAULT_ARDUINO_LIBRARY_INDEX_URL  =
+        'http://downloads.arduino.cc/libraries/library_index.json.gz'
+      DEFAULT_ARDUINO_LIBRARY_PATH       =
+        ENV['ARDUINO_CUSTOM_LIBRARY_PATH'] || (ENV['HOME'] + '/Documents/Arduino/Libraries')
+      DEFAULT_ARDUINO_LIBRARY_INDEX_PATH =
+        ENV['ARDUINO_LIBRARY_INDEX_PATH'] ||
+          (ENV['HOME'] + '/Documents/Arduino/Libraries/index.json.gz')
+    end
   end
 end
 
@@ -19,44 +21,12 @@ require 'arduino/library/types'
 require 'arduino/library/model'
 require 'arduino/library/database'
 require 'arduino/library/default_database'
+require 'arduino/library/resolver'
+require 'arduino/library/instance_methods'
 
 module Arduino
   module Library
-    # @param [String] file_or_url — either a local file, or URL, can be gzipped
-    def db_from(file_or_url)
-      Database.new(file_or_url)
-    end
-
-    def db_default
-      DefaultDatabase.instance
-    end
-
-    #
-    # +file_or_url+ can be a JSON file name, a .properties file name, or
-    # a URL to either of the above.
-    #
-    # @param [String] file_or_url
-    def library_from(file_or_url)
-      Arduino::Library::Model.from(file_or_url)
-    end
-
-    # +opts+ is a Hash that you can use to pass attributes with values, any
-    # number of them. All matching results are returned as models.
-    #
-    #   name: 'AudioZero'
-    #   author: /konstantin/i              - regexp supported
-    #   architectures: [ 'avr' ]           - array is matched if it's a subset
-    #   version: proc do |value|           — or a proc for max flexibility
-    #     value.start_with?('1.') )
-    #   end
-    #
-    # @param [Database] database db instance (or skip it to use the default)
-    # @param [Hash] opts hash of attribute names and values to match
-    # @return Array<Model> array of models that match
-    def search(database = db_default, **opts)
-      Arduino::Library::Model.database = database
-      database.search(**opts)
-    end
+    include InstanceMethods
   end
 end
 

data/lib/arduino/library/include.rb

@@ -1,3 +1,3 @@
 require 'arduino/library'
 
-include Arduino::Library
+include Arduino::Library::InstanceMethods

data/lib/arduino/library/instance_methods.rb

@@ -0,0 +1,43 @@
+require 'arduino/library'
+
+module Arduino
+  module Library
+    module InstanceMethods
+      # @param [String] file_or_url — either a local file, or URL, can be gzipped
+      def db_from(file_or_url)
+        Database.new(file_or_url)
+      end
+
+      def db_default
+        DefaultDatabase.instance
+      end
+
+      #
+      # +file_or_url+ can be a JSON file name, a .properties file name, or
+      # a URL to either of the above.
+      #
+      # @param [String] file_or_url
+      def library_from(file_or_url)
+        Arduino::Library::Model.from(file_or_url)
+      end
+
+      # +opts+ is a Hash that you can use to pass attributes with values, any
+      # number of them. All matching results are returned as models.
+      #
+      #   name: 'AudioZero'
+      #   author: /konstantin/i              - regexp supported
+      #   architectures: [ 'avr' ]           - array is matched if it's a subset
+      #   version: proc do |value|           — or a proc for max flexibility
+      #     value.start_with?('1.') )
+      #   end
+      #
+      # @param [Database] database db instance (or skip it to use the default)
+      # @param [Hash] opts hash of attribute names and values to match
+      # @return Array<Model> array of models that match
+      def search(database = db_default, **opts)
+        Arduino::Library::Model.database = database
+        database.search(**opts)
+      end
+    end
+  end
+end

data/lib/arduino/library/model.rb

@@ -1,5 +1,7 @@
 require_relative 'types'
 require_relative 'utilities'
+require_relative 'instance_methods'
+require_relative 'resolver'
 require 'json'
 
 module Arduino
@@ -7,6 +9,7 @@ module Arduino
     # This class represents a single entry into the library-index.json file,
     # in other words — a `library.properties` file.
     class Model < Dry::Struct
+      include Comparable
 
       # noinspection RubyResolve
       constructor_type :symbolized
@@ -15,8 +18,30 @@ module Arduino
         self.attribute field, eval(type)
       end
 
+      # Instance Methods
+
+      # Convert a version such as '1.44.3' into a number '1044003' for easy
+      # sorting and comparison.
+      def version_to_i
+        if version
+          first, second, third = version.split(/\./).map(&:to_i)
+          10**6 * (first || 0) + 10**3 * (second || 0) + (third || 0)
+        else
+          0
+        end
+      rescue
+        0
+      end
+
+      def <=>(another)
+        self.version_to_i <=> another.version_to_i
+      end
+
+      # Class Methods
+
       class << self
         include Utilities
+        include InstanceMethods
 
         attr_writer :database
 
@@ -29,7 +54,7 @@ module Arduino
         end
 
         def from_json_file(file_or_url)
-          file  = read_file_or_url(file_or_url)
+          file = read_file_or_url(file_or_url)
           from_json(file.read)
         end
 
@@ -75,26 +100,26 @@ module Arduino
         #
         # @return [Model | Array<Model> ] — array for search, otherwise a model
         def from(source = nil, **opts)
-          case source
-            when Hash
-              from_hash(source)
-            when String
-              if source =~ /^{/m
-                from_json(source)
-              elsif File.exist?(source)
-                if source =~ /\.json(\.gz)?$/i
-                  from_json_file(source)
-                elsif source =~ /\.properties(\.gz)?$/i
-                  from_properties_file(source)
-                end
-              end
-            when NilClass
-              if opts && opts[:name] && opts[:version]
-                search(**opts)
-              end
-          end
+          model = case source
+                    when Hash
+                      from_hash(source)
+                    when String
+                      if source =~ /^{/m
+                        from_json(source)
+                      elsif File.exist?(source)
+                        if source =~ /\.json(\.gz)?$/i
+                          from_json_file(source)
+                        elsif source =~ /\.properties(\.gz)?$/i
+                          from_properties_file(source)
+                        end
+                      end
+                    when NilClass
+                      if opts && opts[:name] && opts[:version]
+                        search(**opts)
+                      end
+                  end
+          model ? Resolver.resolve(model) : model
         end
-
       end
     end
   end

data/lib/arduino/library/presenters/properties.rb

@@ -60,4 +60,3 @@ module Arduino
     end
   end
 end
-

data/lib/arduino/library/resolver.rb

@@ -0,0 +1,62 @@
+require 'arduino/library'
+require 'arduino/library/instance_methods'
+require 'arduino/library/model'
+
+module Arduino
+  module Library
+    # This method is used internally by the Model class's #from method.
+    module Resolver
+      class << self
+        include ::Arduino::Library::InstanceMethods
+
+        # Resolves a given model without a URL by performing a
+        # search in the Ardiuino Library for the library name and version.
+        #
+        #      model = Arduino::Library::Resolver.resolve({ name: 'AudioZero'} )
+        #      # => <Arduino::Library::Model#0x3242gfa2...>
+        #
+        #      model.url # => 'https://github.com/.......'
+        #
+        # @param [Model] model with a partial information only, such as the name.
+        # @return [Model] a resolved model with #url provided, if found, nil otherwise.
+        def resolve(model)
+          raise ArgumentError, 'Model argument is required' unless model
+          model = Model.from(model) unless model.is_a?(Model)
+          return model if model && model.url
+
+          query = construct_query(model)
+          return nil if query.empty?
+
+          latest_version_by(query)
+        end
+
+        # Given a model with partial information, constructs a query
+        # by name and version.
+        # @param [Model] model a library model with name, and optionally version
+        # @return [Hash] query to be passed to #search. (See Arduino::Library::InstanceMethods#search)
+        def construct_query(model)
+          query = {}
+          query.merge!(name: model.name) if model.name
+          query.merge!(version: model.version) if model.version
+          query
+        end
+
+        # Executes a given query, and if more than one version is returned
+        # returns the last most recent version of the library.
+        #
+        # @param [Hash] query model attributes to search for, eg, +name: 'AudioZero'
+        # @return <Model>  search result, or the most recent version if many match
+        def latest_version_by(query)
+          results = if query.key?(:name)
+                      Model.find(**query).sort
+                    else
+                      Model.find(**query)
+                    end
+          return nil if results.size == 0
+          return results.first if results.size == 1
+          results.last
+        end
+      end
+    end
+  end
+end

data/lib/arduino/library/utilities.rb

@@ -39,6 +39,8 @@ module Arduino
       end
 
       def download(url, path)
+        debug "dowloading from [#{url.to_s.bold.red}]"
+        debug "             to [#{path.to_s.bold.green}]"
         open(path, 'wb') do |file|
           file << open(url).read
         end

data/lib/arduino/library/version.rb

@@ -1,6 +1,6 @@
 module Arduino
   module Library
-    VERSION = '0.3.2'
+    VERSION = '0.4.0'
     DESCRIPTION = <<-eof
       This gem encapsulates many concepts related to how Arduino Libraries are indexed, how their metadata is validated, or .properties file generated. It supports searching the Arduino library database for any terms. This gem is used by Arli — Arduino Installer CLI toolkit.
     eof

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arduino-library
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-23 00:00:00.000000000 Z
+date: 2017-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -150,6 +150,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: irbtools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: "      This gem encapsulates many concepts related to how Arduino Libraries
   are indexed, how their metadata is validated, or .properties file generated. It
   supports searching the Arduino library database for any terms. This gem is used
@@ -174,8 +188,10 @@ files:
 - lib/arduino/library/database.rb
 - lib/arduino/library/default_database.rb
 - lib/arduino/library/include.rb
+- lib/arduino/library/instance_methods.rb
 - lib/arduino/library/model.rb
 - lib/arduino/library/presenters/properties.rb
+- lib/arduino/library/resolver.rb
 - lib/arduino/library/types.rb
 - lib/arduino/library/utilities.rb
 - lib/arduino/library/version.rb