arli 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 233ae21fdec4ad9e4f6fd73c632dc632d626a5df
-  data.tar.gz: 4db04f61697a98c6288a81d5179bfc62fccf79ee
+  metadata.gz: 716b1c4d72d5a8d569c26ca80f0bd0c86d260414
+  data.tar.gz: ccb615215a6b8ecbcf129f9a2feb94a190a1c98b
 SHA512:
-  metadata.gz: ca67abe8ac90302ffdf49aedfc0c3a33f999f5bc28721aa027e7f9ad104a29cbadff9bcc4ace2fed7bbb2fccf0fc6aada19f38f4096f597599c4188ed8eaf950
-  data.tar.gz: 1635be7126e6515ad602c68388d0e660b2536a12a5d197621c057fcec48f0641a477224cbd87072ea673c9b51c2692a9b9153e2dec1fbc6465c02816dfbb7c66
+  metadata.gz: e403f0d96a42d0d21a37e5da72e882e497c045f0139ae210b7a83f9a2ec4cf63ddda3e359055daf8379f7869b500f25e302fe5791e88d83b50bbfdff8d91d48c
+  data.tar.gz: 7444ed04113582cf6abe9bcbc54bb1141803469b7e731ab2af575f94b5f83faa1c03e8e6cc0e6b7092b03acd66a1d9a4e53aa5378c6c563b6471b851542863e2

data/.rake_tasks~

@@ -0,0 +1,8 @@
+build
+clean
+clobber
+doc
+install
+install:local
+release[remote]
+spec

data/README.md

@@ -12,29 +12,19 @@ a YAML formatted file declaring dependencies, as follows:
 # vi:syntax=yaml
 version: 1.0.0
 dependencies:
-  - name: ESP8266WiFi
-    version: '1.0'
-    url: https://github.com/esp8266/Arduino
   - name: Time
   - name: "Adafruit GFX Library"
   - name: SimpleTimer
     url: https://github.com/jfturcot/SimpleTimer
 ```
 
-The libraries may be specified with a name and url only, OR they can be specified by name (and optionally version) — as long as this is one of the standard libraries documented in the [Arduino official library database](http://downloads.arduino.cc/libraries/library_index.json.gz) JSON file.
+The libraries may be specified with a name and url only (in which case the URL will be used to install it), OR a library can be specified by name (and optionally version). In this case, it will be searched among the standard library index provided by the [Arduino official library database](http://downloads.arduino.cc/libraries/library_index.json.gz) JSON file.
 
-
-Basically a simple pairing of a library/project name 
-(which also happens to be the local directory it's cloned into) 
-and a remote URL.
-
-The gem was created to fill the need of managing many external
-libraries for an Arduino projects in a consistent way. Arli's 
-API was loosely inspired by Bundler.
+The gem was created to fill the need of slightly more complex Arduino projects that DO NOT use Arduino IDE, and instead use other technologies, such as `ArduinoCmake`  in managing many Arduino libraries  in a consistent way. Arli's API was loosely inspired by Bundler.
 
 ## Installation
 
-Install the gem globally like this:
+Install the `arli` ruby gem as follows:
 
 ```bash
 # if using rbenv, or rvm; otherwise you may need to prefix 
@@ -47,9 +37,8 @@ $ gem install arli
 Run `arli --help` for more information:
 
 ```bash
-
-Usage:
-    arli [options] [ command [options]  ]
+age:
+    arli [ options ] [ command [ options ]  ]
 
     -D, --debug            Print debugging info.
     -t, --trace            Print exception stack traces.
@@ -58,19 +47,80 @@ Usage:
     -h, --help             prints this help
 
 Available Commands:
-    install      : installs libraries defined in Arlifile
-    search       : Flexible Search of the Arduino Library Database
+    install      — installs libraries defined in Arlifile
+    search       — Flexible Search of the Arduino Library Database
 
-See arli <command> --help for more information on a specific command.
+See arli command --help for more information on a specific command.
 ```
 
 #### Install Command
 
