fancy_writer 1.0.0 → 1.0.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OTIxMzllODc0MzhhMzM0M2Y0YWI0ZDFiYzAzMmQyZWI5NjhlMDQ1Ng==
+    MmRkNGEyOWE1NGM5MjNiNWQzMGI5NmQ0YzVlMWNiYmMzZGNmZTdkMw==
   data.tar.gz: !binary |-
-    YmM5NjZjMWNhY2ZhMzJhNWQxZjQwMjI4OTkwZjg0ZmQ0ZGZjZGY5YQ==
+    YTg5OTRjNjg5MjQxNDkwYTJhOTU0M2Y2YWFlOWQ5ZWRlMWI4NjFmNw==
 SHA512:
   metadata.gz: !binary |-
-    ZGZiMTM3NDk4MzkxMTYzNGQyOTBmMzkzMzkwODcyNGFlMmM0OTY4ZTc4MWFl
-    NmMzY2VhZjQ5NjVhYjEyNjg1ZmYxYmM3Yjk2YzE2OGQ1NzVmNWM3ZTc5NmEx
-    ZGE3MWJjYzk4YjI4YmFjZjVjMDUzYTA2NjRjYzIzNTA1Mzg5MWI=
+    M2Q5NTMyNzUxN2RhYzEwZTljZTczNWY4YjY2ODVjZjA0NGI4MGE4MDE0YTA2
+    YWUwMDA1OGQ0ZWY0ZmUyNGNkMGQ2MDU2MjVlNGE0MzEzMjk5MjIwN2FmNjMy
+    NjgxNzQzMThhNGY3NmMwNWRiM2EyOTBhOGI1OTc0OWEzNDAyNGQ=
   data.tar.gz: !binary |-
-    YjU1MjIzNjE0ZTgwYjM5ZjAxMGIyODM5MjRjNmQzMGNhYmNiYjQ0Yzg2NmUy
-    OTI3MjQyMjMyOGVlNjg3MWE1OWZlOGU3MDY5MTM1OTkzY2MyYzUxYzg5ODRl
-    ODllN2Q4NDEwMjBkNTIxMjg5NTFhMzJkMTA3MWZlZmJlYTg4MTA=
+    OTU0YTBlMDMzY2JhYTA5MTI1YmZkNTlhYTYxMWU5ZDJhZTFmMWFlNDcyYTM5
+    YTgxZjE0MjFmMjIwMTQxZDE3NDgyYmFkNGIyYWFiYWJkNzlhYjczNGUzNGJh
+    NDBjNjZhMzM4MWEzYzFlNDIzODkyM2QzMWM3YmI0OThjYWM3NDg=

data/README.md

@@ -27,9 +27,9 @@ Or install it yourself as:
 
     $ gem install fancy_writer
 
-## Usage
+## Basic usage
 
-### Basic usage and writing lines
+### Writing lines
 
 Given an IO object that is suitable for writing (such as a file or stdout),
 FancyWriter can use this IO object for creating formatted output:
@@ -167,6 +167,50 @@ end
           Additionally, eight spaces.
 ````
 
+### Blocks
+
+With "blocks" I refer to segments of text that have one single line that begins it and one line that ends it, and an additional body in between. Often, this
+body is indented. The following three-line samples show different examples of
+such blocks from different languages. Each first line is the beginning of a
+block, each second line its body, each third line its ending:
+
+```` HTML
+<div>
+  <p>Lorem ipsum dolor sit amet...</p>
+</div>
+````
+```` Latex
+\begin{section}
+  Lorem ipsum dolor sit amet...
+\end{section}
+````
+```` Bibtex
+@article{User1999,
+  author = {Joe User}
+}
+````
+
+FancyWriter provides the `block` method (shortcut: `b`) to ease the process
+of creating such blocks. This method expects two or three parameters and a
+block. The first two parameters indicate the beginning and ending line, 
+respectively. The third parameter is optional, it indicates the number of
+spaces to be used for indentation (its default is 2 spaces).
+
+So, the first example above (the HTML one) can be produced with FancyWriter
+as follows:
+
+```` Ruby
+FancyWriter::FancyIO.new(io) do
+  block '<div>', '</div>' do
+    line '<p>Lorem ipsum dolor sit amet...</p>'
+  end
+end
+````
+
+While this feature in general does not appear to be very helpful, it can
+be used in combination with custom patterns (see below) to produce blocks
+dynamically. 
+
 ### Symbol-separated values
 
 If you pass an Enumerable to `write_enum` (short version: `e`), the underlying
@@ -201,7 +245,7 @@ Note that also for this method, surrounding `comment` or indentation methods
 are evaluated, meaning that also formatted number sequences will be indented
 or commented out.
 
-## An exhaustive example
+## An exhaustive example of basic usage
 
 This is a somewhat artifical example, but it contains most of the methods
 in action.
@@ -242,6 +286,114 @@ config:
         5,6,7,8
 ````
 
+## Advanced usage 
+
+### Custom line patterns
+
+If you are working with file formats that use repeated patterns (usually
+resulting from the language used), you can make your work even easier
+by defining *named patterns*. These are basically strings with some
+placeholders in them, which you can use to generate lines where these
+placeholders are substituted with parameters.
+
+With the possibility to generate named patterns, you can create your
+own small DSL for the file format you are working with. This can
+save time and make your code more legible.
+
+Let me give an example with the following segment of an Apache configuration
+file (let us further assume that you somehow need to generate these
+config files in your Ruby scripts from some source):
+
+```` conf
+User wwwrun
+Listen 80
+DocumentRoot "/srv/www/htdocs"
+LoadModule cgi_module modules/mod_cgi.so
+LoadModule mime_module modules/mod_mime.so
+LoadModule negotiation_module modules/mod_negotiation.so
+LoadModule status_module modules/mod_status.so
+````
+
+Two things are important here: this configuration file follows a predefined syntax, and there are elements that repeat themselves. For these, you could define named patterns which serve several purposes: You do not need to spell out the complete line, you avoid repetition of formatting, and you can reduce errors. If you look at the end of the sample, you see many similar lines. If you define one pattern for them, you follow the DRY principle, you reduce the number of places to look for if a bug occurs, and you get a cleaner way of generating the file contents.
+
+If you want to use named patterns, you need to delay the calling of the formatting method, because you need to insert the configuration fist. Thus, you do not call the formatting method directly on the newly created object  as in the examples above, or like this:
+
+```` Ruby
+FancyWriter::FancyIO.new(io) do
+  # calls to line, block, comment, etc.
+end
+````
+
+Instead, you assign the FancyWriter instance to a variable, perform the configuration, and finally call `convert` on the instance and give it a block with your formatting wishes:
+
+```` Ruby
+@writer = FancyWriter::FancyIO.new(io)
+# Do your named pattern configuration here
+@writer.add_line_config :load_module, "LoadModule %module modules/%file.so")
+@writer.convert do
+  # NOW, we can start writing!
+  # insert your calls to line, block, comment, etc.
+end
+````
+
+In this example, you can see how a named pattern can be inserted using the
+`add_line_config` method. It expects a symbol (containing the name of the pattern) and the pattern itself. The symbol should follow the rules for method names in Ruby. You will see why in a few moments. 
+
+The named pattern follows a convention similar to the one used for the `sprintf` string formatting. The difference is that *names* are used, such as `%method`. These names will, during text generation, be replaced with matching values from the hash passed to your custom line method. Thus, if you pass a hash containing the entry `method: "mime"`, then all occurrences of `%method` in that pattern will be replaced with `mime`. Literal `%` characters can be expressed by doubling them in the pattern: `%%`.
+
+The pattern defined above basically inserts a line starting with 'LoadModule', and then a formatting of two parameters that you can give it during calling. You will be able to call this named pattern as if you call the pattern name as a method (that's why the pattern name should follow these rules).
+
+You can generate the four module configurations from the example with this code:
+
+```` Ruby
+@writer = FancyWriter::FancyIO.new(io)
+# Do your named pattern configuration here
+@writer.add_line_config :load_module, "LoadModule %module modules/%file.so"
+@writer.convert do
+  load_module module: 'cgi_module', file: 'mod_cgi'
+  load_module module: 'mime_module', file: 'mod_mime'
+  load_module module: 'negotiation_module', file: 'mod_negotiation'
+  load_module module: 'status_module', file: 'mod_status'
+end
+````
+
+In a similar fashion, you could add patterns for the other lines in the configuration file. 
+
+### Custom block patterns
+
+Similar to this, you can also add patterns that create custom blocks. In these blocks, the beginning *and* ending text will be interpolated with the values you pass to the block. The functionality is similar to the one used for custom line patterns, with the following exceptions:
+
+You configure a new block as follows:
+```` Ruby
+@writer.add_block_config block_name, begin_pattern, end_pattern, indentation
+````
+
+- `block_name` is the symbol to be used for the method call.
+- `begin_pattern` and `end_pattern` are patterns for the strings that you want to use to surround your block. Here, you can add `%field` definitions in places where you want to put a variable value.
+- `indentation` declares the number of spaces to use for block indentation.
+
+The difference in calling a block pattern is that you pass a (Ruby) block to it that contains rules for creating the body of the block:
+
+```` Ruby
+@writer.add_block_config :xml_tag, '<%tagname>', '</%tagname>', 2
+@writer.convert do1
+  xml_tag tagname: 'div' do
+    xml_tag tagname: 'p' do 
+      line 'Hello world!'
+    end
+  end
+end
+````
+thus produces
+````XML
+<div>
+  <p>
+    Hello World!
+  </p>
+</div>
+````
+
+*(Of course there are dozens of better and more efficient ways to actually output XML, this is supposed to be just a comprehensible example.)*
 
 ## Issues
 
@@ -275,6 +427,27 @@ ideally by creating an issue on Github.
 
 Please browse existing issues first, to avoid double postings.
 
+## Release history
+
+### 1.0.2 – named pattern support (6 Feb 2015)
+
+- __[#4](https://github.com/pmenke/fancy_writer/issues/4) implemented.__
+Adds support for custom line patterns
+- __[#2](https://github.com/pmenke/fancy_writer/issues/2) implemented.__
+Adds support for custom block patterns
+
+
+### 1.0.1 – block support (6 Feb 2015)
+
+- __[#1](https://github.com/pmenke/fancy_writer/issues/1) implemented.__
+Adds support for blocks
+- __[#3](https://github.com/pmenke/fancy_writer/issues/3) implemented.__
+Minor code improvements
+
+### 1.0.0 – initial version (28 Mar 2014)
+
+- First version of the gem, basic support for lines, comments, indentation.
+
 ## Contributing
 
 Any ideas are welcome!  Either

data/lib/fancy_writer.rb

@@ -25,6 +25,13 @@ module FancyWriter
   # See README.md for an exhaustive usage description.
   class FancyIO
 
+    def self.interpol(string, args)
+      result = string.gsub(/(?<!%)%(\w+)/) do
+        args.has_key?($1.to_sym) ? args[$1.to_sym] : ''
+      end
+      result.gsub(/%%/, '%')
+    end
+
     # This hash holds some default options that are used when
     # no other options are passed to the constructor.
     DEFAULT_OPTIONS = {
@@ -47,6 +54,11 @@ module FancyWriter
     # An attribute holding the caller object.
     attr_reader :caller
 
+    # An attribute holding custom line configurations.
+    attr_reader :custom_lines
+    
+    attr_reader :custom_blocks
+    
 
     # Initializes a new fancy writer instance that wraps
     # around the given io object +p_stream+.
@@ -67,6 +79,8 @@ module FancyWriter
     def initialize(p_stream, opts={}, &block)
       @stream = p_stream
       @prefix_stack = []
+      @custom_lines = Hash.new
+      @custom_blocks = Hash.new
       effective_opts = DEFAULT_OPTIONS.merge(opts)
       @enum_separator = effective_opts[:enum_separator]
       @enum_quote = effective_opts[:enum_quote]
@@ -76,6 +90,30 @@ module FancyWriter
       end
     end
 
+    # Takes the given block and uses it to convert data. This
+    # method is useful if you want to do things to your
+    # FancyWriter object after initialization.
+    # @param @block   [Block] A block containing the
+    #                         fancy writer code.
+    def convert(&block)
+      if block_given?
+        instance_eval &block
+      end
+    end
+    
+    # # # # # # # # # # # # # # # # # #
+    # Further setup of the object
+    # # # # # # # # # # # # # # # # # #
+
+    # Adds a new custom line configuration to the object.
+    def add_line_config(name, pattern)
+      @custom_lines[name.to_sym] = pattern
+    end
+    
+    def add_block_config(name, begin_pattern, end_pattern, indentation=2)
+      @custom_blocks[name.to_sym] = [ begin_pattern, end_pattern, indentation ]
+    end
+    
     # Adds a new string to the prepend stack. These strings
     # will be added to each output line until the end of the
     # block is reached.
@@ -140,6 +178,13 @@ module FancyWriter
       write_line(p_enum)
     end
 
+    def block(prefix, postfix, indentation=2, &block)
+      line prefix
+      indent indentation, &block
+      line postfix                
+    end
+      
+
     # Adds an alias +w+ for the +write+ method.
     alias :w    :write
 
@@ -158,6 +203,9 @@ module FancyWriter
     # Adds an alias +e+ for the +write_enum+ method.
     alias :e :write_enum
 
+    # Adds an alias +b+ for the +block+ method.
+    alias :b :block
+
 
     private
 
@@ -166,10 +214,18 @@ module FancyWriter
     # user with method calls inside FancyWriter's blocks.
     def method_missing(meth, *args, &block)
       if caller.respond_to?(meth)
-        caller.send(meth, *args, &block)
-      else
-        super
+        return caller.send(meth, *args, &block)
+      end
+      if @custom_lines.has_key?(meth)
+        evaluated_pattern = FancyIO.interpol(@custom_lines[meth],args.first)
+        return line(evaluated_pattern)
+      end
+      if @custom_blocks.has_key?(meth)
+        evaluated_begin = FancyIO.interpol(@custom_blocks[meth][0], args.first)
+        evaluated_end   = FancyIO.interpol(@custom_blocks[meth][1], args.first)
+        return block(evaluated_begin, evaluated_end, @custom_blocks[meth][2], &block)
       end
+      return super
     end
 
     # Internal method that performs the actual writing.
@@ -182,7 +238,9 @@ module FancyWriter
       else
         formatted_line = line.to_s
       end
-      stream << "%s%s%s" %[@prefix_stack.join(''),formatted_line,"\n"]
+      stream << @prefix_stack.join('')
+      stream << formatted_line
+      stream << "\n"
     end
 
     # Joins together an enumerable, using configuration options

data/lib/fancy_writer/version.rb

@@ -22,5 +22,5 @@
 # See README.md for usage details.
 module FancyWriter
   # The current version of the library.
-  VERSION = "1.0.0"
+  VERSION = "1.0.2"
 end

data/spec/fancy_writer/custom_lines_spec.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+# This file is part of the fancy_writer gem.
+# Copyright (c) 2014 Peter Menke.
+# http://www.petermenke.de
+#
+# fancy_writer is free software: you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation, either
+# version 3 of the License, or (at your option) any later version.
+#
+# fancy_writer is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with fancy_writer. If not, see
+# <http://www.gnu.org/licenses/>.
+require 'spec_helper'
+
+include FancyWriter
+
+describe FancyWriter::FancyIO do
+
+  before(:each) do
+    @string = String.new
+    @writer = FancyIO.new(@string) 
+  end
+  
+  context 'Custom lines' do
+    
+    it 'can store custom line configurations' do
+      @writer.add_line_config(:custom, "Hi %s")
+      @writer.custom_lines.should_not be nil
+    end  
+
+    it 'stores correct info for custom line configurations' do
+      @writer.add_line_config(:custom, "Hi %s")
+      @writer.custom_lines.has_key?(:custom).should be true
+      @writer.custom_lines[:custom].should eq "Hi %s"
+    end  
+    
+    it 'uses a stored line to produce correct output' do
+      @writer.add_line_config(:custom, "Hi %who")
+      @writer.convert do
+        custom who: 'ho'
+      end
+      @string.should eq "Hi ho\n"
+    end
+    
+    it 'converts also multi-value, complex patterns' do
+      @writer.add_line_config :load_module, "LoadModule %module modules/%file.so"
+      @writer.convert do
+        load_module module: 'mime_module', file: 'mod_mime'
+      end
+      @string.should eq "LoadModule mime_module modules/mod_mime.so\n"
+      puts @string
+    end
+    
+    it 'converts patterns with special characters' do
+      @writer.add_line_config :node, "\\node at (%x,%y) (%name) {%label};"
+      @writer.convert do
+        node x: 4, y: 2, name: 'node1', label: 'Source'
+      end
+      @string.should eq "\\node at (4,2) (node1) {Source};\n"
+      puts @string
+    end
+    
+  end
+  
+  context 'Custom blocks' do
+    
+    it 'can store custom block configurations' do
+      @writer.add_block_config(:custom2, "begin", "end", 4)
+      @writer.custom_blocks.should_not be nil
+    end  
+
+    it 'stores correct info for custom block configurations' do
+      @writer.add_block_config(:custom2, "begin", "end", 4)
+      @writer.custom_blocks.has_key?(:custom2).should be true
+      @writer.custom_blocks[:custom2][0].should eq "begin"
+      @writer.custom_blocks[:custom2][1].should eq "end"
+      @writer.custom_blocks[:custom2][2].should eq 4
+    end  
+    
+    it 'uses a stored block to produce correct output' do
+      @writer.add_block_config(:custom2, "begin %name", "end %name", 4)
+      @writer.convert do
+        custom2 name: 'Heidi' do
+          line 'Peter'
+        end
+      end
+      @string.should eq "begin Heidi\n    Peter\nend Heidi\n"
+    end
+    
+    
+  end
+  
+end

data/spec/fancy_writer/fancy_writer_spec.rb

@@ -30,6 +30,44 @@ describe FancyWriter::FancyIO do
 
   context 'FancyWriter' do
 
+    context 'Static methods' do
+      
+      it 'performs basic interpolation correctly' do
+        @pattern = 'The %speed %color fox'
+        @args = { speed: 'quick', color: 'brown'}
+        @result = FancyIO.interpol(@pattern, @args)
+        @result.should eq "The quick brown fox"
+      end
+      
+      it 'respects escaped percent signs' do
+        @pattern = 'The %%speed %color fox'
+        @args = { speed: 'quick', color: 'brown'}
+        @result = FancyIO.interpol(@pattern, @args)
+        @result.should eq "The %speed brown fox"
+      end
+      
+      it 'respects escaped percent signs even in the very beginning' do
+        @pattern = '%%speed %color fox'
+        @args = { speed: 'quick', color: 'brown'}
+        @result = FancyIO.interpol(@pattern, @args)
+        @result.should eq "%speed brown fox"
+      end
+      
+    end
+
+    context 'Initialization' do
+      
+      it 'can take additional config and then be run with convert method' do 
+         @writer = FancyIO.new(@string) 
+         in_between = @writer.class.name
+         @writer.convert do
+           w "convert"
+         end
+         @string.should eq "convert\n" 
+      end
+      
+    end
+
     context 'Basics' do
       it 'writes lines without method as they are' do
         @writer = FancyIO.new(@string) do
@@ -115,6 +153,31 @@ describe FancyWriter::FancyIO do
 
     end
 
+    context 'Blocks' do
+      
+      it 'produces correct blocks' do
+        @writer = FancyIO.new(@string) do
+          line 'before'
+          block 'begin', 'end' do
+            line 'inside'
+          end
+          line 'after'
+        end
+        @string.should eq "before\nbegin\n  inside\nend\nafter\n"
+      end
+      
+      it 'produces correct blocks with custom indentation settings' do
+        @writer = FancyIO.new(@string) do
+          line 'before'
+          block 'begin', 'end', 4 do
+            line 'inside'
+          end
+          line 'after'
+        end
+        @string.should eq "before\nbegin\n    inside\nend\nafter\n"
+      end
+      
+    end
 
     it 'exports a complex example correctly' do
       @writer = FancyIO.new(@string) do
@@ -138,7 +201,6 @@ describe FancyWriter::FancyIO do
           end
         end
       end
-      puts @string
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fancy_writer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Peter Menke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-28 00:00:00.000000000 Z
+date: 2015-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -69,6 +69,7 @@ files:
 - fancy_writer.gemspec
 - lib/fancy_writer.rb
 - lib/fancy_writer/version.rb
+- spec/fancy_writer/custom_lines_spec.rb
 - spec/fancy_writer/fancy_writer_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/pmenke/fancy_writer
@@ -91,10 +92,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.2
 signing_key: 
 specification_version: 4
 summary: A simple IO wrapper for easier comment blocks, indentation and CSV output.
 test_files:
+- spec/fancy_writer/custom_lines_spec.rb
 - spec/fancy_writer/fancy_writer_spec.rb
 - spec/spec_helper.rb
+has_rdoc: