slither 0.99.3

data/History.txt

@@ -0,0 +1,16 @@
+  
+== 0.99.2 / 2009-04-28
+
+* Added better support for float formatting
+* Added the money_with_implied_decimal type
+  
+== 0.99.1 / 2009-04-22
+
+* Make the missing method build a column  i.e. body.record_type 1
+* Prevent duplicate column names
+* Better error messages
+* Implement custom padding (spaces (default), zero)
+
+== 0.99.0 / 2009-04-14
+
+* Initial Release

data/README.rdoc

@@ -0,0 +1,100 @@
+== slither
+    by Ryan Wood
+    http://ryanwood.com
+
+== DESCRIPTION:
+
+A simple, clean DSL for describing, writing, and parsing fixed-width text files.
+
+== FEATURES:
+
+* Easy DSL syntax
+* Can parse and format fixed width files
+* Templated sections for reuse
+
+== SYNOPSIS:
+
+  # Create a Slither::Defintion to describe a file format
+  Slither.define :simple do |d|
+  
+    # This is a template section that can be reused in other sections
+    d.template :boundary do |t|
+      t.column :record_type, 4  
+      t.column :company_id, 12      
+    end 
+   
+    # Create a header section
+    d.header, :align => :left do |header|      
+      # The trap tells Slither which lines should fall into this section
+      header.trap { |line| line[0,4] == 'HEAD' }
+      # Use the boundary template for the columns
+      header.template :boundary
+    end
+  
+    d.body do |body|
+      body.trap { |line| line[0,4] =~ /[^(HEAD|FOOT)]/ }
+      body.column :id, 10, :type => :integer
+      body.column :name, 10, :align => :left
+      body.spacer 3
+      body.column :state, 2
+    end
+        
+    d.footer do |footer|
+      footer.trap { |line| line[0,4] == 'FOOT' }
+      footer.template :boundary
+      footer.column :record_count, 10
+    end
+  end
+  
+Supported types are: string, integer, date, float, money, and money_with_implied_decimal.
+  
+Then either feed it a nested struct with data values to create the file in the defined format:
+
+  test_data = {
+    :body => [
+      { :id => 12, :name => "Ryan", :state => 'SC' },
+      { :id => 23, :name => "Joe", :state => 'VA' },
+      { :id => 42, :name => "Tommy", :state => 'FL' },
+    ], 
+    :header => { :record_type => 'HEAD', :company_id => 'ABC'  }, 
+    :footer => { :record_type => 'FOOT', :company_id => 'ABC'  }
+  }
+  
+  # Generates the file as a string
+  puts Slither.generate(:simple, test_data)
+  
+  # Writes the file
+  Slither.write('outfile.txt', :simple, test_data)
+
+or parse files already in that format into a nested hash:
+
+  parsed_data = Slither.parse('infile.txt', :test).inspect
+
+== INSTALL:
+
+sudo gem install slither
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008
+
+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/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('rcov') do |t|
+  t.spec_files = FileList['spec/*.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  load 'tasks/setup.rb'
+end
+
+ensure_in_path 'lib'
+require 'bones'
+
+task :default => 'spec:run'
+
+PROJ.name = 'slither'
+PROJ.authors = 'Ryan Wood'
+PROJ.email = 'ryan.wood@gmail.com'
+PROJ.url = 'http://github.com/ryanwood/slither'
+PROJ.version = '0.99.3'
+PROJ.exclude = %w(\.git .gitignore ^tasks \.eprj ^pkg)
+PROJ.readme_file = 'README.rdoc'
+
+#PROJ.rubyforge.name = 'codeforpeople'
+
+PROJ.rdoc.exclude << '^data'
+PROJ.notes.exclude = %w(^README\.rdoc$ ^data ^pkg)
+
+# PROJ.svn.path = 'bones'
+# PROJ.spec.opts << '--color'

data/TODO

@@ -0,0 +1,13 @@
+== 0.99.2
+
+* Add :limit option on sections
+* Add :validation option for columns
+* Add a validate_file() method to parse a file and run all validation tests (implies validation implemented)
+
+== 1.0.0
+
+* Better Documentation
+
+== 1.x
+
+* Alternate Section Flow (other than linear), i.e. repeatable sections (think batch)

data/lib/slither.rb

@@ -0,0 +1,7 @@
+$: << File.dirname(__FILE__)
+require 'slither/slither'
+require 'slither/definition'
+require 'slither/section'
+require 'slither/column'
+require 'slither/parser'
+require 'slither/generator'

data/lib/slither/column.rb

@@ -0,0 +1,124 @@
+require 'date'
+
+class Slither
+  class ParserError < RuntimeError; end
+  
+  class Column
+    attr_reader :name, :length, :alignment, :type, :padding, :precision, :options
+    
+    def initialize(name, length, options = {})
+      assert_valid_options(options)
+      @name = name
+      @length = length
+      @options = options
+      @alignment = options[:align] || :right
+      @type = options[:type] || :string
+      @padding = options[:padding] || :space
+      @truncate = options[:truncate] || false
+      # Only used with floats, this determines the decimal places
+      @precision = options[:precision] 
+    end
+    
+    def unpacker
+      "A#{@length}"
+    end
+       
+    def parse(value)
+      case @type
+        when :integer: value.to_i
+        when :float, :money: value.to_f
+        when :money_with_implied_decimal:
+          value.to_f / 100
+        when :date:
+          if @options[:format]
+            Date.strptime(value, @options[:format])
+          else
+            Date.strptime(value)
+          end
+        else value.strip
+      end
+    rescue
+      raise ParserError, "The value '#{value}' could not be converted to type #{@type}: #{$!}"
+    end
+    
+    def format(value)
+      pad(formatter % to_s(value))
+    rescue
+      puts "Could not format column '#{@name}' as a '#{@type}' with formatter '#{formatter}' and value of '#{value}' (formatted: '#{to_s(value)}'). #{$!}"
+    end
+       
+    private
+    
+      def formatter
+        "%#{aligner}#{sizer}s"
+      end
+          
+      def aligner
+        @alignment == :left ? '-' : ''
+      end
+      
+      def sizer
+        (@type == :float && @precision) ? @precision : @length
+      end
+      
+      # Manually apply padding. sprintf only allows padding on numeric fields.
+      def pad(value)
+      	return value unless @padding == :zero
+      	matcher = @alignment == :right ? /^ +/ : / +$/
+      	space = value.match(matcher)
+      	return value unless space
+      	value.gsub(space[0], '0' * space[0].size)
+      end
+      
+      def to_s(value)
+        result = case @type
+          when :date:            
+            # If it's a DBI::Timestamp object, see if we can convert it to a Time object
+            unless value.respond_to?(:strftime)
+              value = value.to_time if value.respond_to?(:to_time)
+            end
+            if value.respond_to?(:strftime)        
+              if @options[:format]
+                value.strftime(@options[:format])
+              else
+                value.strftime
+              end
+            else
+              value.to_s
+            end
+          when :float:
+            @options[:format] ? @options[:format] % value.to_f : value.to_f.to_s
+          when :money:
+            "%.2f" % value.to_f
+          when :money_with_implied_decimal:
+            "%d" % (value.to_f * 100)
+          else 
+            value.to_s
+        end
+        validate_size result
+      end
+
+      def assert_valid_options(options)
+        unless options[:align].nil? || [:left, :right].include?(options[:align])
+          raise ArgumentError, "Option :align only accepts :right (default) or :left"
+        end
+        unless options[:padding].nil? || [:space, :zero].include?(options[:padding])
+          raise ArgumentError, "Option :padding only accepts :space (default) or :zero"
+        end
+      end
+      
+      def validate_size(result)
+        # Handle when length is out of range
+        if result.length > @length
+          if @truncate
+            start = @alignment == :left ? 0 : -@length
+            result = result[start, @length]
+          else
+            raise Slither::FormattedStringExceedsLengthError, 
+              "The formatted value '#{result}' in column '#{@name}' exceeds the allowed length of #{@length} chararacters."
+          end
+        end
+        result
+      end
+  end  
+end

data/lib/slither/definition.rb

@@ -0,0 +1,33 @@
+class Slither  
+  class Definition
+    attr_reader :sections, :templates, :options
+    
+    def initialize(options = {})
+      @sections = []
+      @templates = {}
+      @options = { :align => :right }.merge(options)
+    end
+    
+    def section(name, options = {}, &block)
+      raise( ArgumentError, "Reserved or duplicate section name: '#{name}'") if  
+      Section::RESERVED_NAMES.include?( name ) || 
+      (@sections.size > 0 && @sections.map{ |s| s.name }.include?( name ))
+    
+      section = Slither::Section.new(name, @options.merge(options))
+      section.definition = self
+      yield(section)
+      @sections << section
+      section
+    end
+    
+    def template(name, options = {}, &block)
+      section = Slither::Section.new(name, @options.merge(options))
+      yield(section)
+      @templates[name] = section
+    end
+    
+    def method_missing(method, *args, &block)
+      section(method, *args, &block)
+    end
+  end  
+end

data/lib/slither/generator.rb

@@ -0,0 +1,26 @@
+class Slither
+  class Generator
+		
+		def initialize(definition)
+			@definition = definition
+		end
+		
+		def generate(data)
+	    @builder = []
+	    @definition.sections.each do |section|
+	      content = data[section.name]
+	      if content
+  	      content = [content] unless content.is_a?(Array)
+  	      raise(Slither::RequiredSectionEmptyError, "Required section '#{section.name}' was empty.") if content.empty?
+  	      content.each do |row|
+  	        @builder << section.format(row)
+  	      end
+  	    else
+  	      raise(Slither::RequiredSectionEmptyError, "Required section '#{section.name}' was empty.") unless section.optional
+	      end
+	    end
+	    @builder.join("\n")
+		end
+		
+	end
+end

data/lib/slither/parser.rb

@@ -0,0 +1,53 @@
+class Slither
+  class Parser
+        
+    def initialize(definition, file)
+      @definition = definition
+      @file = file
+      # This may be used in the future for non-linear or repeating sections
+      @mode = :linear
+    end
+    
+    def parse()
+      @parsed = {}
+      @content = read_file      
+      unless @content.empty?
+        @definition.sections.each do |section|
+          rows = fill_content(section)
+          raise(Slither::RequiredSectionNotFoundError, "Required section '#{section.name}' was not found.") unless rows > 0 || section.optional
+        end
+      end
+      @parsed
+    end
+    
+    private
+    
+      def read_file
+        content = []
+        File.open(@file, 'r') do |f|
+          while (line = f.gets) do
+            content << line
+          end
+        end
+        content
+      end
+      
+      def fill_content(section)
+        matches = 0
+        loop do
+          line = @content.first
+          break unless section.match(line) 
+          add_to_section(section, line)
+          matches += 1
+          @content.shift
+        end
+        matches
+      end
+      
+      def add_to_section(section, line)
+        @parsed[section.name] = [] unless @parsed[section.name]
+        @parsed[section.name] << section.parse(line)
+      end
+    
+  end
+end

data/lib/slither/section.rb

@@ -0,0 +1,76 @@
+class Slither
+  class Section
+    attr_accessor :definition, :optional
+    attr_reader :name, :columns, :options
+    
+    RESERVED_NAMES = [:spacer]
+    
+    def initialize(name, options = {})
+      @name = name
+      @options = options
+      @columns = []
+      @trap = options[:trap]
+      @optional = options[:optional] || false
+    end
+    
+    def column(name, length, options = {})
+      raise(Slither::DuplicateColumnNameError, "You have already defined a column named '#{name}'.") if @columns.map do |c|
+        RESERVED_NAMES.include?(c.name) ? nil : c.name
+      end.flatten.include?(name)
+      col = Column.new(name, length, @options.merge(options))
+      @columns << col
+      col
+    end
+    
+    def spacer(length)
+      column(:spacer, length)
+    end
+    
+    def trap(&block)
+      @trap = block
+    end
+    
+    def template(name)
+      template = @definition.templates[name]
+      raise ArgumentError, "Template #{name} not found as a known template." unless template
+      @columns = @columns + template.columns
+      # Section options should trump template options
+      @options = template.options.merge(@options)
+    end
+    
+    def format(data)
+      # raise( ColumnMismatchError,
+      #   "The '#{@name}' section has #{@columns.size} column(s) defined, but there are #{data.size} column(s) provided in the data."
+      # ) unless @columns.size == data.size
+      row = ''      
+      @columns.each do |column|
+        row += column.format(data[column.name])
+      end
+      row
+    end
+    
+    def parse(line)
+      line_data = line.unpack(unpacker)
+      row = {}
+      @columns.each_with_index do |c, i|
+        row[c.name] = c.parse(line_data[i]) unless RESERVED_NAMES.include?(c.name)
+      end
+      row
+    end
+    
+    def match(raw_line)
+      raw_line.nil? ? false : @trap.call(raw_line)
+    end
+    
+    def method_missing(method, *args)
+      column(method, *args)
+    end
+  
+    private
+      
+      def unpacker
+        @columns.map { |c| c.unpacker }.join('')
+      end
+
+  end  
+end