arduino-library 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 66aeda9e6680093e8c8225ba6b7e4d66b2389c48
-  data.tar.gz: 695f68cdea0c96ac44a46817b168210a0c0a79c8
+  metadata.gz: dfd69741b18cd50e564b668bfec0d7a0e50e1392
+  data.tar.gz: bd4b4443a0598213ba330f3ac21082bc29eba77c
 SHA512:
-  metadata.gz: a72df69b7cf8ae242bc0ba37dd6abaca3214d52e3e3251bb3015ce08f3bf03883606c065e628b2d09f5d2db0d4d38c2d51423aa29006128bcbcec36c30a29daa
-  data.tar.gz: bc91451ac384c4f7a6676d61446da720840715a9f707f3e2095a6631604f5413ddf18d4f2a51b4e53e061d5b75a5773adeb658ee675713b77c6e34f3706fdbe5
+  metadata.gz: 679f7c39fa04c902061f687be5c9ddfcf56c28b3d754540141cac679390256b9ac312b218b506568613cee9d117453e44676e9a188d4d0c712c4a6972ced374a
+  data.tar.gz: 97117d676ce82780c48a6ab277d5e5fa30d65737fbc6df8fb5e1158e51a4149dee6d8d462deab9065ae5e3317b17b3f9ccc81fa1e54702f927a4bb3e5f76edca

data/README.md

@@ -8,13 +8,14 @@
 
 # Arduino::Library
 
-This gem encapsulates various rules about the [`library.properties`](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#library-metadata) file that contains meta-data about Arduino Libraries.
+> NOTE: This gem is the underpinning for [Arli](https://github.com/kigster/arli) — command line Arduino Library manager.
 
-It also provides convenient shortcuts for downloading the Arduino-maintained database of published libraries in JSON format, searching for various libraries, choosing a version, and more.
+This library offers a ruby model representing an Arduino Library, including field validation, reading and writing the [`library.properties`](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#library-metadata) file, or searching for libraries in the official database.
 
-It also provides validation functionality for the `library.properties` file for your custom libraries you would like to open source.
- 
+Searching for a library will transparently download and cache the Arduino-maintained JSON database of official libraries locally, so that future searches are fast. 
 
+The library also provides validation functionality for the `library.properties` file for your custom libraries you would like to open source.
+ 
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -69,26 +70,16 @@ Arduino::Library::DefaultDatabase.library_index_url = ''
 If you change any of the above, please reload the database with:
 
 ```ruby
-Arduino::Library::DefaultDatabase.instance.setup
+Arduino::Library::DefaultDatabase.reload!
 ```
 
 #### Default Values:
 
-```ruby
-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')
-```
+Please review the [`library.rb`](https://github.com/kigster/arduino-library/blob/master/lib/arduino/library.rb) file to understand how these variables are resolved.
 
 ### Finding and Resolving Arduino Libraries
 
-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.
+The primary module `Arduino::Library` provides a convenient Facáde into all of 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.
 
 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.
 
@@ -101,13 +92,14 @@ class Foo
 end
 ```
 
-Or, perhaps easier:
+Or, perhaps even easier:
 
 ```ruby
 class Foo
-  require 'arduino/library/include
+  require 'arduino/library/include'
 end
 ```
+
 ### Facáde Methods
 
 #### Using `db_from`
@@ -146,6 +138,28 @@ library_from('https://raw.githubusercontent.com/PaulStoffregen/DS1307RTC/master/
 #=> 'DS1307RTC'
 ```
 
+In the next section you will read about the search, but the truth is that the `library_from` method actualy will fall back to search if you provide a partial hash. The allowed values in the hash are: `name, checksum, archiveFileName`. Since these keys often uniquely identify a library, the gem attempts to find it for you.
+
+```ruby
+require 'arduino/library/include' #=> true
+library_from(name: 'AudioZero')
+    => #<Arduino::Library::Model 
+            name="AudioZero" 
+            version="1.1.1" 
+            author="Arduino" 
+            maintainer="Arduino <info@arduino.cc>"
+            ..........>
+
+library_from(checksum: 'SHA-256:4604a3b92b9f4a7dd92534eb09247443fa5078e6bd0e7a2c5f3060eaba2ad974')
+    => #<Arduino::Library::Model 
+            name="AudioZero" 
+            version="1.1.1" 
+            author="Arduino" 
+            maintainer="Arduino <info@arduino.cc>"
+            ..........>
+```
+
+
 #### Using `search`
 
 Method `search` is, perhaps, some of the most powerful functionality in this gem. It allows constructing very flexible and precise queries, to match any number of library attributes.
@@ -192,7 +206,11 @@ results.size
 
 Note that multiple attributes must ALL match for the library to be included in the result set.
 
-### `Arduino::Library::Database`
+### Low-level API
+
+The Facade is the recommended way to use library. Below we briefly describe the low-level API of the underlying classes.
+
+#### `Arduino::Library::Database`
 
 > Downloading the index of all libraries, and searching for a library.
 
@@ -229,7 +247,7 @@ end
 You can pass any of the attributes to #search, and the value can be a `String` (in which case only equality matches), or a regular expression, eg:
 
 ```ruby
-database.search(author: "Paul Stoffregen").size #=> 21
+database.search(author: 'Paul Stoffregen').size #=> 21
 database.search(author: /stoffregen/i).size     #=> 33
 ```
 
@@ -249,11 +267,11 @@ all_versions = database.search(name: 'AudioZero')
 # => [ Arduino::Library::Model<name: AudioZero, version: '1.0.1',... >, .. ]
 ```
 
-### `Arduino::Library::Model` 
+#### `Arduino::Library::Model` 
 
 > Use this class to operate on a single library.
 
-#### Reading Library from an External Source using `.from`
+##### Reading Library from an External Source using `.from`
 
 You can use an intelligent class method `.from` that attempts to auto-detect the type of file or URL you are passing as an argument, and use an appropriate parser for each type. 
 
@@ -273,11 +291,11 @@ model = Arduino::Library::Model.from(properties_file)
 model.name #=> 'AudioZero'
 ```
 
-### Presenters
+#### Presenters
 
 Presenters are there to convert to and from a particular format.
 
-#### `.properties` Presenter
+##### `.properties` Presenter
 
 ```ruby
 props = Arduino::Library::Presenters::Properties.new(model).present

data/lib/arduino/library.rb

@@ -21,7 +21,7 @@ require 'arduino/library/types'
 require 'arduino/library/model'
 require 'arduino/library/database'
 require 'arduino/library/default_database'
-require 'arduino/library/resolver'
+require 'arduino/library/finder'
 require 'arduino/library/instance_methods'
 
 module Arduino

data/lib/arduino/library/default_database.rb

@@ -12,24 +12,34 @@ module Arduino
       class << self
         attr_accessor :library_index_path,
                       :library_path,
-                      :library_index_url
+                      :library_index_url,
+                      :url_size_cache
 
         def instance
           @default ||= self.send(:new)
         end
+
+        def reload!
+          instance.reload!
+        end
+
+        def assign_defaults
+          self.url_size_cache     ||= {}
+          self.library_index_path ||= DEFAULT_ARDUINO_LIBRARY_INDEX_PATH
+          self.library_index_url  ||= DEFAULT_ARDUINO_LIBRARY_INDEX_URL
+          self.library_path       ||= DEFAULT_ARDUINO_LIBRARY_PATH
+        end
       end
 
-      self.library_index_path ||= DEFAULT_ARDUINO_LIBRARY_INDEX_PATH
-      self.library_index_url  ||= DEFAULT_ARDUINO_LIBRARY_INDEX_URL
-      self.library_path       ||= DEFAULT_ARDUINO_LIBRARY_PATH
+      self.assign_defaults
 
       attr_accessor :url, :path
 
       def initialize
-        setup
+        reload!
       end
 
-      def setup
+      def reload!
         self.url  = self.class.library_index_url
         self.path = self.class.library_index_path
 
@@ -44,17 +54,26 @@ module Arduino
 
       def download_if_needed!
         if File.exist?(path)
-          resp        = HTTParty.head(url)
-          remote_size = resp['content-length'].to_i
+          remote_size = get_remote_size(url)
           local_size  = File.size(path)
-          debug("remote: #{remote_size}, local #{local_size}")
+          debug("remote size: #{remote_size}, local size: #{local_size}")
           return if remote_size == local_size
           backup_previous_library(path)
         end
-
         download(url, path)
       end
 
+      def get_remote_size(url)
+        with_caching(url) do
+          resp = HTTParty.head(url)
+          resp['content-length'].to_i
+        end
+      end
+
+      def with_caching(url, &_block)
+        @cache ||= self.class.url_size_cache
+        @cache[url] ||= yield
+      end
     end
   end
 end

data/lib/arduino/library/{resolver.rb → finder.rb}

@@ -1,28 +1,34 @@
-require 'arduino/library'
-require 'arduino/library/instance_methods'
-require 'arduino/library/model'
+require_relative 'instance_methods'
+require_relative 'model'
 
 module Arduino
   module Library
-    # This method is used internally by the Model class's #from method.
-    module Resolver
+    # The goal of this class is to identify a *single* library
+    # complete with all the metadata, in particular URL, so that
+    # the library can be installed.
+    #
+    # We accept partial information about the library, and construct
+    # query based this information. If multiple entries returned,
+    # but for the same library, the latest version is returned.
+    module Finder
       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.
+        # Finds a given model with only partial data by
+        # searching in the Ardiuino Database.
         #
-        #      model = Arduino::Library::Resolver.resolve({ name: 'AudioZero'} )
+        #      model = Arduino::Library::Finder.find({ 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)
+        # @return [Model] a found model with #url provided, if found, nil otherwise.
+        def find(model)
           raise ArgumentError, 'Model argument is required' unless model
+
           model = Model.from(model) unless model.is_a?(Model)
-          return model if model && model.url
+          return model unless model.partial?
 
           query = construct_query(model)
           return nil if query.empty?

data/lib/arduino/library/instance_methods.rb

@@ -2,6 +2,9 @@ require 'arduino/library'
 
 module Arduino
   module Library
+    # These are the DSL methods that can be imported by requiring
+    # 'arduino/library/include'
+    #
     module InstanceMethods
       # @param [String] file_or_url — either a local file, or URL, can be gzipped
       def db_from(file_or_url)

data/lib/arduino/library/model.rb

@@ -1,7 +1,7 @@
 require_relative 'types'
 require_relative 'utilities'
 require_relative 'instance_methods'
-require_relative 'resolver'
+require_relative 'finder'
 require 'json'
 
 module Arduino
@@ -18,6 +18,8 @@ module Arduino
         self.attribute field, eval(type)
       end
 
+      SEARCHABLE_FIELDS = %i(name archiveFileName checksum)
+
       # Instance Methods
 
       # Convert a version such as '1.44.3' into a number '1044003' for easy
@@ -33,6 +35,11 @@ module Arduino
         0
       end
 
+      # @returns true if the library has enough data to be searched in the db
+      def partial?
+        self.url.nil? && SEARCHABLE_FIELDS.any?{ |field| self.send(field) }
+      end
+
       def <=>(another)
         self.version_to_i <=> another.version_to_i
       end
@@ -99,7 +106,7 @@ module Arduino
         #   ends
         #
         # @return [Model | Array<Model> ] — array for search, otherwise a model
-        def from(source = nil, **opts)
+        def from(source = nil, ** opts)
           model = case source
                     when Hash
                       from_hash(source)
@@ -114,11 +121,21 @@ module Arduino
                         end
                       end
                     when NilClass
-                      if opts && opts[:name] && opts[:version]
-                        search(**opts)
+                      if opts
+                        if SEARCHABLE_FIELDS.any?{ |field| opts[field] }
+                          results = search(**opts)
+                          raise "Too many items matched — #{results.size}" if results.size > 1
+                          results ? results.first : nil
+                        else
+                          from_hash(opts)
+                        end
                       end
                   end
-          model ? Resolver.resolve(model) : model
+          if model&.partial?
+            Finder.find(model)
+          else
+            model
+          end
         end
       end
     end

data/lib/arduino/library/utilities.rb

@@ -21,19 +21,7 @@ module Arduino
       end
 
       def backup_previous_library(path)
-        debug "backup previous library: #{path.bold.green}"
-        new_name = nil
-        index    = 0
-
-        loop do
-          index += 1
-
-          new_name = "#{path}.#{index}"
-          break unless File.exist?(new_name)
-          debug "file #{new_name.bold.green} exists, next..."
-          raise 'Too many backup versions created, delete some first' if index > 20
-        end
-
+        new_name = path + ".#{short_time}"
         debug "moving #{path.bold.green}", "to #{new_name.bold.blue}"
         FileUtils.move(path, new_name)
       end
@@ -49,6 +37,10 @@ module Arduino
       def debug(*msgs)
         puts "\n" + msgs.join("\n") if ENV['DEBUG']
       end
+
+      def short_time(time = Time.now)
+        time.strftime('%Y%m%d-%H%M%S')
+      end
     end
   end
 end

data/lib/arduino/library/version.rb

@@ -1,8 +1,8 @@
 module Arduino
   module Library
-    VERSION = '0.4.1'
+    VERSION = '0.5.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.
+    This library provides a convenient ruby API for representation of an Arduino Library specification, including field and type validation, reading and writing the library.properties file, as well as downloading the official database of Arduino libraries, and offering a highly advanced searching functionality. This gem only offers Ruby API, but for command line usage please checkout the gem called "arli" — Arduino Library Dependency Manager that uses this library behind the scenes.
     eof
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arduino-library
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-11-20 00:00:00.000000000 Z
+date: 2017-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -164,10 +164,14 @@ dependencies:
     - - ">="
       - !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
-  by Arli — Arduino Installer CLI toolkit.\n"
+description: '    This library provides a convenient ruby API for representation of
+  an Arduino Library specification, including field and type validation, reading and
+  writing the library.properties file, as well as downloading the official database
+  of Arduino libraries, and offering a highly advanced searching functionality. This
+  gem only offers Ruby API, but for command line usage please checkout the gem called
+  "arli" — Arduino Library Dependency Manager that uses this library behind the scenes.
+
+'
 email:
 - kigster@gmail.com
 executables: []
@@ -187,11 +191,11 @@ files:
 - lib/arduino/library.rb
 - lib/arduino/library/database.rb
 - lib/arduino/library/default_database.rb
+- lib/arduino/library/finder.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
@@ -218,8 +222,10 @@ rubyforge_project:
 rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
-summary: 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.
+summary: This library provides a convenient ruby API for representation of an Arduino
+  Library specification, including field and type validation, reading and writing
+  the library.properties file, as well as downloading the official database of Arduino
+  libraries, and offering a highly advanced searching functionality. This gem only
+  offers Ruby API, but for command line usage please checkout the gem called "arli"
+  — Arduino Library Dependency Manager that uses this library behind the scenes.
 test_files: []