dupervisor 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bca39c7b710df3bc2a87932f40b4f778b7612ccf
-  data.tar.gz: 13aa34c9976da2a02b7ba1c3dcb532f845b8ce1d
+  metadata.gz: 76bfc503dc8997edc0e6926cde6a7aed182d4a32
+  data.tar.gz: 683bb204b680c970a7c2156791ce6735d34cc438
 SHA512:
-  metadata.gz: 2682e95d55df050f8e9828ecbcf1a176c9d73e8ff8187f200ea0cb037efa209b96cbeed4bfebce6f5531a11d2f82a250baac46108667dbac11677923af001d11
-  data.tar.gz: a59a88ea3b11907152002dd2cb61862b67ed546531e72b6f8ad80453a328771d7a9a64234cedf5f282c4d2c92ec8a9b1c9f863294e2547970619f08f2a1b3e82
+  metadata.gz: 48c9203124a4d72d534e4af996f60be2189ad70b716141972978339f02e63e77c9179f3eff77eaa04c8c632dfbfaac6a89a5da7efd507ec7a3fa94498232d960
+  data.tar.gz: c18ae3908021f61dfe427987a296adbc3557aa41420102f670323eb7b3ac63c9cec7be14dcef54b6208fbf3baa564383b88bfd804537149148d9f8ff631f1820

data/README.md

