FixedWidthFields 0.1

data/lib/fixedWidth.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+#--
+# Copyright 2006 by Brett Norris (norri_b@hotmail.com).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+require 'fixedWidth/base'
+require 'fixedWidth/helpers'

data/lib/fixedWidth/base.rb

@@ -0,0 +1,148 @@
+require 'test/unit'
+require 'fixedWidth/helpers'
+
+# The FixedWidthFields library is designed to allow
+# files containing fixed-width fields to be created
+# easily.
+# 
+# Fixed-width fields are fields that are guaranteed to
+# take up the specified number of characters when
+# converted to a string.
+#
+# == Example
+# Say that we want to create a class representing a
+# Person and convert this to a fixed-width string
+# easily.
+#
+# Create the class as follows:
+#   class Person < FixedWidthFields
+#	    field :name, :width => 5
+#	    field :age, :width => 3, :pad_with => '0'
+#   end 
+#
+# Use it as follows:
+#   james = Person.new
+#   james.name = "JamesBond"
+#   james.age = 7
+#
+#   james.to_s # => "James007"
+# 
+# == Defining fixed width fields
+#
+# Parameters that must be used when defining fields are:
+# * <tt>:width</tt> - the required width of the field
+#
+# Parameters that can be used when defining fields are:
+# * <tt>:default</tt> - the default value that this field should take if it is not explicitly set
+# * <tt>:pad_with</tt> - the character that should be used for padding the field if it is less than the required width (defaults to the space character)
+# * <tt>:formatter</tt> - a <tt>Proc</tt> instance that can be used for formatting the field. This proc should expect one parameter (which will be set to the value of the field) and should return a string. If the string returned is greater than the specified width of the field, the field will be truncated.
+
+class FixedWidthFields
+	# This class is used by the <tt>FixedWidthFields</tt> class to
+	# store the metadata associated with each fixed-width field. It is
+	# not intended for this class to be used seperately from the
+	# <tt>FixedWidthFields</tt> class.
+	class Field
+		# Contains the name of this fixed-width field (i.e. the
+		# name of the instance variable through which it is
+		# accessed)
+		attr_reader :name
+
+		# Create a new instance of a fixed-width field, accessed through
+		# instance variable <tt>name</tt> with defining parameters
+		# specified in <tt>params</tt>.
+		# See <tt>FixedWidthFields</tt> for a list of the valid
+		# parameters
+		def initialize(name, params)
+			@name, @params = name,params
+			validate_params
+		end
+
+		# Return the default value for this field (i.e. the value it
+		# takes if it is not explicitly set to another value)
+		def default
+			@params[:default]
+		end
+
+		# Applies the formatting to this field and returns the
+		# formatted field
+		def format_field(instance)
+			value = instance.send(@name) || @params[:default]
+			value = @params[:formatter].call(value) unless @params[:formatter].nil?
+
+			return justify_field(value)
+		end
+
+		# Ensure that the parameters given when creating this field
+		# are valid
+		def validate_params
+			raise "field '#{name}' has no width specified" if @params[:width].nil?
+		end
+
+		# Ensure that the field is exactly the specified width
+		def justify_field(contents)
+			justify_char = @params[:pad_with] || ' '
+			contents.to_s.rjust(@params[:width], justify_char)[0,@params[:width]]
+		end
+
+		private :justify_field, :validate_params 
+	end
+
+	# Define getter for class instance variable 'fields'
+	class << self
+		class_eval {
+			# An attribute stored in the metaclass. This is an array
+			# containing all of the fixed-width fields defined in
+			# this class.
+			attr_reader :fields
+		}
+	end
+
+	# Ensure that class instance variable 'fields' defaults to []
+	class_eval {
+		instance_variable_set("@fields", [])
+	}
+
+	# Convert all of the fields in the class into string form. Each field
+	# will be present in the order it was defined in the class and the
+  # width of each field will be exactly equal to the <tt>:width</tt>
+  # parameter supplied
+	def to_s
+		self.class.fields.inject("") {|result,field|
+			result += field.format_field(self)
+		}
+	end
+
+	# Defines an accessor for <tt>field</tt>.
+  # This will work in the expected way but will also ensure
+  # that the field can be converted to a fixed-width string
+	# when <tt>to_s</tt> is called on the defining class
+	# The <tt>formatting_params</tt> hash defines the formatting
+	# applied to this field when it is converted to a string.
+	# Valid values of <tt>formatting_params</tt> are as follows:
+	# * <tt>:width</tt> - the required width of the field
+	# * <tt>:default</tt> - the default value that this field should take if it is not explicitly set
+	# * <tt>:pad_with</tt> - the character that should be used for padding the field if it is less than the required width (defaults to the space character)
+	# * <tt>:formatter</tt> - a <tt>Proc</tt> instance that can be used for formatting the field. This proc should expect one parameter (which will be set to the value of the field) and should return a string. If the string returned is greater than the specified width of the field, the field will be truncated.
+
+	def self.field(field, formatting_params={})
+		attr_accessor(field.to_sym)
+
+		ensure_superclass_fields_present
+		@fields << Field.new(field.to_sym, formatting_params)
+	end
+
+	private
+	# This method does not need to be used directly
+	def initialize
+		self.class.ensure_superclass_fields_present if self.class.fields.nil?
+		self.class.fields.each {|field|
+				instance_variable_set("@#{field.name}", field.default)
+		}
+	end
+
+	def self.ensure_superclass_fields_present
+		@fields ||= superclass.fields.dup
+	end
+
+end

data/lib/fixedWidth/helpers.rb

@@ -0,0 +1,11 @@
+class FixedWidthFields
+	# A helper method to convert a Time value into the format
+	# 'YYYYmmddHHMMSS'. It can be used in a FixedWidthField class
+	# by using :formatter => DateTimeFormatter
+	DateTimeFormatter = lambda {|t| t.strftime("%Y%m%d%H%M%S") }
+
+	# A helper method to convert a Time value into the format
+	# 'YYYYmmdd'. It can be used in a FixedWidthField class by
+	# using :formatter => DateFormatter
+	DateFormatter = lambda {|t| t.strftime("%Y%m%d") }
+end

data/test/testFixed.rb

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+require 'fixedWidth/base'
+
+class TestFixed < Test::Unit::TestCase
+	class Person < FixedWidthFields
+		field :name, :width => 4, :default => "Bob"
+		field :age, :width => 2, :pad_with => '0'
+	end
+
+	class NameTlaFile < Person
+		field :tla, :width => 3
+	end
+
+	def testBaseClass
+		a = FixedWidthFields.new
+		assert_equal("", a.to_s)
+	end
+
+	def testTruncatedField
+		self.class.class_eval "remove_const :Name if const_defined? :Name"
+		self.class.class_eval "class Name < FixedWidthFields
+			field :name, :width => 4
+		end"
+
+		brian = Name.new
+		brian.name = "Brian"
+
+		assert_equal("Brian", brian.name)
+		assert_equal("Bria", brian.to_s)
+	end
+
+	def testJustifiedWithSpace
+		self.class.class_eval "remove_const :Name if const_defined? :Name"
+		self.class.class_eval "class Name < FixedWidthFields
+			field :name, :width => 5
+		end"
+
+		bob = Name.new
+		bob.name = "Bob"
+
+		assert_equal("Bob", bob.name)
+		assert_equal("  Bob", bob.to_s)
+	end
+
+	def testLeftJustifiedWithChar
+		self.class.class_eval "remove_const :Age if const_defined? :Age"
+		self.class.class_eval "class Age < FixedWidthFields
+			field :age, :width => 3, :pad_with => '0'
+		end"
+
+		bond = Age.new
+		bond.age = 7
+		assert_equal(7, bond.age)
+		assert_equal("007", bond.to_s)
+	end
+
+	def testDerivedClass
+		self.class.class_eval "remove_const :Name if const_defined? :Name"
+		self.class.class_eval "remove_const :NameAndAge if const_defined? :NameAndAge"
+		self.class.class_eval "class Name < FixedWidthFields
+			field :name, :width => 4
+		end"
+		self.class.class_eval "class NameAndAge < Name
+			field :age, :width => 3
+		end"
+
+		johnny = NameAndAge.new
+		johnny.name = "Johnny"
+		johnny.age = 27
+	
+		assert_equal("John 27", johnny.to_s)
+	end
+
+	def testDefaultField
+		self.class.class_eval "remove_const :Name if const_defined? :Name"
+		self.class.class_eval "class Name < FixedWidthFields
+			field :name, :width => 5, :default => \"Bob\"
+		end"
+
+		bob = Name.new
+		assert_equal("  Bob", bob.to_s)
+	end
+
+	def testFormatter
+		self.class.class_eval "remove_const :FixedDate if const_defined? :FixedDate"
+		self.class.class_eval "class FixedDate < FixedWidthFields
+			field :time, :width => 14, :default => Time.now, 
+						:formatter => FixedWidthFields::DateTimeFormatter
+			end"
+
+		date = FixedDate.new
+		aTime = Time.utc(2000,"jan",1,20,15,01)
+		date.time = aTime
+
+		assert_equal(aTime, date.time)
+		assert_equal("20000101201501", date.to_s)
+	end	
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: FixedWidthFields
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+date: 2006-06-22 00:00:00 +01:00
+summary: Easily create files with fixed-width fields
+require_paths: 
+- lib
+email: norri_b@hotmail.com
+homepage: 
+rubyforge_project: 
+description: The FixedWidthFields library is designed to allow files containing fixed-width fields to be created easily.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Brett Norris
+files: 
+- lib/fixedWidth.rb
+- lib/fixedWidth/base.rb
+- lib/fixedWidth/helpers.rb
+- test/testFixed.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+