-Use this command to install libraries for the first time. 
+Use this command to install or re-install libraries.
+
+You can specify libraries in the `Arlifile` by providing either just the `name:` (and posibly `version`) — the name must match exactly a library in the Arduino standard database. Alternatively, your can pass `archiveFileName`, `checksum` — which all uniquely identify a library in the database.
+
+Sometimes a library will not be in the database, in which case just provide the name and `url` field for it. The URL can either be a git URL, or a downloadable ZIP file.
+
+
+##### Automatic Folder Name Correction
+
+Arli has an build-in action that's invoked during installation of the libraries: once the library is upacked into a folder (either using git or unzip), it's contents is searched for source files. The name of the directory is then compared to the files found, and in some cases Arli will rename the library folder to match the source files.
+
+For example, 'Adafruit GFX Library' is the proper name of the corresponding library, and it's ZIP archive will unpack into `Adafruit_GFX_Library-1.4.3` folder.  Arli will first remove the version number, and move it to `Adafruit_GFX_Library`, but then it will detect that the file inside is `Adafruit_GFX.h`, and so the top-level folder gets renamed to `Adafruit_GFX` as well. This is an audacious attempt to make sense of the chaos that is the Arduino Library world.
+
+##### An Example
+
+Here is the `arli install` command inside CMake-based project to build a [Wall Clock using Arduino](https://github.com/kigster/wallclock-arduino). This project has the following `Arlifile`:
+
+```yaml
+# vi:syntax=yaml
+---
+dependencies:
+- name: "Adafruit GFX Library"
+- name: "DS1307RTC"
+- name: "Adafruit LED Backpack Library"
+- name: "Adafruit Unified Sensor"
+- name: "DHT sensor library"
+- name: "OneButton"
+- name: SimpleTimer
+  url: https://github.com/jfturcot/SimpleTimer.git
+- name: Time
+```
+
+You can see that most libraries are specified by name, except one (SimpleTimer) is specified together with the URL, which will be used to `git clone` the library.
+
+So let's specify where our libraries live, and run `arli install` inside that project:
+
+```bash
+❯ export ARDUINO_CUSTOM_LIBRARY_PATH=~/Documents/Arduino/libraries/
+❯ cd skethes/wallclock-arduino
+❯ arli install
+Adafruit GFX Library (1.2.2) ....... (Adafruit_GFX)
+DS1307RTC (1.4.0) ......
+Adafruit LED Backpack Library (1.1.6) ....... (Adafruit_LEDBackpack)
+Adafruit Unified Sensor (1.0.2) ....... (Adafruit_Sensor)
+DHT sensor library (1.3.0) ....... (DHT)
+OneButton (1.2.0) .......
+SimpleTimer running git clone -v https://github.com/jfturcot/SimpleTimer.git ~/Documents/Arduino/libraries/SimpleTimer 2>&1 .
+s (1.5.0) ......
+```
+
+Now, we can inspect the library folder and observe that all of the specified libraries have been installed, and into correct folders:
+
+```bash
+❯ ls -1 ~/Documents/Arduino/libraries
+Adafruit_GFX
+DS1307RTC
+Adafruit_LEDBackpack
+Adafruit_Sensor 
+DHT
+OneButton
+SimpleTimer
+Time
+```
+
+Below is the complete help for the install command:
 
-NOTE: unless you pass `-e` flag, install command falls back to `update` if
-the target folder already exists.  With `-e` flag, installer aborts if the 
-target library already exists.
 
 ```bash
 Description:
@@ -80,10 +130,10 @@ Usage:
     arli install [options]
 
 Command Options
-    -l, --libs PATH        Local folder where libraries are installed
+    -l, --libraries PATH   Local folder where libraries are installed
                            Defaults to ~/Dropbox/Workspace/oss/arduino/libraries
 
-    -p, --arli-path PATH   Folder where Arlifile is located,
+    -a, --arli-path PATH   Folder where Arlifile is located,
                            Defaults to the current directory.
 
     -e, --if-exists ACTION If a library folder already exists, by default
@@ -97,17 +147,58 @@ Command Options
     -h, --help             prints this help
 ```
 
-
 #### Search Command
 
-To search Arduino library database, you can use the search command:
+To search Arduino library database, you can use the search command.
+
+You can search in two ways:
+
+ 1. simple name match
+ 2. complex arbitrary attribute match, that supports regular expressions and more.
+
+`arli search AudioZero` does a simple search by name, and returns 3 results:
+
+```bash
+❯ arli search AudioZero
+AudioZero (1.0.1), by Arduino
+AudioZero (1.0.0), by Arduino
+AudioZero (1.1.1), by Arduino
+
+Total matches: 3
+```
+
+The search argument can also be a ruby-syntaxed expression, that (if you know ruby)  is actually `eval`-ed into the method parameters. Here are a few examples:
+
+
+
+You can also use regular expressions, and set maximum number of results printed by the `-m MAX` flag.
+
+```bash
+❯ arli search 'name: /adafruit/i' -m 0
+Adafruit ADS1X15 (1.0.0), by Adafruit
+Adafruit ADXL345 (1.0.0), by Adafruit
+Adafruit AM2315 (1.0.0), by Adafruit
+Adafruit AM2315 (1.0.1), by Adafruit
+.....
+WEMOS Matrix Compatible With Adafruit GFX Library (1.0.0), by Thomas O Fredericks
+WEMOS Matrix Compatible With Adafruit GFX Library (1.1.0), by Thomas O Fredericks
+Adafruit SGP30 Sensor (1.0.0), by Adafruit
+
+Total matches: 352
+```
+
+With `-m 0` flag, we disabled the default search limit of 100, and got all of the libraries that have the word "adafruit" in their name. We could have used `version:`, or `author`, or `website`, or even `url` and `archiveFileName` fields. For complete description of available library attributes, please see the official definition of the [`library.properties`](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#library-metadata) file.
+
+A detailed description of the complete search functionality is documented in the library that provides it — [arduino-library](https://github.com/kigster/arduino-library#using-search). Arli uses `arduino-library` gem behind the scenes to search, and lookup libraries.
+
+Below is the help screen for the search command:
 
 ```bash
 Description:
     Flexible Search of the Arduino Library Database
 
 Usage:
-    arli search <query> [options]
+    arli search [ name-match | expression ] [options]
 
 Command Options
     -d FILE/URL,           a JSON file name, or a URL that contains the index
@@ -121,8 +212,9 @@ Command Options
     -h, --help             prints this help
 
 Example:
-    arli search 'name: /AudioZero/, version: "1.0.1"'
-I```
+     arli search 'name: /AudioZero/, version: "1.0.1"'
+```
+
 
 ## Development
 

data/Rakefile

@@ -1,6 +1,28 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+def shell(*args)
+  puts "running: #{args.join(' ')}"
+  system(args.join(' '))
+end
+
+task :permissions do 
+  shell('rm -rf pkg/ tmp/' )
+  shell("chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*")
+  shell("find . -type d -exec chmod o+x,g+x {} \\;")
+end
+
+task :build => :permissions
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = %w(lib/**/*.rb exe/*.rb - README.md LICENSE)
+  t.options.unshift('--title','"Sym – Symmetric Key Encryption for Your Data"')
+  t.after = ->() { exec('open doc/index.html') }
+end
 
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+

data/arli.gemspec

@@ -28,18 +28,21 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'arduino-library', '~> 0.4.1'
+  spec.add_dependency 'arduino-library', '~> 0.5.1'
   spec.add_dependency 'colored2'
   spec.add_dependency 'hashie'
   spec.add_dependency 'dry-types'
   spec.add_dependency 'dry-struct'
+  spec.add_dependency 'dry-configurable'
   spec.add_dependency 'awesome_print'
   spec.add_dependency 'archive-zip'
 
 
+  spec.add_development_dependency 'yard'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'bundler', '~> 1.15'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rspec-its'
+  spec.add_development_dependency 'aruba'
 end

data/exe/arli

@@ -1,8 +1,6 @@
 #!/usr/bin/env ruby
 
-require 'arli'
+require 'arli/cli/runner'
 
-Arli::CLI.new.tap do |cli|
-  cli.parse
-end
+Arli::CLI::Runner.new(ARGV.dup).execute!
 

data/lib/arli.rb

@@ -1,42 +1,40 @@
-require 'forwardable'
-require 'logger'
 require 'arduino/library'
 
 require 'arli/version'
+require 'arli/extensions'
 require 'arli/errors'
-require 'arli/logger'
-require 'arli/config'
+require 'arli/configuration'
+require 'arli/library'
+require 'arli/commands'
 
 module Arli
+  @config = ::Arli::Configuration.config
 
   class << self
     attr_accessor :config
-  end
-
-  self.config = ::Arli::Config
-
-  class << self
-    extend Forwardable
-    def_delegators :@config, *::Arli::Config::PARAMS
 
     def configure(&_block)
       yield(self.config)
     end
 
     def debug?
-      self.debug
+      self.config.debug
     end
-  end
-end
 
-Arli.configure do |config|
-  config.library_path       = ::Arduino::Library::DefaultDatabase.library_path
-  config.library_index_path = ::Arduino::Library::DefaultDatabase.library_index_path
-  config.library_index_url  = ::Arduino::Library::DefaultDatabase.library_index_url
-  config.logger             = ::Logger.new(STDOUT, level: :info)
-  config.debug              = ENV['ARLI_DEBUG'] || false
+    def library_path
+      self.config.libraries.path
+    end
+
+    def default_library_path
+      dehomify_path(self.config.libraries.path)
+    end
+
+    def dehomify_path(absolute_path)
+      absolute_path.gsub(%r(#{ENV['HOME']}), '~')
+    end
+  end
 end
 
 require 'arli/arli_file'
-require 'arli/installer'
+require 'arli/actions'
 require 'arli/cli'

data/lib/arli/actions.rb

@@ -0,0 +1,19 @@
+module Arli
+  module Actions
+    class << self
+      attr_accessor :actions
+
+      def action(name)
+        self.actions[name]
+      end
+    end
+  end
+end
+
+Arli::Actions.actions = {}
+
+require_relative 'actions/action'
+require_relative 'actions/zip_file'
+require_relative 'actions/git_repo'
+require_relative 'actions/dir_name'
+require_relative 'actions/backup'

data/lib/arli/actions/action.rb

@@ -0,0 +1,32 @@
+require_relative '../output'
+
+module Arli
+  module Actions
+    # Represents an abstract action related to the library
+    class Action
+      include Arli::Output
+
+      extend Forwardable
+      def_delegators :@library, :exists?, :path, :dir, :libraries_home
+
+      class << self
+        def inherited(klazz)
+          action_name = klazz.name.gsub(/.*::/, '').underscore.to_sym
+          ::Arli::Actions.actions[action_name] = klazz
+        end
+      end
+
+      attr_accessor :library, :config
+
+      def initialize(library, config: Arli.config)
+        self.library = library
+        self.config  = config
+      end
+
+      def act(**_opts)
+        raise 'Abstract method #act called on Action'
+      end
+
+    end
+  end
+end

data/lib/arli/actions/backup.rb

@@ -0,0 +1,30 @@
+require_relative 'action'
+
+module Arli
+  module Actions
+    class Backup < Action
+
+      def act(**options)
+        return false unless exists?
+
+        if backup_action.abort
+          raise Arli::Errors::LibraryAlreadyExists, path
+        elsif backup_action.backup
+          FileUtils.mv(path, backup_library_path)
+        elsif backup_action.overwrite
+          library.rm_rf!
+        end
+      end
+
+      def backup_action
+        config.install.if_exists
+      end
+
+      private
+
+      def backup_library_path
+        path + ".#{Time.now.strftime('%Y%m%d%H%M%S')}"
+      end
+    end
+  end
+end