@@ -4,15 +4,17 @@
 [![Test Coverage](https://codeclimate.com/github/kigster/dupervisor/badges/coverage.svg)](https://codeclimate.com/github/kigster/dupervisor/coverage)
 [![Issue Count](https://codeclimate.com/github/kigster/dupervisor/badges/issue_count.svg)](https://codeclimate.com/github/kigster/dupervisor)
 
-# DuperVisor™ Pro 
+# dupervisor
 
-The super-duper awesome library is your best friend if you want an easy way to convert configuration between any one of the supported formats, which at this time are: JSON, YAML, and Windows INI format. 
+Ruby gem `dupervisor` is a well tested library that offers an easy way to convert configuration between any two of the supported formats, which (at this time) are:  
 
-This tool was originally created to allow storing configs of another great tool called [__supervisord__](http://supervisord.org), which is still highly applicable today, but unfortunately uses a rather [archaic configuration file format](http://supervisord.org/configuration.html) of the decades old Windows INI format.
+ * JSON
+ * YAML
+ * and the Windows INI file formats. 
 
-Whatever your preferences are, the truth is that some of the modern DevOps tools (such as Ansible and SaltStack) are using YAML format extensively to configure the environments. Ability to "embed" YAML configuration for a tool like supervisord means that you don't have to go to multiple places to see what is being run everywhere.
+Please see the [section "Motivation"](#motivation) below, which contains further discussion about why this is useful.
 
-If you enjoy using this converted, please star the repo and we very much welcome all pull requests and contributions.
+If you enjoy using this library, please star the repo, and do submit pull requests and/or bug reports, as well as any other contributions – which are all accepted with gratitude.
 
 ## YAML/JSON vs INI
 
@@ -23,25 +25,12 @@ Consider the following example taken from the [_supervisord_ configuration docum
 nodaemon = false
 minfds = 1024
 minprocs = 200
-umask = 022
-user = chrism
-identifier = supervisor
-directory = /tmp
-nocleanup = true
-childlogdir = /tmp
-strip_ansi = false
-environment = PATH="/usr/bin:/usr/local/bin:/bin:/sbin",ENVIRONMENT="development"
 
 [program:cat]
 command=/bin/cat
 process_name=%(program_name)s
-numprocs=1
-directory=/tmp
-umask=022
-priority=999
 autostart=true
 autorestart=unexpected
-
 ```
 
 We think that it is much easier to read this:
@@ -51,28 +40,22 @@ supervisord:
   nodaemon: false
   minfds: 1024
   minprocs: 200
-  umask: 022
-  user: chrism
-  identifier: supervisor
-  directory: /tmp
-  nocleanup: true
-  childlogdir: /tmp
-  strip_ansi: false
-  environment: PATH="/usr/bin:/usr/local/bin:/bin:/sbin",ENVIRONMENT="development"
 
 program:
   cat:
     command: /bin/cat
     process_name: %(program_name)s
-    numprocs: 1
-    directory: /tmp
-    umask: 022
-    priority: 999
     autostart: true
     autorestart: unexpected
 ```
 
-Not only that, but with this structure you can leverage existing tools for merging information from the default environment to your production, and so on.
+Besides arguably better readability, YAML format also allows you to leverage existing configuration management tools such as Chef, SaltStack or Ansible.
+
+### Supervisord Specifics
+
+When parsing INI files, and upon encountering a hash key of the form `word1:word2`, such key is broken up into the two parts and second part is used to create a sub-hash, thus generating a three-level hash. Supervisord uses this syntax for describing all commands to run, such as `program:cat` or `program:pgbouncer`, etc. Parser for INI format will create a hash with keys `cat` and `pgbouncer`, which itself will be mapped to the key `program`. 
+
+Reverse is also true – and such a three-level hash will be collapsed by joining second and third level keys with a colon, before rendering INI file.
 
 ## Installation
 
@@ -90,12 +73,13 @@ gem 'dupervisor'
 
 ## Usage
 
-To perform translations in code, you would use `DuperVisor::Parser` class to parse an existing format, and `DuperVisor::Renderer` class to convert the intermediary hash into the destination format:
+### From Ruby Code
 
-```ruby
-# This helper extracts format from a file extension
-Detector.new('myfile.json').detect  # => :json
+To perform config transformations in ruby, you would typically use the `DuperVisor::Parser` class to parse an existing format and, optionally, to guess the format of the content. 
+
+You would then use the `DuperVisor::Renderer` class to render the intermediate hash into the destination format, like so:
 
+```ruby
 # This is how you can parse content by specifying the format
 content = Parser.new(File.read('myfile.json')).parse(:json) 
 
@@ -110,39 +94,81 @@ content.parse_result # => { ... } Hash
 Renderer.new(content.parse_result).render(:yaml) # => YAML string
 ```
 
-You can use the provided executable `dupervisor` to convert from a JSON or YAML file into an INI
+There is an additional helper available to grab format from a filename:
 
-### `dv [source-file] [options]`
+```ruby
+# This helper extracts format from a file extension
+Detector.new('myfile.json').detect  # => :json
+```
 
-Summary: convert between several hierarchical configuration file formats, such as ini, yaml, json
-Automatically guesses the source format based either on the file extension, or by attempting to parse it for STDIN.
+### Command Line
 
-#### Specific Options
+You can also use the provided executable `dv` to transform between supported formats.
 
+```bash
+$ dv [source_file | STDIN ] 
+     [ --yaml | --ini | --json ] 
+     [ -o | --output output_file | STDOUT ]
 ```
-        --ini                        Generate an INI file
-        --yaml                       Generate a YAML file
-        --json                       Generate a JSON file
-    -o, --output [FILE]              File to write, if not supplied write to STDOUT
-    -v, --verbose                    Print extra debugging info
-    -h, --help                       Show this message
-        --version                    Show version
+
+#### CLI Options
+
+```
+        --ini            Generate an INI file
+        --yaml           Generate a YAML file
+        --json           Generate a JSON file
+    -o, --output [FILE]  File to write, if not supplied write to STDOUT
+    -v, --verbose        Print extra debugging info
+    -h, --help           Show this message
+        --version        Show version
 ```
 
 #### Examples
 
 __Guess input format, convert YAML format to an INI file:__
 
-```
+```bash
 $ cat config.yml | dv --ini > config.ini
 ```
 
 __Guess input format, convert INI format to a JSON file:__
 
-```
+```bash
 $ dv config.ini --json -o config.json
 ```
 
+## Adding New Formats
+
+It should be relatively trivial to add new formats to the gem. Please check out the `lib/dupervisor/formats` folder, copy eg. `yaml.rb` file to a new name, and update the code.
+
+Below is the actual code of YAML converter. 
+
+```ruby
+module DuperVisor
+  module Formats
+    class YAML < Base
+      aliases %i(yml)
+      from    ->(string)  { ::YAML.load(string) }
+      to      ->(hash)    { ::YAML.dump(hash)   }
+      errors  [Psych::SyntaxError]
+    end
+  end
+end
+```
+
+ * __aliases__ are additional names of the format. Main name is the class name without the modules.
+ * __from__ is a proc that receives a string, and should return a hash or raise an error.
+ * __to__ is a proc that receives a hash, and is supposed to return a string representing the hash in a given format.
+ * __errors__ is a list of exceptions that parsing (`#to`) may raise if the content is not valid for this format.
+
+
+## Motivation
+
+This tool was originally created to allow storing as YAML configuration of [__supervisord__](http://supervisord.org), which uses a [decades old configuration file format](http://supervisord.org/configuration.html) known as the Windows INI file.
+
+Some of the modern DevOps tools (such as Ansible and SaltStack) are using YAML format extensively to configure the environments. Chef stores node attributes as a hash, which is DuperVisor's intermediate data structure. Therefore DuperVisor offers an opportunity to "embed" INI-files for tools like _supervisord_ natively within the configuration management software, to keep all configuration centralized. When configuration management tool executes, INI files can be re-rendered on the fly. 
+
+Note that the same applies to rendering into YAML or JSON, and that the source could also be any one of the three.
 
 ## Contributing
 

data/lib/dupervisor/cli.rb

@@ -9,76 +9,76 @@ module DuperVisor
     attr_accessor :args, :config, :parser
 
     def initialize(args)
-      self.args    = args
+      self.args   = args
       self.config = Config.new
     end
 
     def parse
       self.parser = OptionParser.new do |opts|
-        usage_banner(opts)
+        decorator = OptionsDecorator.new(opts, config)
+        decorator.usage
+        decorator.flags
+        decorator.examples
+      end
 
-        opts.on('--ini', 'Generate an INI file') do
-          config.to = :ini
-        end
-        opts.on('--yaml', 'Generate a YAML file') do
-          config.to = :yaml
-        end
-        opts.on('--json', 'Generate a JSON file') do
-          config.to = :json
-        end
+      parser.parse!(args)
+      config
+    end
+
+    class OptionsDecorator < Struct.new(:opts, :config)
+
+      def flags
+        opts.separator 'Options:'.bold.blue.underlined
+        opts.separator '  Output Format:'.bold.yellow
+        opts.on('--ini', 'Generate an INI file') { config.to = :ini }
+        opts.on('--yaml', 'Generate a YAML file') { config.to = :yaml }
+        opts.on('--json', 'Generate a JSON file') { config.to = :json }
+        opts.separator ''
 
+        opts.separator '  Flags:'.bold.yellow
         opts.on('-o', '--output [FILE]',
-                'File to write, if not supplied write to STDOUT') do |file|
+                'File to write, STDOUT if none.') do |file|
           config.output = file
         end
 
-        opts.on('-v', '--verbose',
-                'Print extra debugging info') do
-          config.verbose = true
-        end
-        example_banner(opts)
-
         # No argument, shows at tail.  This will print an options summary.
         # Try it and see!
-        opts.on_tail('-h', '--help', 'Show this message') do
+        opts.on('-h', '--help', 'Show this message') do
           puts opts
           exit
         end
 
         # Another typical switch to print the version.
-        opts.on_tail('--version', 'Show version') do
+        opts.on('--version', 'Show version') do
           puts DuperVisor::VERSION
           exit
         end
+
       end
-      parser.parse!(args)
-      config
-    end
 
-    def example_banner(opts)
-      opts.separator ''
-      opts.separator 'Examples:'.bold.blue
-      opts.separator ''
-      opts.separator '    # guess input format, convert YAML format to an INI file'
-      opts.separator '    cat config.yml | dv --ini > config.ini'.green
-      opts.separator ''
-      opts.separator '    # guess input format, convert INI format to a JSON file '
-      opts.separator '    dv config.ini --json -o config.json'.green
+      def examples
+        opts.separator ''
+        opts.separator 'Examples:'.bold.blue.underlined
+        opts.separator ''
+        opts.separator '    # guess input format, convert YAML format to an INI file'
+        opts.separator '    cat config.yml | dv --ini > config.ini'.green
+        opts.separator ''
+        opts.separator '    # guess input format, convert INI format to a JSON file '
+        opts.separator '    dv config.ini --json -o config.json'.green
 
-      opts.separator ''
-      opts.separator 'Common options:'.bold.blue
-    end
+        opts.separator ''
+      end
 
-    def usage_banner(opts)
-      opts.banner = 'Usage: '.bold.blue + 'dv [source-file] [options] '.bold.green
-      opts.separator ''
-      opts.separator '       Convert between several hierarchical configuration'
-      opts.separator '       file formats, such as ' + 'ini, yaml, json'.bold.green
-      opts.separator ''
-      opts.separator '       Automatically guesses the source format based either on'
-      opts.separator '       the file extension, or by attempting to parse it for STDIN'
-      opts.separator ''
-      opts.separator 'Specific options:'.bold.blue
+      def usage
+        opts.banner = 'Usage:'.bold.blue.underlined + "\n" + '  dv [source-file] [options] '.bold.green
+        opts.separator ''
+        opts.separator '  Convert between several hierarchical configuration'
+        opts.separator '  file formats, such as ' + 'ini, yaml, json.'.bold.green
+        opts.separator ''
+        opts.separator '  Automatically detects the source format based on either'
+        opts.separator '  the file extension, or by attempting to parse STDIN.'
+        opts.separator ''
+      end
     end
   end
 end

data/lib/dupervisor/config.rb

@@ -7,11 +7,10 @@ module DuperVisor
   end
 
   class Config
-    attr_accessor :to, :output, :verbose
+    attr_accessor :to, :output
 
-    def initialize(to: nil, output: nil, verbose: false)
+    def initialize(to: nil, output: nil)
       self.to      = to
-      self.verbose = verbose
       self.output  = output
     end
 

data/lib/dupervisor/formats/yaml.rb

@@ -10,5 +10,4 @@ module DuperVisor
       errors  [Psych::SyntaxError]
     end
   end
-
 end

data/lib/dupervisor/main.rb

@@ -17,6 +17,10 @@ module DuperVisor
       self.content = Parser.new(ARGF.read).parse(from_format)
       Renderer.new(content.parse_result, config.output).render(config.to)
     rescue DuperVisor::Parser::ParseError => e
+      report_error(e)
+    end
+
+    def report_error(e)
       puts '  Error:'.bold.white + ' Unable to parse input.'.bold.red
       puts 'Details:'.bold.white + " #{e.inspect}".red
     end

data/lib/dupervisor/version.rb

@@ -1,3 +1,3 @@
 module DuperVisor
-  VERSION = "1.0.2"
+  VERSION = '1.0.3'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dupervisor
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Konstantin Gredeskoul