lino 2.2.0.pre.1 → 2.2.0.pre.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6b8d73d1b83fd4e09bd2cd61bcc0b0717bb14c43976688dbe26d7b84037f725
-  data.tar.gz: b1e0ee813a1300a0935a78eaa224677ec60d36181a573e3f4a0ec0e9fb426c61
+  metadata.gz: 9aefe3408616b3ae2841a469c5968f05a3d93f069b481ab3a311b37c5c99a19c
+  data.tar.gz: 36aab763064d14623437733908fdf4dcc1662431aa74ef5b296d8966799e6713
 SHA512:
-  metadata.gz: e78ac95f2c066ca9de9b1b04aceae7ab7ed0a744df486558414abfb8bf725f3bb3a9f37c53220fbd68b7a5bbb2ec9d0eb98da2e40d08943692ac07a7799f0a07
-  data.tar.gz: 1697191e1593ceef0785913ec5091ba06cad2af156ba97db7196157da9bf017cfc710d434b71012a44b3470c059669a86f06b1e5fdb865593437ab89a4d662dc
+  metadata.gz: a0492eb20f00aa07778fe583f1ae8e59516b2ca15a745a5c1f754401db2c6ab5c16f6ee5804b0517c434180a4dab376d499c6d881e7dac1db9a6433e2e6b8aa1
+  data.tar.gz: d3d77fe67e292480d87d323887ecd93292149ab7cb3a510b32c9accd721d3c465b8a12cfa7b84c8ad9b2a8310c5702efc39fb91c19a787a1a1d2e299061701be

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lino (2.2.0.pre.1)
+    lino (2.2.0.pre.6)
       hamster (~> 3.0)
       open4 (~> 1.3)
 

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)
@@ -95,6 +97,8 @@ module Lino
     end
 
     def with_arguments(arguments)
+      return self if missing?(arguments)
+
       arguments.inject(self) { |s, argument| s.with_argument(argument) }
     end
 
@@ -109,6 +113,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)
@@ -21,7 +38,15 @@ module Lino
     end
 
     def with_flag(flag)
+      return self if missing?(flag)
+
       with(options: @options.add({ components: [flag] }))
     end
+
+    def with_flags(flags)
+      return self if missing?(flags)
+
+      flags.inject(self) { |s, flag| s.with_flag(flag) }
+    end
   end
 end

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.1'
+  VERSION = '2.2.0.pre.6'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lino
 version: !ruby/object:Gem::Version
-  version: 2.2.0.pre.1
+  version: 2.2.0.pre.6
 platform: ruby
 authors:
 - Toby Clemson
@@ -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