format_engine 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f114053c3cff51fcde5ac482b6e27463110adc68
-  data.tar.gz: 0721a2c7c92b65dbcb1f6f410f0dbb759530df8a
+  metadata.gz: bbc14c2d44ed9942c2648f3e96f2599f2328e5fe
+  data.tar.gz: 962a267e81193093a7ba295784dc123154a0f361
 SHA512:
-  metadata.gz: 4ae828117862ee0e38f5b670f4ddeb78b69f1868db1b18978db53dc8b2a97f851cb3ed6c5eca960f53a43ff442fb471e769b743cb7b5e040647883af68680f5d
-  data.tar.gz: 6b613688092373d7eec2d7cf66336a23f9cc8dfe45008f88d0d98a74b4d63486327350700d52a4f742472c4bf465acee477d34c41bad85ff5b5ad8261b82a9f7
+  metadata.gz: 0d4c624e4d34c28a8c2e9bebcbb8960b1a173c5b2c6bc7e72bb7aa7b92ca6b6f40939e044bd16fd994b13198432fa7627992bfa7d8694992c01f86f35573fa56
+  data.tar.gz: 484a63a6acb302edc40f3f9c7240ec087c0f518989994249fad1b4776c20a5fe5994bd80dd69702f21ae490b06a323114a5d7b3186f95ef21bc745af9ccede3a

data/README.md

@@ -21,13 +21,67 @@ Or install it yourself as:
 
 ## Usage
 
-In general formatters and parsers are defined using the attr_formatter
-and attr_parser methods. Both of these methods accept a symbol and a hash of
-strings (plus a few special symbols) that point to blocks (that take no arguments).
+In general the format engine allows for the easy creation of formatters and
+parsers. This is done using the attr_formatter and attr_parser methods that
+work in a manner analogous to attr_reader etc for creating access to instance
+data.
 
-The symbol is the name of a method that is created. The hash forms a library
-of supported formats. Special hash keys are the symbols :before (that is run
-before all other operations) and :after (that is run after all other operations)
+#### attr_formatter
+
+Creates a data formatting facility for the specified class.
+
+_Prerequisites_
+<br>The class must 'extend FormatEngine::AttrFormatter'
+
+_Arguments_
+* method_symbol - the name of the formatter instance method created by this
+method
+* library - a hash mapping specifications to actions (lambda blocks)
+
+_Returns_
+<br>The formatting engine created for the formatter.
+
+_The created instance method_
+<br>This method creates an instance method that provides formatted text from
+an object. This takes the form:
+
+    an_object.method_name(format_string) -> a_formatted_string
+
+#### attr_parse
+
+Creates a data parsing facility for the specified class.
+
+_Prerequisites_
+<br>The class must 'extend FormatEngine::AttrParser'
+
+_Arguments_
+* method_symbol - the name of the parser class method created by this method.
+* library - a hash mapping specifications to actions (lambda blocks)
+
+_Returns_
+<br>The formatting engine created for the parser.
+
+_The created class method_
+<br>This method creates an class method that parses formatted text into a new
+instance of the class. This takes the form:
+
+    AClass.method_name(input_string, format_string) -> an_object
+
+_Extras_
+<br>After the parsing method is completed, the unparsed attribute of the parser
+engine contains the un-processed portion of the input string. If no parsing
+has been performed, this is an empty string.
+
+#### Special entries
+The library has two special entries keyed by symbols instead of strings.
+These are
+
+* :before - references a block that is executed before the formatting or
+parsing process starts.
+* :after - references a block that is executed after the formatting or
+parsing process finishes.
+
+By default, both of these entries take no action.
 
 ### Example
 The following example is found in the mocks folder:
@@ -92,16 +146,17 @@ The parsing of format specification strings is based on the following regular
 expression. This expression is applied repeatedly until all the specifications
 have been extracted from the input string.
 
