format_engine 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f68de35267cd2cec34ca42b8638cc5035f64ff42
+  data.tar.gz: d0c21b2ba3cd709f75d9e8e036d5848238abbafa
+SHA512:
+  metadata.gz: 493f6d819bb9c0ceae8eb2c743c5d99a7d0d3fadc537e69e90e540e06c688e3f303a417f5fd8da9174419a8febac8d65ef21209398cc66c27867ee1de325f212
+  data.tar.gz: 25823819e6fc80c713e1f95cfb0fcd25c3b9bf9034cf7eb0755865217a43a77ebbc6ee0a68dc55ceb22225b9ca1bb234b37fb2e6e64d610ce765546a55a0ce00

data/.gitignore

@@ -0,0 +1,23 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+docs/.~lock.*
+*.bat
+*.zip
+*.tmp
+rdoc
+test/tmp
+test/version_tmp
+tmp
+temp.txt

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in format_engine.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Peter Camilleri
+
+MIT License
+
+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,84 @@
+# FormatEngine
+
+The FormatEngine gem contains the common support code needed to support
+string formatting and parsing routines like strftime and strptime.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'format_engine'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install format_engine
+
+## Usage
+
+```ruby
+require 'format_engine'
+
+#A demo class for the format_engine gem.
+class Customer
+  extend FormatEngine::AttrFormatter
+  extend FormatEngine::AttrParser
+
+  #Demo customer first name.
+  attr_reader :first_name
+
+  #Demo customer last name
+  attr_reader :last_name
+
+  attr_formatter :strfmt,
+  {"%f"  => lambda {cat src.first_name.ljust(fmt.width) },
+   "%l"  => lambda {cat src.last_name.ljust(fmt.width)  } }
+
+  attr_parser :strprs,
+  {"%f"    => lambda { hsh[:fn] = found if parse(/(\w)+/ ) },
+   "%l"    => lambda { hsh[:ln] = found if parse(/(\w)+/ ) },
+   :after  => lambda { set dst.new(hsh[:fn], hsh[:ln]) } }
+
+  #Create an instance of the demo customer.
+  def initialize(first_name, last_name)
+    @first_name, @last_name = first_name, last_name
+  end
+end
+
+#Then later in the code...
+
+cust = Customer.new("Jane", "Doe")
+puts cust.strfmt("%f, %l"))  #"Jane, Doe"
+
+#And elsewhere in Gotham City...
+
+in_str = "Jane, Doe"
+agent = Customer.strprs(in_str, "%f, %l")
+
+#Etc, etc, etc ...
+
+```
+
+## Philosophy
+
+When designing this gem, a concerted effort has been applied to keeping it as
+simple as possible. To this end, many subtle programming techniques have been
+avoided in favor of simpler, more obvious approaches. This is based on the
+observation that I don't trust code that I don't understand and I avoid code
+I don't trust.
+
+Feedback on the convenience/clarity balance as well as any other topics are
+most welcomed.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/format_engine/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,55 @@
+#!/usr/bin/env rake
+# coding: utf-8
+
+require 'rake/testtask'
+require 'rdoc/task'
+require 'bundler/gem_tasks'
+
+#Generate internal documentation with rdoc.
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+
+  #List out all the files to be documented.
+  rdoc.rdoc_files.include("lib/**/*.rb", "mocks/**/demo*.rb", "license.txt", "README.md")
+
+  #Make all access levels visible.
+  rdoc.options << '--visibility' << 'private'
+  #rdoc.options << '--verbose'
+  #rdoc.options << '--coverage-report'
+
+  #Set a title.
+  rdoc.options << '--title' << 'fOOrth Language Internals'
+
+end
+
+#Run the format_engine unit test suite.
+Rake::TestTask.new do |t|
+  #List out all the test files.
+  t.test_files = FileList['tests/**/*.rb']
+  t.verbose = false
+end
+
+desc "Run a scan for smelly code!"
+task :reek do |t|
+  `reek --no-color lib > reek.txt`
+end
+
+desc "Run an IRB Session with format_engine loaded."
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require './lib/format_engine'
+  puts "Starting an IRB console with format_engine."
+  puts "Use 'quit' to exit."
+  puts
+  ARGV.clear
+  IRB.start
+end
+
+desc "What version of code is this?"
+task :vers do |t|
+  puts
+  puts "format_engine version = #{FormatEngine::VERSION}"
+end
+
+

data/format_engine.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'format_engine/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "format_engine"
+  spec.version       = FormatEngine::VERSION
+  spec.authors       = ["Peter Camilleri"]
+  spec.email         = ["peter.c.camilleri@gmail.com"]
+  spec.summary       = %q{An engine for string formatting and parsing.}
+  spec.description   = %q{An engine for string formatting and parsing like the strftime and strptime methods.}
+  spec.homepage      = "http://teuthida-technologies.com/"
+  spec.license       = "MIT"
+
+  raw_list           = `git ls-files`.split($/)
+  spec.files         = raw_list.keep_if {|entry| !entry.start_with?("docs") }
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'minitest', "~> 5.5.1"
+  spec.add_development_dependency 'minitest_visible', "~> 0.0.1"
+  spec.add_development_dependency 'rdoc', "~> 4.0.1"
+end

data/format_engine.reek

@@ -0,0 +1,109 @@
+---
+Attribute:
+  enabled: false
+  exclude: []
+BooleanParameter:
+  enabled: true
+  exclude: []
+ClassVariable:
+  enabled: true
+  exclude: []
+ControlParameter:
+  enabled: true
+  exclude: []
+DataClump:
+  enabled: true
+  exclude: []
+  max_copies: 2
+  min_clump_size: 2
+DuplicateMethodCall:
+  enabled: true
+  exclude: []
+  max_calls: 1
+  allow_calls: []
+FeatureEnvy:
+  enabled: true
+  exclude: []
+IrresponsibleModule:
+  enabled: true
+  exclude: []
+LongParameterList:
+  enabled: true
+  exclude: []
+  max_params: 3
+  overrides:
+    initialize:
+      max_params: 5
+LongYieldList:
+  enabled: true
+  exclude: []
+  max_params: 3
+NestedIterators:
+  enabled: true
+  exclude: []
+  max_allowed_nesting: 1
+  ignore_iterators: []
+NilCheck:
+  enabled: true
+  exclude: []
+PrimaDonnaMethod:
+  enabled: true
+  exclude: []
+RepeatedConditional:
+  enabled: true
+  exclude: []
+  max_ifs: 2
+TooManyInstanceVariables:
+  enabled: true
+  exclude: []
+  max_instance_variables: 9
+TooManyMethods:
+  enabled: true
+  exclude: []
+  max_methods: 25
+TooManyStatements:
+  enabled: true
+  exclude:
+  - initialize
+  max_statements: 7
+UncommunicativeMethodName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^[a-z]$/
+  - !ruby/regexp /[0-9]$/
+  - !ruby/regexp /[A-Z]/
+  accept: []
+UncommunicativeModuleName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^.$/
+  - !ruby/regexp /[0-9]$/
+  accept:
+  - Inline::C
+UncommunicativeParameterName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^.$/
+  - !ruby/regexp /[0-9]$/
+  - !ruby/regexp /[A-Z]/
+  - !ruby/regexp /^_/
+  accept: []
+UncommunicativeVariableName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^.$/
+  - !ruby/regexp /[0-9]$/
+  - !ruby/regexp /[A-Z]/
+  accept:
+  - _
+UnusedParameters:
+  enabled: true
+  exclude: []
+UtilityFunction:
+  enabled: true
+  exclude: []
+  max_helper_calls: 1

data/lib/format_engine/attr_formatter.rb

@@ -0,0 +1,32 @@
+
+module FormatEngine
+
+  # This module adds the \attr_formatter extension to a class.
+  module AttrFormatter
+
+    #Define a formatter for instances of the current class.
+    #<br>Parameters
+    #* method - A symbol used to name the formatting method created by this method.
+    #* library - A hash of formatting rules that define the formatting
+    #  capabilities supported by this formatter.
+    #<br>Meta-effects
+    #* Creates a method (named after the symbol in method) that formats the
+    #  instance of the class. The created method takes one parameter:
+    #<br>Meta-method Parameters
+    #* spec_str - A format specification string with %x etc qualifiers.
+    #<br>Meta-method Returns
+    #* A formatted string
+    def attr_formatter(method, library)
+      engine = Engine.new(library)
+
+      define_method(method) do |spec_str|
+        spec = FormatEngine::FormatSpec.get_spec(spec_str)
+
+        engine.do_format(self, spec)
+      end
+
+    end
+
+  end
+
+end

data/lib/format_engine/attr_parser.rb

@@ -0,0 +1,33 @@
+module FormatEngine
+
+  # This module adds the \attr_parser extension to a class.
+  module AttrParser
+
+    #Define a parser for the current class.
+    #<br>Parameters
+    #* method - A symbol used to name the parsing method created by this method.
+    #* library - A hash of parsing rules the define the parsing
+    #  capabilities supported by this parser.
+    #<br>Meta-effects
+    #* Creates a class method (named after the symbol in method) that parses in
+    #  a string and creates an instance of the class. The created method takes
+    #  two parameters:
+    #<br>Meta-method Parameters
+    #* src - A string of formatted data to be parsed.
+    #* spec_str - A format specification string with %x etc qualifiers.
+    #<br>Meta-method Returns
+    #* An instance of the host class.
+    def attr_parser(method, library)
+      engine = Engine.new(library)
+
+      define_singleton_method(method) do |src, spec_str|
+        spec = FormatEngine::FormatSpec.get_spec(spec_str)
+
+        engine.do_parse(src, self, spec)
+      end
+
+    end
+
+  end
+
+end

data/lib/format_engine/engine.rb

@@ -0,0 +1,59 @@
+module FormatEngine
+
+  # The engine class of the format engine.
+  class Engine
+
+    #Set up base data structures.
+    def initialize(library)
+      @lib = library
+
+      #Set up defaults for pre and post amble blocks.
+      nop = lambda { }
+      @lib[:before] ||= nop
+      @lib[:after]  ||= nop
+    end
+
+    # Get an entry from the library
+    def [](index)
+      @lib[index]
+    end
+
+    #Do the actual work of building the formatted output.
+    #<br>Parameters
+    #* src - The source object being formatted.
+    #* format_spec - The format specification.
+    def do_format(src, format_spec)
+      due_process(src, "", format_spec, :do_format)
+    end
+
+    #Do the actual work of parsing the formatted input.
+    #<br>Parameters
+    #* src - The source string being parsed.
+    #* dst - The class of the object being created.
+    #* format_spec - The format specification.
+    def do_parse(*args)
+      due_process(*args, :do_parse)
+    end
+
+    #Do the actual work of parsing the formatted input.
+    #<br>Parameters
+    #* src - The input to the process.
+    #* dst - The output of the process.
+    #* format_spec - The format specification.
+    #* sym - The symbol applied to each format specification.
+    #<br>Endemic Code Smells
+    #* :reek:LongParameterList
+    def due_process(src, dst, format_spec, sym)
+      spec_info = SpecInfo.new(src, dst, nil, self, {})
+      spec_info.instance_exec(&self[:before])
+
+      format_spec.validate(self).specs.each do |fmt|
+        fmt.send(sym, spec_info)
+      end
+
+      spec_info.instance_exec(&self[:after])
+      spec_info.dst
+    end
+
+  end
+end

data/lib/format_engine/format_spec/literal.rb

@@ -0,0 +1,36 @@
+module FormatEngine
+
+  # A format engine literal specification.
+  class FormatLiteral
+
+    # The literal text of this literal specification.
+    attr_reader :literal
+
+    # Set up a literal format specification.
+    def initialize(literal)
+      @literal = literal
+    end
+
+    # Is this literal supported by the engine? YES!
+    def validate(_engine)
+      self
+    end
+
+    # Format onto the output string
+    def do_format(spec_info)
+      spec_info.dst << @literal
+    end
+
+    # Parse from the input string
+    def do_parse(spec_info)
+      spec_info.parse!(literal)
+    end
+
+    # Inspect for debugging.
+    def inspect
+      "Literal(#{literal.inspect})"
+    end
+
+  end
+
+end

data/lib/format_engine/format_spec/variable.rb

@@ -0,0 +1,64 @@
+module FormatEngine
+
+  # A format engine variable specification.
+  class FormatVariable
+
+    # The fixed part of this variable specification.
+    attr_reader :format
+
+    # The (optional) numeric format parameters.
+    attr_reader :parms
+
+    # Setup a variable format specification.
+    def initialize(format)
+      if format =~ /(\d+(\.\d+)?)/
+        @format = $PREMATCH + $POSTMATCH
+
+        if (digits = $MATCH) =~ /\./
+          @parms = [$PREMATCH, $POSTMATCH]
+        else
+          @parms = [digits]
+        end
+
+      else
+        @parms  = nil
+        @format = format
+      end
+    end
+
+    # Is this variable supported by the engine?
+    def validate(engine)
+      fail "Unsupported tag = #{format.inspect}" unless engine[format]
+      self
+    end
+
+    # Get the width parameter.
+    def width
+      parms ? parms[0].to_i : 0
+    end
+
+    # Get the precision parameter.
+    def prec
+      (parms && parms.length > 1) ? parms[1].to_i : 0
+    end
+
+    # Format onto the output string
+    def do_format(spec_info)
+      spec_info.fmt = self
+      spec_info.instance_exec(&spec_info.engine[self.format])
+    end
+
+    # Parse from the input string
+    def do_parse(spec_info)
+      spec_info.fmt = self
+      spec_info.instance_exec(&spec_info.engine[self.format])
+    end
+
+    # Inspect for debugging.
+    def inspect
+      "Variable(#{format.inspect}, #{parms.inspect})"
+    end
+
+  end
+
+end

data/lib/format_engine/format_spec.rb

@@ -0,0 +1,61 @@
+require_relative 'format_spec/literal'
+require_relative 'format_spec/variable'
+
+# Format String Specification Syntax (BNF):
+#  spec = { text | item }+
+#  item = "%" {flag}* {parm {"." parm}?}? {command}
+#  flag = { "~" | "@" | "#" | "&" | "^"  |
+#           "&" | "*" | "-" | "+" | "="  |
+#           "?" | "_" | "<" | ">" | "\\" |
+#           "/" | "." | "," | "|" | "!"  }
+#  parm = { "0" .. "9" }+
+#  command = { "a" .. "z" | "A" .. "Z" }
+#  Sample: x = FormatSpec.get_spec "Elapsed = %*03.1H:%M:%S!"
+
+module FormatEngine
+
+  #The format string parser.
+  class FormatSpec
+    #Don't use new, use get_spec instead.
+    private_class_method :new
+
+    #Either get a format specification from the pool or create one.
+    def self.get_spec(fmt_string)
+      @spec_pool ||= {}
+      @spec_pool[fmt_string] ||= new(fmt_string)
+    end
+
+    #The array of specifications that were extracted.
+    attr_reader :specs
+
+    #Set up an instance of a format specification.
+    #<br>Note
+    #This is a private method (rdoc gets it wrong). To create new instances of
+    #\FormatSpec do not use \FormatSpec.new, but use \FormatSpec.get_spec instead.
+    def initialize(fmt_string)
+      @specs = []
+      scan_spec(fmt_string)
+    end
+
+    #Scan the format string extracting literals and variables.
+    def scan_spec(fmt_string)
+      until fmt_string.empty?
+        if fmt_string =~ /%[~@#$^&*\-+=?_<>\\\/\.,\|!]*(\d+(\.\d+)?)?[a-zA-Z]/
+          @specs << FormatLiteral.new($PREMATCH) unless $PREMATCH.empty?
+          @specs << FormatVariable.new($MATCH)
+          fmt_string  =  $POSTMATCH
+        else
+          @specs << FormatLiteral.new(fmt_string)
+          fmt_string = ""
+        end
+      end
+    end
+
+    #Validate the specs of this format against the engine.
+    def validate(engine)
+      specs.each {|item| item.validate(engine)}
+      self
+    end
+
+  end
+end