format_engine 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f68de35267cd2cec34ca42b8638cc5035f64ff42
-  data.tar.gz: d0c21b2ba3cd709f75d9e8e036d5848238abbafa
+  metadata.gz: 53a90dc85e96a48d8f1b469ef5749f63102a4230
+  data.tar.gz: 6555ef6261b11cd7feb5fe996b3e5143d593271b
 SHA512:
-  metadata.gz: 493f6d819bb9c0ceae8eb2c743c5d99a7d0d3fadc537e69e90e540e06c688e3f303a417f5fd8da9174419a8febac8d65ef21209398cc66c27867ee1de325f212
-  data.tar.gz: 25823819e6fc80c713e1f95cfb0fcd25c3b9bf9034cf7eb0755865217a43a77ebbc6ee0a68dc55ceb22225b9ca1bb234b37fb2e6e64d610ce765546a55a0ce00
+  metadata.gz: 9bd665882c88cdb9ed4acb2e6bed688a3b69585630a74425e2fc14e15a098ebb36899dd609d1c5680ffcb89a68c61390ee808dbfb4535837624f4945fa26c636
+  data.tar.gz: a726f4166591fe0683275b35eec562e4d4f9baadbdbe8f14c41e780736add9b38922941e4efedce6ffcc2e853fd3cec9bb5a1b5398d7d0fe32a21e72d88221eb

data/README.md

@@ -21,10 +21,22 @@ 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).
+
+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)
+
+### Example
+The following example is found in the mocks folder:
+
 ```ruby
 require 'format_engine'
 
 #A demo class for the format_engine gem.
+
 class Customer
   extend FormatEngine::AttrFormatter
   extend FormatEngine::AttrParser
@@ -35,10 +47,12 @@ class Customer
   #Demo customer last name
   attr_reader :last_name
 
+  #Demo defn of the strfmt method for formatted string output!
   attr_formatter :strfmt,
   {"%f"  => lambda {cat src.first_name.ljust(fmt.width) },
    "%l"  => lambda {cat src.last_name.ljust(fmt.width)  } }
 
+  #Demo defn of the strprs method for formatted string input!
   attr_parser :strprs,
   {"%f"    => lambda { hsh[:fn] = found if parse(/(\w)+/ ) },
    "%l"    => lambda { hsh[:ln] = found if parse(/(\w)+/ ) },
@@ -63,6 +77,77 @@ agent = Customer.strprs(in_str, "%f, %l")
 #Etc, etc, etc ...
 
 ```
+## Format Specification
+
+Format String Specification Syntax (BNF):
+
+* spec = { text | item }+
+* item = "%" {flag}* {parm {"." parm}?}? {command}
+* flag = { "~" | "@" | "#" | "&" | "^"  |
+  "&" | "*" | "-" | "+" | "="  |
+  "?" | "_" | "<" | ">" | "\\" |
+  "/" | "." | "," | "|" | "!"  }
+* parm = { "0" .. "9" }+
+* command = { "a" .. "z" | "A" .. "Z" }
+
+
+###Sample:
+
+The format specification "Elapsed = %*02H:%M:%5.2S!"
+creates the following format specification array:
+
+```ruby
+[Literal("Elapsed = "),
+ Variable("%*H", ["02"]),
+ Literal("H"),
+ Variable("%M", nil).
+ Literal(":"),
+ Variable("%S", ["5", "2"]),
+ Literal("!")]
+```
+Where literals are processed as themselves and variables are executed by looking
+up the format string in the library and executing the corresponding block.
+
+**Note:** If a format string does not correspond to an entry in the library,
+an exception occurs.
+
+## Formatting / Parsing Blocks
+
+In the context of a formatting / parsing block, the
+"self" of that block is an instance of SpecInfo. The
+components of that object are:
+
+###When Formatting:
+Attributes:
+* src - The object that is the source of the data (RO).
+* dst - A string that receives the formatted output (RO).
+* fmt - The format specification currently being processed (RW).
+* engine - The formatting engine. Mostly for access to the library (RO).
+* hsh - A utility hash so that the formatting process can retain state (RO).
+
+Methods
+* cat - Append the string that follows to the formatted output. This is
+  equivalent to dst << "string"
+
+###When Parsing:
+Attributes:
+* src - A string that is the source of formatted input (RO).
+* dst - The class of the object being created (RO).
+* fmt - The parse specification currently being processed (RW).
+* engine - The parsing engine. Mostly for access to the library (RO).
+* hsh - A utility hash so that the parsing process can retain state RO.
+
+Methods
+* set - Set the return value of the parsing operation to the value that follows.
+* parse - Look for the string or regex parm that follows. Return the data found or nil.
+* parse! - Like parse but raises an exception (with optional msg) if not found.
+* found? - Did the last parse succeed?
+* found - The text found by the last parse (or parse!) operation.
+
+###Format Specifier Attributes
+The format specifier (accessed as fmt above) has the following attributes:
+* width - The width parameter or 0 if not specified.
+* prec - The precision parameter or 0 if not specified.
 
 ## Philosophy
 
@@ -70,7 +155,7 @@ 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.
+that I don't trust.
 
 Feedback on the convenience/clarity balance as well as any other topics are
 most welcomed.

data/lib/format_engine/attr_formatter.rb

@@ -20,9 +20,7 @@ module FormatEngine
       engine = Engine.new(library)
 
       define_method(method) do |spec_str|