-    REGEX = %r{(?<lead>  (^|(?<=[^\\]))%){0}
-               (?<flags> [~@#$^&*=?_<>|!]*){0}
+    PARSE_REGEX =
+      %r{(?<lead>  (^|(?<=[^\\]))%){0}
+         (?<flags> [~@#$^&*=?_<>|!]*){0}
 
-               (?<var> \g<lead>\g<flags>[-+]?(\d+(\.\d+)?)?[a-zA-Z]){0}
-               (?<set> \g<lead>\g<flags>(\d+(,\d+)?)?\[([^\]\\]|\\.)+\]){0}
-               (?<rgx> \g<lead>\g<flags>\/([^\\ \/]|\\.)*\/([imx]*)){0}
-               (?<per> \g<lead>%){0}
+         (?<var> \g<lead>\g<flags>[-+]?(\d+(\.\d+)?)?[a-zA-Z]){0}
+         (?<set> \g<lead>\g<flags>(\d+(,\d+)?)?\[([^\]\\]|\\.)+\]){0}
+         (?<rgx> \g<lead>\g<flags>\/([^\\ \/]|\\.)*\/([imx]*)){0}
+         (?<per> \g<lead>%){0}
 
-               \g<var> | \g<set> | \g<rgx> | \g<per>
-              }x
+         \g<var> | \g<set> | \g<rgx> | \g<per>
+        }x
 
 ### Var
 A format specification of the classical form:

data/lib/format_engine/attr_formatter.rb

@@ -1,4 +1,3 @@
-
 module FormatEngine
 
   # This module adds the \attr_formatter extension to a class.
@@ -16,6 +15,8 @@ module FormatEngine
     #* spec_str - A format specification string with %x etc qualifiers.
     #<br>Meta-method Returns
     #* A formatted string
+    #<br>Returns
+    #* The format engine used by this method.
     def attr_formatter(method, library)
       engine = Engine.new(library)
 
@@ -24,6 +25,7 @@ module FormatEngine
         engine.do_format(self, spec_str)
       end
 
+      engine
     end
 
   end

data/lib/format_engine/attr_parser.rb

@@ -17,6 +17,8 @@ module FormatEngine
     #* spec_str - A format specification string with %x etc qualifiers.
     #<br>Meta-method Returns
     #* An instance of the host class.
+    #<br>Returns
+    #* The format engine used by this method.
     def attr_parser(method, library)
       engine = Engine.new(library)
 
@@ -25,6 +27,7 @@ module FormatEngine
         engine.do_parse(src, self, spec_str)
       end
 
+      engine
     end
 
   end

data/lib/format_engine/engine.rb

@@ -6,10 +6,14 @@ module FormatEngine
     #The parse library
     attr_reader :library
 
+    #Any un-parsed string data.
+    attr_reader :unparsed
+
     #Set up base data structures.
     def initialize(library)
       @library = library
       @spec_pool = {}
+      @unparsed = ""
 
       #Set up defaults for pre and post amble blocks.
       nop = lambda { }
@@ -50,6 +54,9 @@ module FormatEngine
       due_process(spec_info, parse_spec_str) do |format|
         spec_info.do_parse(format)
       end
+
+    ensure
+      @unparsed = spec_info.src
     end
 
     private

data/lib/format_engine/format_spec.rb

@@ -29,7 +29,7 @@ module FormatEngine
     #Scan the format string extracting literals and variables.
     def scan_spec(fmt_string)
       until fmt_string.empty?
-        if (match_data = REGEX.match(fmt_string))
+        if (match_data = PARSE_REGEX.match(fmt_string))
           mid = match_data.to_s
           pre = match_data.pre_match
 

data/lib/format_engine/format_spec/parse_regex.rb

@@ -2,15 +2,16 @@ module FormatEngine
 
   #The format string parser.
   class FormatSpec
-    #The regex used to parse variable specifications.
-    REGEX = %r{(?<lead>  (^|(?<=[^\\]))%){0}
-               (?<flags> [~@#$^&*=?_<>|!]*){0}
-               (?<var> \g<lead>\g<flags>[-+]?(\d+(\.\d+)?)?[a-zA-Z]){0}
-               (?<set> \g<lead>\g<flags>(\d+(,\d+)?)?\[([^\]\\]|\\.)+\]){0}
-               (?<rgx> \g<lead>\g<flags>\/([^\\ \/]|\\.)*\/([imx]*)){0}
-               (?<per> \g<lead>%){0}
-               \g<var> | \g<set> | \g<rgx> | \g<per>
-              }x
+    #The regular expression used to parse variable specifications.
+    PARSE_REGEX =
+      %r{(?<lead>  (^|(?<=[^\\]))%){0}
+         (?<flags> [~@#$^&*=?_<>|!]*){0}
+         (?<var> \g<lead>\g<flags>[-+]?(\d+(\.\d+)?)?[a-zA-Z]){0}
+         (?<set> \g<lead>\g<flags>(\d+(,\d+)?)?\[([^\]\\]|\\.)+\]){0}
+         (?<rgx> \g<lead>\g<flags>\/([^\\ \/]|\\.)*\/([imx]*)){0}
+         (?<per> \g<lead>%){0}
+         \g<var> | \g<set> | \g<rgx> | \g<per>
+        }x
    end
 
 end

data/lib/format_engine/version.rb

@@ -1,5 +1,5 @@
 
 module FormatEngine
   # The version of the format_engine gem.
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

data/mocks/demo/demo_format.rb

@@ -6,10 +6,13 @@ class Customer
   ##
   #The specification of the formatter method of the demo \Customer class.
 
-  attr_formatter :strfmt,
+  @formatter_engine = attr_formatter :strfmt,
   {"%a"  => lambda {cat "%#{fmt.width_str}d" % src.age },
    "%f"  => lambda {cat "%#{fmt.width_str}s" % src.first_name },
    "%l"  => lambda {cat "%#{fmt.width_str}s" % src.last_name  }
   }
 
+  class << self
+    attr_reader :formatter_engine
+  end
 end

data/mocks/demo/demo_parse.rb

@@ -6,11 +6,19 @@ class Customer
   ##
   #The specification of the parser method of the demo \Customer class.
 
-  attr_parser :strprs,
-  {"%a"    => lambda { tmp[:age] = found.to_i if parse(/(\d)+/) },
-   "%f"    => lambda { tmp[:fn] = found if parse(/(\w)+/) },
-   "%l"    => lambda { tmp[:ln] = found if parse(/(\w)+/) },
-   :after  => lambda { set dst.new(tmp[:fn], tmp[:ln], tmp[:age]) }
+  @parser_engine = attr_parser :strprs,
+  {"%a"    => lambda { tmp[:age] = found.to_i if parse(/\d+/) },
+   "%f"    => lambda { tmp[:fn] = found.gsub(/_/, ' ') if parse(/\w+/) },
+   "%l"    => lambda { tmp[:ln] = found.gsub(/_/, ' ') if parse(/\w+/) },
+   :after  => lambda do
+                fail  "Customer strprs error, missing field: first name" unless tmp[:fn]
+                fail  "Customer strprs error, missing field: last name" unless tmp[:ln]
+                fail  "Customer strprs error, missing field: age" unless tmp[:age]
+                set dst.new(tmp[:fn], tmp[:ln], tmp[:age])
+              end
   }
 
+  class << self
+    attr_reader :parser_engine
+  end
 end

data/tests/format_engine_tests.rb

@@ -11,6 +11,11 @@ class FormatEngineTester < Minitest::Test
   #Track mini-test progress.
   include MinitestVisible
 
+  def test_that_engines_are_returned
+    assert_equal(FormatEngine::Engine, Customer.formatter_engine.class)
+    assert_equal(FormatEngine::Engine, Customer.parser_engine.class)
+  end
+
   def test_basic_formatting
     cust = Customer.new("Jane", "Doe", 21)
 
@@ -26,4 +31,19 @@ class FormatEngineTester < Minitest::Test
     assert_equal(21, cust.age)
   end
 
+  def test_some_fancy_footwork
+    cust = Customer.strprs("Wernher, von_Braun 104", "%f, %l %a")
+
+    assert_equal(Customer, cust.class)
+    assert_equal("Wernher", cust.first_name)
+    assert_equal("von Braun", cust.last_name)
+    assert_equal(104, cust.age)
+  end
+
+  def test_for_missing_data_detection
+    assert_raises { Customer.strprs("Jane, Doe twenty", "%f, %l %a") }
+    assert_raises { Customer.strprs("Jane", "%f, %l %a") }
+    assert_raises { Customer.strprs("Jane, 34", "%f, %a") }
+  end
+
 end

data/tests/parser_engine_tests.rb

@@ -167,4 +167,18 @@ class ParserTester < Minitest::Test
 
   end
 
+  def test_for_the_unparsed
+    engine = make_parser
+    assert_equal("", engine.unparsed)
+
+    spec = "%f, %l %a"
+    result = engine.do_parse("Squidly, Jones 55 And much more!", TestPerson, spec)
+
+    assert_equal(TestPerson, result.class)
+    assert_equal("Squidly", result.first_name)
+    assert_equal("Jones", result.last_name)
+    assert_equal(" And much more!", engine.unparsed)
+
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: format_engine
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Peter Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-22 00:00:00.000000000 Z
+date: 2016-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler