opto 1.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 01abb09f30890132075384eb8ff969899b0fb168
+  data.tar.gz: 51d608217ef7b48968d66a75ae2e8515c38c4d9d
+SHA512:
+  metadata.gz: 66121b1275518c5023ee8e2a4633e7835f3cff613c6173bc18debe8a1b29905f0913f13a4b1579e83d46f8fd4f049ebb17a2936497660c3fda1d1c2471446a07
+  data.tar.gz: 89ecd251166c29beeae9bcb96962d7d873215d9f55225e7c6813050fa1b772b400497977289594549a182e51e0098e498887e0a8bd38c0a0b17e0c80c2d66494

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.byebug_history

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+rvm:
+  - 2.0.0-p648
+  - 2.1.8
+  - 2.2.3
+  - 2.3.1
+env:
+  - secure: "bCu1bVzr6SP+gAbMo88GvcHHbhO3LcnJtWp+YuSZ5qW4EHhdBw+DOQeOlzoKHtYhNhptmb/65pZZctRTE6jOOSZzpOUHaeqaqHZpELldkCMu7rE8bXuCV4OfhG0CKWvURS0x5p5F5onEx1a1sjiu+MVEUqktAPDAcdTBNBW1irRwvnSifgjcZRLzfm1aRs1fqzBJpHaAXyD++2GQaWyXDtQsEsc/Eyhmnkac5Y2cTeQiYlDluqBeB885q9K16ruLp2NWx/rnR8RGMP1LSnrye/GEo2mRWOWy1MyIEwNDcVaA6MVDY2GBIQUoXg4PBrZAleVIsO3LzwR4oorFCaSgWxzqYI67g5Kb2zn8fW9Yu5lDcFEJKIHQAwBrlq3n3Mi5it/IxGQDWXQ/2fjBxCwuilvI0WTzOH0m4g8Uf6jHaQLFC6ahdWDjfs6aCzdPpbJls26/r39NIB5k/6ZO29NZkxGBsQ7E7m4wurr7a9ksLODgPOyPiB8/4Txu35Llp+IuJpbshrlkRIMwEIFVWiLi6MZhRBkxaRzlkJQ0bS3RD9W4z9UJyoBujmgXMrv0eHNTGCOC+/4tvrA+pXzJwmFQJA6TnenoDl9hc6o03gyfH/YvmMgrtJLbJ8rGoLRaY8HsQwHWgimpCl1o043kO8/UkhhS7J4wyQXYwqGnA2PC/j0="
+before_install: gem install bundler -v 1.12.5
+cache: bundler
+script: bundle install && bundle exec rspec spec/
+deploy:
+  provider: rubygems
+  api_key: $GEM_TOKEN
+  gem: opto
+  on:
+    tags: true
+    rvm: 2.3.1

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in opto.gemspec
+gemspec
+
+group :development do
+  gem 'byebug', require: false
+  gem 'simplecov', require: false
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Kimmo Lehto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,407 @@
+# Opto
+
+[![Build Status](https://travis-ci.org/kontena/opto.svg?branch=master)](https://travis-ci.org/kontena/opto)
+
+An option parser, built for generating options from YAML based [Kontena](https://github.com/kontena/kontena/) stack
+definition files, but can be just as well used for other things, such as an API input validator.
+
+The values for options can be resolved from files, env-variables, custom interactive prompts, random generators, etc.
+
+The option type handlers can perform validations, such as defining a range or length requirements.
+
+Transformations can be performed on values, such as upcasing strings or removing white space.
+
+Options can have simple conditionals for determining if it needs to be processed or not, an option for defining a database
+password can be processed only if a database has been selected.
+
+Finally the value for the option can be placed to some destination, such as an environment variable or sent to a command.
+
+## Installation
+
+```ruby
+# gem install opto
+
+require 'opto'
+```
+
+## YAML definition examples:
+
+```yaml
+# Enum type
+  remote_driver:
+    type: "enum"
+    required: true
+    label: "Remote Driver"
+    description: "Remote Git and Auth scheme"
+    options:
+      - github
+      - bitbucket
+      - gitlab
+      - gogs
+```
+
+```yaml
+# String validation and transformation
+  foo_username:
+    type: string
+    required: true
+    min_length: 1
+    max_length: 30
+    strip: true   # remove leading / trailing whitespace
+    upcase: true  # make UPCASE
+    env: FOO_USER # read value from ENV variable FOO_USER
+```
+
+```yaml
+# Enum with prettier item descriptions
+  name: foo_os
+    type: enum
+    can_be_other: true # otherwise value has to be one of the options to be valid.
+    options:
+     - value: coreos
+       label: CoreOS
+       description: CoreOS Stable
+     - value: ubuntu
+       label: Ubuntu
+       description: Ubuntu Bubuntu
+```
+
+```yaml
+# Integer with default value and allowed range
+  foo_instances:
+    type: integer
+    default: 1
+    min: 1
+    max: 30
+```
+
+```yaml
+# Uri validator
+  host_url:
+    type: uri
+    schemes:
+      - file # only allow file:/// uris
+```
+
+## Resolvers
+
+Simple so far. Now let's mix in "resolvers" which can fetch the value from a number of sources or even generate new data:
+
+```yaml
+# Generate random strings
+  vault_iv:
+    type: string
+    from: 
+      random_string:
+        length: 64
+        charset: ascii_printable # Other charsets include hex, hex_upcase, alphanumeric, etc.
+```
+
+```yaml
+# Try to get value from multiple sources
+  aws_secret:
+    type: string
+    strip: true # removes any leading / trailing whitespace from a string
+    upcase: true # turns the string to upcase
+    from:
+      env: 'FOOFOO'
+      file: /tmp/aws_secret.txt  # if env is not set, try to read it from this file, raises if not readable
+
+  aws_secret:
+    type: string
+    strip: true # removes any leading / trailing whitespace from a string
+    upcase: true # turns the string to upcase
+    from:
+      env: FOOFOO
+      file:  # if env is not set, try to read it from this file, returns nil if not readable
+        path: /tmp/aws_secret.txt
+        ignore_errors: true 
+      random_string: 30 # not there either, generate a random string.
+```
+
+## Setters
+
+Ok, so what to do with the values? There's setters for that.
+
+```yaml
+  aws_secret:
+    type: string
+    from:
+      env: AWS_TOKEN
+    to:
+      env: AWS_SECRET_TOKEN # once a valid value is set, set it to this variable.
+
+# There aren't any more setters right now, but one could imagine setters such as
+# output to a file, interpolate into a file, run a command, etc.
+```
+
+## Conditionals
+
+There's also rudimentary conditional support:
+
+```yaml
+  - name: foo
+    type: string
+    value: 'hello'
+  - name: bar
+    type: integer
+    only_if:       # only process if 'foo' has the value 'hello'
+      - foo: hello
+```
+
+```ruby
+ group.option('bar').skip? 
+ => false
+ group.option('foo').value = 'world'
+ group.option('bar').skip? 
+ => true
+```
+
+```yaml
+  - name: bar
+    type: integer
+    skip_if:   # same but reverse, do not process if 'foo' has value 'hello'
+      - foo: 'hello'
+```
+
+```ruby
+ group.option('foo').value = 'world'
+ group.option('bar').skip? 
+ => false
+ group.option('foo').value = 'hello'
+ group.option('bar').skip? 
+ => true
+```
+
+```yaml
+ # These work too:
+
+  - name: bar
+    type: integer
+    skip_if: 
+      - foo: hello # AND
+      - baz: world
+
+  - name: bar
+    type: integer
+    only_if: foo   # process if foo is not null, false or 'false'
+
+  - name: bar
+    type: integer
+    only_if:
+      - foo   # foo is not null
+      - baz   # AND baz is not null
+```
+
+Pretty nifty, right?
+
+## Examples
+
+```ruby
+# Read definitions from 'options' key inside a YAML:
+Opto.load('/tmp/stack.yml', :options)
+
+# Read definitions from root of YAML
+Opto.load('/tmp/stack.yml')
+
+# Create an option group:
+Opto.new( [ {name: 'foo', type: :string} ] )
+# or
+group = Opto::Group.new
+group.build_option(name: 'foo', type: :string, value: "hello")
+group.build_option(name: 'bar', type: :string, required: true)
+group.first
+=> #<Opto::Option:xxx>
+group.size
+=> 2
+group.each { .. }
+group.errors
+=> { 'bar' => { :presence => "Required value missing" } }
+group.options_with_errors.each { ... }
+group.valid?
+=> false
+```
+
+## Creating a custom resolver
+
+Want to prompt for values? Try something like this:
+
+```ruby
+# gem install tty-prompt
+require 'tty-prompt'
+class Prompter < Opto::Resolver
+  def resolve
+    # option = accessor to the option currently being resolved
+    # option.handler = accessor to the type handler
+    # hint = resolver options, for example the env variable name for env resolver, not used here.
+    return nil if option.skip?
+    if option.type == :enum
+      TTY::Prompt.new.select("Select #{option.label}") do |menu|
+        option.handler.options[:options].each do |opt| # quite ugly way to access the option's value list definition
+          menu.choice opt[:label], opt[:value]
+        end
+      end
+    else
+      TTY::Prompt.new.ask("Enter value for #{option.label}")
+    end
+  end
+end
+
+# And the option:
+- name: foo
+  type: enum
+  options:
+    - foo: Foo
+    - bar: Bar
+  from: prompter
+```
+
+## Subclassing a predefined type handler, setter, etc
+
+```ruby
+class VersionNumber < Opto::Types::String
+  Opto::Type.inherited(self) # need to call Opto::Type.inherited for registering the handler for now.
+
+  OPTIONS = Opto::Types::String::OPTIONS.merge(
+    min_version: nil,
+    max_version: nil
+  )
+
+  validate :min_version do |value|
+    if options[:min_version] && value < options[:min_version]
+      "Minimum version required: #{options[:min_version]}"
+    end
+  end
+
+  validate :max_version do |value|
+    if options[:max_version] && value > options[:max_version]
+      "Maximum version: #{options[:max_version]}, yours is #{value}"
+    end
+  end
+
+  sanitize :remove_build_info do |value|
+    value.split('+').first
+  end
+end
+
+# And to use:
+> opt = Opto::Option.new(type: :version_number, name: 'foo', minimum_version: '1.0.0')
+> opt.value = '0.1.0'
+> opt.valid?
+=> false
+> opt.errors
+=> { :validate_min_version => "Minimum version required: 1.0.0" }
+```
+
+## Default types
+
+Global validations:
+
+```yaml
+  in:  # only allow one of the following values
+    - a
+    - b
+    - c
+```
+
+### boolean
+
+```ruby
+{
+   truthy: ['true', 'yes', '1', 'on', 'enabled', 'enable'], # These strings will be turned into true
+   nil_is: false, # If the value is null, set to false
+   blank_is: false, # If the value is a blank string, set to false
+   false: 'false', # When outputting, emit this value when value is false
+   true: 'true',   # When outputting, emit this value when value is true
+   as: 'string'    # Output a string, can be 'boolean' or 'integer'
+}
+```
+
+### enum
+
+```ruby
+{
+  options: [],  # List of the possible option values
+  can_be_other: false  # Or allow values outside the option list
+}
+```
+
+### integer
+```ruby
+{
+  min: 0, # minimum value, can be negative
+  max: nil, # maximum value
+  nil_is_zero: false # null value will be turned into zero
+}
+```
+
+### string
+```ruby
+{
+  min_length: nil, # minimum length
+  max_length: nil, # maximum length
+  empty_is_nil: true, # if string contains whitespace only, make value null
+  encode_64: false, # encode content to base64
+  decode_64: false, # decode content from base64
+  upcase: false, # convert to UPPERCASE
+  downcase: false, # convert to lowercase
+  strip: false, # remove leading/trailing whitespace,
+  chomp: false, # remove trailing linefeed
+  capitalize: false # convert to Capital case.
+}
+```
+
+### uri
+```ruby
+{
+  schemes: [ 'http', 'https' ] # only http and https urls are considered valid
+}
+```
+
+## Default resolvers
+Hint is the value that gets passed to the resolver when doing for example: `env: FOO` (FOO is the hint)
+
+### env
+Hint is the environment variable name to read from. Defaults to the option's name.
+
+### file
+Hint can be a string containing a path to the file, or a hash that defines `path: 'file_path', ignore_errors: true`
+
+### random_number
+Hint must be a hash containing `min: minimum_number, max: maximum_number`
+
+### random_string
+Hint can be a string/number that defines minimum length. Default charset is 'alphanumeric'
+Hint can also be a hash that defines `length: length_of_generated_string, charset: 'charset_name'`
+
+Defined charsets:
+ * numbers (0-9)
+ * letters (a-z + A-Z)
+ * downcase (a-z)
+ * upcase (A-Z)
+ * alphanumeric (0-9 + a-z + A-Z)
+ * hex (0-9 + a-f)
+ * hex_upcase (0-9 + A-F)
+ * base64 (base64 charset (length has to be divisible by four when using base64))
+ * ascii_printable (all printable ascii chars)
+ * or a set of characters, for example: { length: 8, charset: '01' }  Will generate something like:  01001100
+
+### random_uuid
+Ignores hint completely.
+
+Output is a 'random' UUID generated by `SecureRandom.uuid`, such as `78b6decf-e312-45a1-ac8c-d562270036ba`
+
+## Default setters
+
+### env
+Works exactly the same as env resolver, except in reverse.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kontena/opto. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+