ytools 0.1.0

data/Rakefile

@@ -0,0 +1,52 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift File.expand_path("../spec", __FILE__)
+
+require 'fileutils'
+require 'rake'
+require 'rubygems'
+require 'spec/rake/spectask'
+require 'ytools/version'
+
+task :default => :spec
+
+desc "Run the RSpec tests"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['-b', '-c', '-f', 'p']
+  t.fail_on_error = false
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name           = 'ytools'
+    gem.version        = YTools::Version.to_s
+    gem.executables    = %W{ypath ytemplates}
+    gem.summary        = 'For reading or writing configuration files using YAML.'
+    gem.description    = "Installs the ypath tool for reading YAML files using an XPath-like syntax.  Installs the ytemplates tool for writing ERB templates using YAML files as the template binding object."
+    gem.email          = ['madeonamac@gmail.com']
+    gem.authors        = ['Gabe McArthur']
+    gem.homepage       = 'http://github.com/gabemc/ytools'
+    gem.files          = FileList["[A-Z]*", "{bin,lib,spec}/**/*"]
+    
+    gem.add_development_dependency 'rspec', '>=1.3.0'
+  end
+rescue LoadError
+  puts "Jeweler or dependencies are not available.  Install it with: sudo gem install jeweler"
+end
+
+desc "Deploys the gem to rubygems.org"
+task :gem => :release do
+  system("gem build ytools.gemspec")
+  system("gem push ytools-#{YTools::Version.to_s}.gem")
+end
+
+desc "Does the full release cycle."
+task :deploy => [:gem, :clean] do
+end
+
+desc "Cleans the gem files up."
+task :clean do
+  FileUtils.rm(Dir.glob('*.gemspec'))
+  FileUtils.rm(Dir.glob('*.gem'))
+end

data/bin/ypath

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'ytools/path/cli'
+YTools::Path::CLI.new(ARGV).execute!

data/bin/ytemplates

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'ytools/templates/cli'
+YTools::Templates::CLI.new(ARGV).execute!

data/lib/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/ytools/basecli.rb

@@ -0,0 +1,67 @@
+require 'optparse'
+require 'ytools/errors'
+require 'ytools/version'
+
+module YTools
+
+  class BaseCLI
+    attr_reader :options, :args
+
+    def initialize(args)
+      @args = args
+      @options = {}
+    end
+
+    def execute!
+      begin
+        sargs = args.dup
+        parse(sargs)
+        validate(sargs)
+        execute(sargs)
+      rescue SystemExit => e
+        raise
+      rescue YTools::ConfigurationError => e
+        print_error(e.message)
+      rescue OptionParser::InvalidOption => e
+        print_error(e.message)
+      rescue Exception => e
+        STDERR.puts e.backtrace
+        print_error(e.message)
+      end
+    end
+
+    protected
+    def parse(args)
+      # To override
+    end
+
+    def validate(args)
+      # To override
+    end
+
+    def execute(args)
+      # To override
+    end
+
+    def print_version
+      puts "#{File.basename($0)} version: #{YTools::Version.to_s}"
+      exit 0
+    end
+
+    def print_examples(basedir)
+      examples = File.join(basedir, 'examples.txt')
+      File.open(examples, 'r') do |f|
+        f.each_line do |line|
+          puts line
+        end
+      end
+      exit 0
+    end
+
+    def print_error(e)
+      STDERR.puts "ERROR: #{File.basename($0)}: #{e}"
+      STDERR.puts "ERROR: #{File.basename($0)}: Try '--help' for more information"
+      exit 1
+    end
+  end
+end

data/lib/ytools/errors.rb

@@ -0,0 +1,7 @@
+
+module YTools
+  Error = Class.new(RuntimeError)
+
+  ConfigurationError = Class.new(YTools::Error)
+  PathError          = Class.new(YTools::Error)
+end

data/lib/ytools/path/cli.rb

@@ -0,0 +1,103 @@
+require 'optparse'
+require 'ytools/basecli'
+require 'ytools/errors'
+require 'ytools/path/executor'
+
+module YTools::Path
+  class CLI < YTools::BaseCLI
+    protected 
+    def execute(sargs)
+      begin
+        executor = Executor.new(options[:path], sargs)
+
+        if options[:debug]
+          STDERR.puts executor.yaml_object
+        end
+
+        puts executor.process!
+      rescue YTools::Path::ParseError => e
+        print_path_error(e)
+      end
+    end
+
+    def parse(args)
+      OptionParser.new do |opts| 
+        opts.banner = "Usage: #{File.basename($0)} [OPTIONS] YAML_FILES"
+        opts.separator <<EOF
+Description:
+    This tool uses a kind of XPath syntax for locating and printing elements
+    from within YAML files.  Check out the '--examples' flag for details
+    on the exact path syntax.
+
+    It accepts multiple yaml files, and will merge their contents in the
+    order in which they are given.  Thus, files listed later, if their
+    keys conflict with ones listed earlier, override the earlier listed
+    values.  If you pass in files that don't exist, no error will be 
+    raised unless the '--strict' flag is passed.
+
+Options:
+EOF
+
+        opts.on('-p', '--path PATTERN',
+                "The pattern to use to access the",
+                "configuration.") do |p|
+          options[:path] = p
+        end
+        opts.on('-s', '--strict',
+                "Checks to make sure all of the YAML files",
+                "exist before proceeding.") do |s|
+          options[:strict] = true
+        end
+        opts.separator ""
+        
+        opts.on('-e', '--examples',
+                "Show some examples on how to use the",
+                "path syntax.") do
+          print_examples(File.dirname(__FILE__))
+        end
+        opts.on('-v', '--version',
+                "Show the version information") do |v|
+          print_version
+        end
+        opts.on('-d', '--debug',
+                "Prints out the merged yaml as a",
+                "ruby object to STDERR.") do |d|
+          options[:debug] = true
+        end
+        opts.on('-h', '--help',
+                "Show this help message.") do
+          puts opts
+          exit 0
+        end
+      end.parse!(args)
+    end
+
+    def validate(args)
+      if options[:path].nil?
+        raise YTools::ConfigurationError.new("The path expression was empty.")
+      end
+      if args.length == 0
+        raise YTools::ConfigurationError.new("No YAML files given as arguments")
+      end
+
+      if options[:strict]
+        args.each do |arg|
+          if !File.exists?(arg)
+            raise YTools::ConfigurationError.new("Non-existant YAML file: #{arg}")
+          end
+        end
+      end
+    end
+
+    def print_path_error(e)
+      STDERR.puts "ERROR: Path error: #{e.token.path}"
+      spacer = "ERROR:             "
+      e.token.offset.downto(1) do 
+        spacer << " "
+      end
+      spacer << "^"
+      STDERR.puts spacer
+      print_error("Path expression parsing error - #{e.message}")
+    end
+  end # CLI
+end

data/lib/ytools/path/examples.txt

@@ -0,0 +1,64 @@
+Examples
+--------
+
+Something like XPath, we use dotted expressions to pull out
+specific configuration values.
+
+The path expression have a particular syntax:
+
+- YAML hashes are accessed using the '/' syntax, so 
+     ---
+     this:
+        goes: here
+     ---
+  would access the value 'here' with the expression '/this/goes'.
+
+  If the key itself has '/' characters, wrap the key in '|'s, so
+     ---
+     this/is/complex:
+        goes: here
+     ---
+  would access the value 'here' with the expression 
+  '/|this/is/complex|/goes'.  The '|' can be escaped with '\|'
+
+- Array values can be specified by index so
+     ---
+     this:
+        - is a list
+        - of values
+     ---
+  would access the 2nd array value 'of values' with the 
+  expression '/this[1]'
+
+- If you want all of the values in a list or in a collection 
+  of descendants, each value on a separate line,
+     ---
+     this:
+        - name: joe
+          age: 32
+        - name: jack
+          age: 10
+     ---
+  would access all of ages could be accessed by '/this//age'
+  and would return:
+
+     32
+     10
+
+- If you want all the keys in a hash, each key on a 
+  separate line,
+     ---
+     this:
+        host1:
+           value: blip
+        host2:
+           value: bloom
+        host3:
+           value: blam
+     ---
+  you would access 'host[1-3]' with the expression '/this'.
+  
+Caveats
+-------
+Missing elements output nothing.  Malformed path expressions
+print an error and exit 1.

data/lib/ytools/path/executor.rb

@@ -0,0 +1,58 @@
+require 'ytools/yaml_object'
+require 'ytools/path/parser'
+
+module YTools::Path
+
+  class Executor
+    attr_reader :path, :yaml_object
+
+    def initialize(path, files)
+      @path = path
+      @yaml_object = YTools::YamlObject.from_files(files)
+    end
+
+    def process!
+      parser = Parser.new(path)
+      selectors = parser.parse!
+
+      found = selectors.select(yaml_object)
+      if found.is_a?(YTools::YamlObject)
+        show_yaml_object(found)
+      elsif found.is_a?(Array)
+        show_array(found)
+      else
+        found.to_s
+      end
+    end
+
+    private
+    def show_yaml_object(found)
+      output = ""
+      first = true
+      found.yhash.each_key do |key|
+        if first
+          first = false
+        else
+          output << "\n"
+        end
+        output << key.to_s
+      end
+      output
+    end
+
+    def show_array(found)
+      output = ""
+      first = true
+      found.each do |found|
+        if first
+          first = false
+        else
+          output << "\n"
+        end
+        output << found.to_s 
+      end
+      output
+    end
+
+  end
+end

data/lib/ytools/path/lexer.rb

@@ -0,0 +1,166 @@
+require 'ytools/errors'
+
+module YTools::Path
+
+  Token = Struct.new(:path, :offset, :length, :type) do
+    def value
+      case type
+        when :path_separator then '/'
+        when :path_part then path # We cheat and put in the actual
+                                  # value of the path part here, 
+                                  # because we don't care about the offset
+        when :lbrace then '['
+        when :rbrace then ']'
+        when :number then path[offset, length].to_i
+        else raise YPath::PathError("Unrecognized token type!!!!")
+      end
+    end
+  end
+  
+  class Lexer
+    attr_reader :offset, :path
+
+    def initialize(path)
+      @path = path
+      @offset = 0
+      @buffer = []
+    end
+
+    def [](index)
+      if offset + index >= path.length
+        nil
+      else
+        @path[offset + index]
+      end
+    end
+
+    def next
+      if @buffer.length > 0
+         @buffer.pop
+      else
+        token
+      end
+    end
+
+    def peek(count=nil)
+      count ||= 0
+
+      if count >= @buffer.length
+        (@buffer.length - count).downto(0) do
+          @buffer.push(token)
+        end
+      end
+
+      @buffer[count]
+    end
+
+    def has_next?
+      !peek.nil?
+    end
+
+    private
+    def token
+      return nil if offset >= path.length
+
+      case @path[offset]
+        when ?/ then path_separator
+        when ?[ then lbrace
+        when ?] then rbrace
+        when ?- then path_part
+        when ?0..?9 then number
+        else path_part
+      end
+    end
+
+    def path_separator
+      tok = Token.new(path, offset, 1, :path_separator)
+      @offset += 1
+      tok
+    end
+
+    def lbrace
+      tok = Token.new(path, offset, 1, :lbrace)
+      @offset += 1
+      tok
+    end
+
+    def rbrace
+      tok = Token.new(path, offset, 1, :rbrace)
+      @offset += 1
+      tok
+    end
+
+    def number
+      starting_offset = offset
+
+      while offset < path.length
+        case path[offset]
+          when ?0..?9 then @offset += 1
+          else break
+        end
+      end
+
+      Token.new(path, starting_offset, offset - starting_offset, :number)
+    end
+
+    def path_part
+      starting_offset = offset
+      in_bar = false
+      str = ""
+
+      while offset < path.length
+        case path[offset]
+        when ?\\
+          if offset + 1 >= path.length
+            raise YTools::PathError.new("Last character in a path cannot be a '\\' character: '#{path}'")
+          end
+
+          lookahead = path[offset + 1]
+          case lookahead
+          when ?[ , ?] , ?| , ?\ , ?/
+            str << lookahead
+            @offset += 2
+          else
+            raise YTools::PathError.new("Unescaped backslash character at position #{offset} in '#{path}'")
+          end
+        when ?| 
+          in_bar = !in_bar
+          @offset += 1
+        when ?/ 
+          if in_bar
+            str << ?/
+            @offset += 1
+          else
+            return path_or_number(str, starting_offset, offset - starting_offset)
+          end
+        when ?[ , ?] , ?@ then
+          return path_or_number(str, starting_offset, offset - starting_offset)
+        else 
+          if !path[offset].nil?
+            str << path[offset]
+            @offset += 1
+          end
+        end
+      end
+
+      if in_bar
+        raise YTools::PathError.new("There was no closing bar '|' character in the path '#{path}'")
+      end
+
+      return path_or_number(str, starting_offset, offset - starting_offset)
+    end
+
+# FIXME: there's a bug in here somewhere about the offset for numbers/paths.
+
+    def path_or_number(str, start, length)
+      i = str.to_i
+      if i == 0
+        return Token.new(str, start, length, :path_part)
+      elsif i.to_s == str
+        return Token.new(str, 0, length, :number)
+      else
+        return Token.new(str, start, length, :path_part)
+      end
+    end
+  end # PathLexer  
+end