lino 2.2.0.pre.3 → 2.4.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cee8c3683bbc6d1aa1088315b0271fe95850ab79a815ca239230dc354d2296b1
-  data.tar.gz: fe01bf1be359a9d52be65af820228c6859592a60c107a533f330c5bbf06bd34f
+  metadata.gz: c8e3b24a8c6e75d46c7b35d031a103086e6581ddf565fcd6b29f5899a40b85e0
+  data.tar.gz: 58e3a47d18114356c513de7cfcdef552faad11ad738d88445297cfb4c48b8a12
 SHA512:
-  metadata.gz: 002a1329d9ed0d050827c159e152ac6752e3e5d46ba225ffdac40accf9765189ce7c83fb9ef26c1ad876ecb018b3e24f50eeff60104b51cb8b342fb2b1d7dc3d
-  data.tar.gz: 01d1c73ed195be4dcdc15e0365ca8865b6756133be2f95c4ef6a6f6824819c045720502c9a9e597ffe25244099a72435aae2f16e940a950bbae8d1f4f3c57094
+  metadata.gz: bf1f78f7538dc573f9ce6d2bfd77c98c8cec8fc2922a81249d89ff903b89d1ace6c999b28aa9d8c2ce259029053b849eee422b450a208cdd40a7ba0c18bade97
+  data.tar.gz: ff587023b46e059be16b08c6b113d396f618621edd9211aff9ca33d7413c5afa164b6e5f5206308a1b675b339cea3e4f34a6e540288000d7a161dc65e94f30ea

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lino (2.2.0.pre.3)
+    lino (2.4.0.pre.1)
       hamster (~> 3.0)
       open4 (~> 1.3)
 
@@ -133,4 +133,4 @@ DEPENDENCIES
   simplecov (~> 0.16)
 
 BUNDLED WITH
-   2.2.15
+   2.2.16

data/README.md

@@ -41,10 +41,13 @@ command_line.execute
 ### `Lino::CommandLineBuilder`
 
 The `CommandLineBuilder` allows a number of different styles of commands to be 
-built:
+built.
+
+#### Flags
+
+Flags can be added with `#with_flag`:
 
 ```ruby
-# commands with flags
 Lino::CommandLineBuilder.for_command('ls')
     .with_flag('-l')
     .with_flag('-a')
@@ -52,8 +55,24 @@ Lino::CommandLineBuilder.for_command('ls')
     .to_s
 
 # => ls -l -a
+```
+
+or `#with_flags`:
+
+```ruby
+Lino::CommandLineBuilder.for_command('ls')
+    .with_flags(%w[-l -a])
+    .build
+    .to_s
+
+# => ls -l -a
+```
+
+#### Options
+
+Options with values can be added with `#with_option`:
 
-# commands with options
+```ruby
 Lino::CommandLineBuilder.for_command('gpg')
     .with_option('--recipient', 'tobyclemson@gmail.com')
     .with_option('--sign', './doc.txt')
@@ -61,16 +80,57 @@ Lino::CommandLineBuilder.for_command('gpg')
     .to_s
 
 # => gpg --recipient tobyclemson@gmail.com --sign ./doc.txt
+```
+
+or `#with_options`, either as a hash:
+
+```ruby
+Lino::CommandLineBuilder.for_command('gpg')
+    .with_options({
+      '--recipient' => 'tobyclemson@gmail.com',
+      '--sign' => './doc.txt'
+    })
+    .build
+    .to_s
 
-# commands with an option repeated multiple times
+# => gpg --recipient tobyclemson@gmail.com --sign ./doc.txt
+```
+
+or as an array:
+
+```ruby
+Lino::CommandLineBuilder.for_command('gpg')
+    .with_options(
+      [
+        { option: '--recipient', value: 'tobyclemson@gmail.com' },
+        { option: '--sign', value: './doc.txt' }
+      ]
+    )
+    .build
+    .to_s
+
+# => gpg --recipient tobyclemson@gmail.com --sign ./doc.txt
+```
+
+Some commands allow options to be repeated:
+
+```ruby
 Lino::CommandLineBuilder.for_command('example.sh')
     .with_repeated_option('--opt', ['file1.txt', nil, '', 'file2.txt'])
     .build
     .to_s
 
 # => example.sh --opt file1.txt --opt file2.txt
+```
+
+> Note: `lino` ignores `nil` or empty option values in the resulting command 
+>       line. 
 
-# commands with arguments 
+#### Arguments
+
+Arguments can be added using `#with_argument`:
+
+```ruby 
 Lino::CommandLineBuilder.for_command('diff')
     .with_argument('./file1.txt')
     .with_argument('./file2.txt')
@@ -78,16 +138,28 @@ Lino::CommandLineBuilder.for_command('diff')
     .to_s
 
 # => diff ./file1.txt ./file2.txt
+```
 
-# ... or alternatively
+or `#with_arguments`, as an array:
+
+```ruby
 Lino::CommandLineBuilder.for_command('diff')
     .with_arguments(['./file1.txt', nil, '', './file2.txt'])
     .build
     .to_s
 
 # => diff ./file1.txt ./file2.txt
+```
+
+> Note: `lino` ignores `nil` or empty argument values in the resulting command 
+>        line.
+
+#### Option Separators
 
-# commands with custom option separator
+By default, `lino` separates option values from the option by a space. This
+can be overridden globally using `#with_option_separator`:
+
+```ruby
 Lino::CommandLineBuilder.for_command('java')
     .with_option_separator(':')
     .with_option('-splash', './images/splash.jpg')
@@ -96,44 +168,132 @@ Lino::CommandLineBuilder.for_command('java')
     .to_s
 
 # => java -splash:./images/splash.jpg ./application.jar
+```
+
+The option separator can be overridden on an option by option basis:
+
+```ruby
+Lino::CommandLineBuilder.for_command('java')
+    .with_option('-splash', './images/splash.jpg', separator: ':')
+    .with_argument('./application.jar')
+    .build
+    .to_s
+
+# => java -splash:./images/splash.jpg ./application.jar
+```
+
+> Note: `#with_options` supports separator overriding when the options are
+>       passed as an array of hashes and a `separator` key is included in the 
+>       hash.
+
+> Note: `#with_repeated_option` also supports the `separator` named parameter.
+
+> Note: option specific separators take precedence over the global option 
+>       separator 
+
+#### Option Quoting
+
+By default, `lino` does not quote option values. This can be overridden 
+globally using `#with_option_quoting`:
+
+```ruby
+Lino::CommandLineBuilder.for_command('gpg')
+    .with_option_quoting('"')
+    .with_option('--sign', 'some file.txt')
+    .build
+    .to_s
+
+# => gpg --sign "some file.txt"
+```
+
+The option quoting can be overridden on an option by option basis:
+
+```ruby
+Lino::CommandLineBuilder.for_command('java')
+    .with_option('-splash', './images/splash.jpg', quoting: '"')
+    .with_argument('./application.jar')
+    .build
+    .to_s
+
+# => java -splash "./images/splash.jpg" ./application.jar
+```
+
+> Note: `#with_options` supports quoting overriding when the options are
+>       passed as an array of hashes and a `quoting` key is included in the 
+>       hash.
+
+> Note: `#with_repeated_option` also supports the `quoting` named parameter.
+
+> Note: option specific quoting take precedence over the global option 
+>       quoting 
+
+#### Subcommands
+
+Subcommands can be added using `#with_subcommand`:
 
-# commands using a subcommand style
+```ruby
 Lino::CommandLineBuilder.for_command('git')
     .with_flag('--no-pager')
-    .with_subcommand('log') do |sub|
-      sub.with_option('--since', '2016-01-01')
-    end
+    .with_subcommand('log')
     .build
     .to_s
 
-# => git --no-pager log --since 2016-01-01
+# => git --no-pager log
+```
 
-# commands with multiple levels of subcommand
+Multi-level subcommands can be added using multiple `#with_subcommand` 
+invocations:
+
+```ruby
 Lino::CommandLineBuilder.for_command('gcloud')
     .with_subcommand('sql')
     .with_subcommand('instances')
     .with_subcommand('set-root-password')
-    .with_subcommand('some-database') do |sub|
-      sub.with_option('--password', 'super-secure')
-    end
+    .with_subcommand('some-database')
     .build
     .to_s
-    
-# => gcloud sql instances set-root-password some-database --password super-secure
 
-# ... or alternatively
+# => gcloud sql instances set-root-password some-database
+```
+
+or using `#with_subcommands`:
+     
+```ruby
 Lino::CommandLineBuilder.for_command('gcloud')
     .with_subcommands(
       %w[sql instances set-root-password some-database]
-    ) do |sub|
-      sub.with_option('--password', 'super-secure')
-    end
+    )
     .build
     .to_s
     
-# => gcloud sql instances set-root-password some-database --password super-secure
+# => gcloud sql instances set-root-password some-database
+```
+
+Subcommands also support options via `#with_flag`, `#with_flags`, 
+`#with_option`, `#with_options` and `#with_repeated_option` just like commands,
+via a block, for example: 
+
+```ruby
+Lino::CommandLineBuilder.for_command('git')
+    .with_flag('--no-pager')
+    .with_subcommand('log') do |sub|
+      sub.with_option('--since', '2016-01-01')
+    end
+    .build
+    .to_s
+
+# => git --no-pager log --since 2016-01-01
+```
+
+> Note: `#with_subcommands` also supports a block, which applies in the context
+>       of the last subcommand in the passed array.
+
+#### Environment Variables
+
+Command lines can be prefixed with environment variables using 
+`#with_environment_variable`:
   
-# commands controlled by environment variables
+```ruby
 Lino::CommandLineBuilder.for_command('node')
     .with_environment_variable('PORT', '3030')
     .with_environment_variable('LOG_LEVEL', 'debug')
@@ -142,31 +302,73 @@ Lino::CommandLineBuilder.for_command('node')
     .to_s
     
 # => PORT=3030 LOG_LEVEL=debug node ./server.js
+```
+
+or `#with_environment_variables`, either as a hash:
+
+```ruby
+Lino::CommandLineBuilder.for_command('node')
+    .with_environment_variables({
+      'PORT' => '3030',
+      'LOG_LEVEL' => 'debug'
+    })
+    .build
+    .to_s
+    
+# => PORT=3030 LOG_LEVEL=debug node ./server.js
+```
+
+or as an array:
+
+```ruby
+Lino::CommandLineBuilder.for_command('node')
+    .with_environment_variables(
+      [
+        { name: 'PORT', value: '3030' },
+        { name: 'LOG_LEVEL', value: 'debug' }
+      ]
+    )
+    .build
+    .to_s
+    
+# => PORT=3030 LOG_LEVEL=debug node ./server.js
+```
+
+#### Option Placement
+
+By default, `lino` places top-level options after the command, before all 
+subcommands and arguments.
 
-# note: by default, options are placed after the command, before all subcommands
-#       and arguments
+This is equivalent to calling `#with_options_after_command`:
 
-# this can be expressed explicitly
+```ruby
 Lino::CommandLineBuilder.for_command('gcloud')
     .with_options_after_command
     .with_option('--password', 'super-secure')
-    .with_subcommands(%w[sql instances set-root-password some-database])
+    .with_subcommands(%w[sql instances set-root-password])
     .build
     .to_s
 
-# => gcloud --password super-secure sql instances set-root-password some-database
+# => gcloud --password super-secure sql instances set-root-password
+```
+
+Alternatively, top-level options can be placed after all subcommands using
+`#with_options_after_subcommands`:
 
-# options can also come after subcommands
+```ruby
 Lino::CommandLineBuilder.for_command('gcloud')
     .with_options_after_subcommands
     .with_option('--password', 'super-secure')
-    .with_subcommands(%w[sql instances set-root-password some-database])
+    .with_subcommands(%w[sql instances set-root-password])
     .build
     .to_s
 
-# => gcloud sql instances set-root-password some-database --password super-secure
+# => gcloud sql instances set-root-password --password super-secure
+```
+
+or, after all arguments, using `#with_options_after_arguments`:
 
-# options can also come after arguments, although usages of this are rare
+```ruby
 Lino::CommandLineBuilder.for_command('ls')
     .with_options_after_arguments
     .with_flag('-l')
@@ -177,6 +379,59 @@ Lino::CommandLineBuilder.for_command('ls')
 # => ls /some/directory -l
 ```
 
+#### Appliables
+
+Command and subcommand builders both support passing 'appliables' that are
+applied to the builder allowing an operation to be encapsulated in an object.
+
+Given an appliable type:
+
+```ruby
+class AppliableOption
+  def initialize(option, value)
+    @option = option
+    @value = value
+  end
+
+  def apply(builder)
+    builder.with_option(@option, @value)
+  end
+end
+```
+
+an instance of the appliable can be applied using `#with_appliable`:
+
+```ruby
+Lino::CommandLineBuilder.for_command('gpg')
+    .with_appliable(AppliableOption.new('--recipient', 'tobyclemson@gmail.com'))
+    .with_flag('--sign')
+    .with_argument('/some/file.txt')
+    .build
+    .to_s
+
+# => gpg --recipient tobyclemson@gmail.com --sign /some/file.txt 
+```
+
+or multiple with `#with_appliables`:
+
+```ruby
+Lino::CommandLineBuilder.for_command('gpg')
+    .with_appliables([
+      AppliableOption.new('--recipient', 'user@example.com'),
+      AppliableOption.new('--output', '/signed.txt')
+    ])
+    .with_flag('--sign')
+    .with_argument('/file.txt')
+    .build
+    .to_s
+
+# => gpg --recipient user@example.com --output /signed.txt --sign /file.txt 
+```
+
+> Note: an 'appliable' is any object that has an `#apply` method.
+
+> Note: `lino` ignores `nil` or empty appliables in the resulting command line.
+
 ### `Lino::CommandLine`
 
 A `CommandLine` can be executed using the `#execute` method:

data/Rakefile

@@ -16,6 +16,7 @@ task default: %i[
 
 namespace :encryption do
   namespace :passphrase do
+    desc 'Generate encryption passphrase for CI GPG key'
     task :generate do
       File.open('config/secrets/ci/encryption.passphrase', 'w') do |f|
         f.write(SecureRandom.base64(36))
@@ -96,6 +97,7 @@ RakeGithub.define_repository_tasks(
 end
 
 namespace :pipeline do
+  desc 'Prepare CircleCI Pipeline'
   task prepare: %i[
     circle_ci:project:follow
     circle_ci:env_vars:ensure

data/lib/lino/appliables.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'utilities'
+
+module Lino
+  module Appliables
+    include Lino::Utilities
+
+    def with_appliable(appliable)
+      return self if missing?(appliable)
+
+      appliable.apply(self)
+    end
+
+    def with_appliables(appliables)
+      return self if missing?(appliables)
+
+      appliables.inject(self) do |s, appliable|
+        s.with_appliable(appliable)
+      end
+    end
+  end
+end

data/lib/lino/command_line_builder.rb

@@ -5,6 +5,7 @@ require_relative 'utilities'
 require_relative 'command_line'
 require_relative 'subcommand_builder'
 require_relative 'options'
+require_relative 'appliables'
 
 module Lino
   # rubocop:disable Metrics/ClassLength
@@ -20,6 +21,7 @@ module Lino
 
     include Lino::Utilities
     include Lino::Options
+    include Lino::Appliables
 
     class << self
       def for_command(command)
@@ -50,6 +52,8 @@ module Lino
     # rubocop:enable Metrics/ParameterLists
 
     def with_subcommand(subcommand, &block)
+      return self if missing?(subcommand)
+
       with(
         subcommands: @subcommands.add(
           (block || ->(sub) { sub }).call(
@@ -60,6 +64,8 @@ module Lino
     end
 
     def with_subcommands(subcommands, &block)
+      return self if missing?(subcommands)
+
       without_block = subcommands[0...-1]
       with_block = subcommands.last
 
@@ -111,6 +117,17 @@ module Lino
       )
     end
 
+    def with_environment_variables(environment_variables)
+      return self if missing?(environment_variables)
+
+      environment_variables.entries.inject(self) do |s, var|
+        s.with_environment_variable(
+          var.include?(:name) ? var[:name] : var[0],
+          var.include?(:value) ? var[:value] : var[1]
+        )
+      end
+    end
+
     def build
       components = formatted_components
       command_line = SELECTORS[@option_placement]

data/lib/lino/options.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require_relative 'utilities'
+
 module Lino
   module Options
+    include Lino::Utilities
+
     def with_option(option, value, separator: nil, quoting: nil)
       return self if missing?(value)
 
@@ -14,6 +18,19 @@ module Lino
       ))
     end
 
+    def with_options(options)
+      return self if missing?(options)
+
+      options.entries.inject(self) do |s, entry|
+        s.with_option(
+          entry.include?(:option) ? entry[:option] : entry[0],
+          entry.include?(:value) ? entry[:value] : entry[1],
+          separator: (entry.include?(:separator) ? entry[:separator] : nil),
+          quoting: (entry.include?(:quoting) ? entry[:quoting] : nil)
+        )
+      end
+    end
+
     def with_repeated_option(option, values, separator: nil, quoting: nil)
       values.inject(self) do |s, value|
         s.with_option(option, value, separator: separator, quoting: quoting)

data/lib/lino/subcommand_builder.rb

@@ -3,11 +3,13 @@
 require 'hamster'
 require_relative 'utilities'
 require_relative 'options'
+require_relative 'appliables'
 
 module Lino
   class SubcommandBuilder
     include Lino::Utilities
     include Lino::Options
+    include Lino::Appliables
 
     class <<self
       def for_subcommand(subcommand)

data/lib/lino/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lino
-  VERSION = '2.2.0.pre.3'
+  VERSION = '2.4.0.pre.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lino
 version: !ruby/object:Gem::Version
-  version: 2.2.0.pre.3
+  version: 2.4.0.pre.1
 platform: ruby
 authors:
 - Toby Clemson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-04-05 00:00:00.000000000 Z
+date: 2021-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hamster
@@ -222,6 +222,7 @@ files:
 - bin/console
 - bin/setup
 - lib/lino.rb
+- lib/lino/appliables.rb
 - lib/lino/command_line.rb
 - lib/lino/command_line_builder.rb
 - lib/lino/options.rb