-        spec = FormatEngine::FormatSpec.get_spec(spec_str)
-
-        engine.do_format(self, spec)
+        engine.do_format(self, spec_str)
       end
 
     end

data/lib/format_engine/attr_parser.rb

@@ -21,9 +21,7 @@ module FormatEngine
       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)
+        engine.do_parse(src, self, spec_str)
       end
 
     end

data/lib/format_engine/engine.rb

@@ -18,40 +18,48 @@ module FormatEngine
       @lib[index]
     end
 
+    # Set an entry in the library
+    def []=(index, value)
+      @lib[index] = value
+    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)
+    #* format_spec_str - The format specification string.
+    def do_format(src, format_spec_str)
+      spec_info = SpecInfo.new(src, "", nil, self, {})
+
+      due_process(spec_info, format_spec_str) do |fmt|
+        fmt.do_format(spec_info)
+      end
     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)
+    #* parse_spec_str - The format specification string.
+    def do_parse(src, dst, parse_spec_str)
+      spec_info = SpecInfo.new(src, dst, nil, self, {})
+
+      due_process(spec_info, parse_spec_str) do |fmt|
+        fmt.do_parse(spec_info)
+      end
     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 - The state of the process.
+    #* spec_str - The format specification string.
+    #* block - A code block performed for each format specification.
+    def due_process(spec_info, spec_str, &block)
+      spec = FormatSpec.get_spec(spec_str).validate(self)
 
+      spec_info.instance_exec(&self[:before])
+      spec.specs.each(&block)
       spec_info.instance_exec(&self[:after])
+
       spec_info.dst
     end
 

data/lib/format_engine/version.rb

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

data/tests/formatter_engine_tests.rb

@@ -28,7 +28,7 @@ class FormatterTester < Minitest::Test
   end
 
   def make_spec(str)
-    FormatEngine::FormatSpec.get_spec str
+    str
   end
 
   def make_all(str)
@@ -60,7 +60,7 @@ class FormatterTester < Minitest::Test
       :before => lambda {dst << "((" },
       :after  => lambda {dst << "))" })
 
-    spec = FormatEngine::FormatSpec.get_spec "Test"
+    spec = "Test"
     assert_equal("((Test))", engine.do_format(nil, spec))
   end
 
@@ -68,4 +68,14 @@ class FormatterTester < Minitest::Test
     engine, obj, spec = make_all("Name = %f %j")
     assert_raises(RuntimeError) { engine.do_format(obj, spec) }
   end
+
+  def test_that_it_validates_before_before
+    engine, obj, spec = make_all("Name = %f %j")
+    test = 1
+    engine[:before] = lambda { test = 2 }
+
+    assert_raises(RuntimeError) { engine.do_format(obj, spec) }
+    assert_equal(1, test)
+  end
+
 end

data/tests/parser_engine_tests.rb

@@ -29,7 +29,7 @@ class ParserTester < Minitest::Test
 
   def test_that_it_can_parse
     engine = make_parser
-    spec = FormatEngine::FormatSpec.get_spec "%f, %l"
+    spec = "%f, %l"
     result = engine.do_parse("Squidly, Jones", TestPerson, spec)
 
     assert_equal(TestPerson, result.class)
@@ -39,7 +39,7 @@ class ParserTester < Minitest::Test
 
   def test_that_it_can_parse_loudly
     engine = make_parser
-    spec = FormatEngine::FormatSpec.get_spec "%F, %L"
+    spec =  "%F, %L"
     result = engine.do_parse("Squidly, Jones", TestPerson, spec)
 
     assert_equal(TestPerson, result.class)
@@ -49,7 +49,7 @@ class ParserTester < Minitest::Test
 
   def test_that_it_can_fix_shouting
     engine = make_parser
-    spec = FormatEngine::FormatSpec.get_spec "%-F, %-L"
+    spec =  "%-F, %-L"
     result = engine.do_parse("SQUIDLY, JONES", TestPerson, spec)
 
     assert_equal(TestPerson, result.class)
@@ -59,7 +59,7 @@ class ParserTester < Minitest::Test
 
   def test_that_it_can_flex_parse
     engine = make_parser
-    spec = FormatEngine::FormatSpec.get_spec "%f%,s%l"
+    spec =  "%f%,s%l"
     result = engine.do_parse("Squidly, Jones", TestPerson, spec)
 
     assert_equal(TestPerson, result.class)
@@ -69,7 +69,7 @@ class ParserTester < Minitest::Test
 
   def test_that_it_can_tab_parse
     engine = make_parser
-    spec = FormatEngine::FormatSpec.get_spec "%f%t%l"
+    spec =  "%f%t%l"
     result = engine.do_parse("Squidly\tJones", TestPerson, spec)
 
     assert_equal(TestPerson, result.class)
@@ -79,13 +79,13 @@ class ParserTester < Minitest::Test
 
   def test_that_it_can_detect_errors
     engine = make_parser
-    spec = FormatEngine::FormatSpec.get_spec "%f, %l"
+    spec =  "%f, %l"
 
     assert_raises(RuntimeError) do
       engine.do_parse("Squidly Jones", TestPerson, spec)
     end
 
-    spec = FormatEngine::FormatSpec.get_spec "%f%!t%l"
+    spec =  "%f%!t%l"
 
     assert_raises(RuntimeError) do
       engine.do_parse("Squidly Jones", TestPerson, spec)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: format_engine
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Peter Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-28 00:00:00.000000000 Z
+date: 2015-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler