heredoc_unindent 1.0.4 → 1.0.5

data/History.rdoc

@@ -1,3 +1,11 @@
+=== 1.0.5 / 2011-01-27
+
+* 1 minor enhancement
+
+  * Refactoring and minor optimization
+  * Improved documentation with YARD tags
+  * New examples in README
+
 === 1.0.4 / 2011-01-27
 
 * 1 minor enhancement

data/README.rdoc

@@ -17,22 +17,25 @@ will probably be an issue and hence this gem.
 == SYNOPSIS:
 
   if true
-    s1 = <<-EOS
+    s = <<-EOS
       How sad it is
         to be unable
       to unindent heredocs
     EOS
-    s2 = <<-EOS.unindent
+    t = <<-EOS.unindent
       How wonderful it is
         to be able
       to do it!
     EOS
   end
 
-  s1[0, 13]  #=>  "      How sad"
-  s2[0, 13]  #=>  "How wonderful"
+  s[0..12]  #=>  "      How sad"
+  t[0..12]  #=>  "How wonderful"
 
-  " foo\n  bar\n baz".unindent  #=>  "foo\n bar\nbaz"
+  s = "   foo"  #=>  "   foo"
+  s.unindent!   #=>  "foo"
+  s.unindent!   #=>  nil
+  s             #=>  "foo"
 
 == FEATURES:
 

data/Rakefile

@@ -6,7 +6,7 @@ require 'hoe'
 Hoe.spec 'heredoc_unindent' do
   developer('Adriano Mitre', 'adriano.mitre@gmail.com')
   
-  self.version = '1.0.4'
+  self.version = '1.0.5'
   
   self.readme_file = 'README.rdoc'
   self.history_file = 'History.rdoc'

data/lib/heredoc_unindent.rb

@@ -1,37 +1,89 @@
 module CoreExt
   module String
-    module HeredocUnindent
+
+    # This module, which is automatically included in ::String, define in-place
+    # and out-of-place unindentation methods.
     #
-    # This module, which is included in String, define the heredoc unindentation method
-    # +heredoc_unindent+ and alias it as +unindent+.
-    ##
+    module HeredocUnindent
      
-      # Removes common margin from indented strings such as the ones produced by
-      # heredocs, i.e., strips out leading whitespace chars at the beggining of
-      # each line (but only as much as the line with the smallest margin).
-      #
-      # Unless the optional argument +warn_first_dif_min+ is set to false or nil, a
-      # warning is produced when the margin of the first line differs from the minimum.
-      #
-      def heredoc_unindent(warn_first_dif_min=true)
-        min_margin = self.scan(/^\s*/).map(&:size).min
-        if warn_first_dif_min
-          first_margin = self[/^\s*/].size
-          if first_margin != min_margin
-            puts "warning: margin of the first line differs from minimum margin"
-          end
+      private
+      
+      # Actual implementation of the unindentation mechanism,
+      # both for in and out-of-place processing.
+      #
+      # @param [Boolean] warn_first_not_min 
+      # @param [Boolean] in_place
+      # @return [String, nil]
+      #
+      def unindent_base(in_place, warn_first_not_min)
+        margins = self.scan(/^\s*/).map(&:size)
+        margins_min = margins.min
+        if margins.first != margins_min && warn_first_not_min
+          puts "warning: margin of the first line differs from minimum margin"
         end
-        re = Regexp.new('^\s{0,' + min_margin.to_s + '}'  ) # omitting the lower limit produces warnings and wrong behavior in ruby-1.8.7-p330 and ree-1.8.7-2010.02
-        self.gsub(re, '')
+        return in_place ? nil : self unless margins_min != 0
+        re = Regexp.new('^\s{0,' + margins_min.to_s + '}'  ) # omitting the lower limit produces warnings and wrong behavior in ruby-1.8.7-p330 and ree-1.8.7-2010.02
+        in_place ? gsub!(re, '') : gsub(re, '')
+      end
+      
+      public
+    
+      # Removes common margin from indented strings, such as the ones produced
+      # by indented heredocs. In other words, it strips out leading whitespace
+      # chars at the beggining of each line, but only as much as the line with
+      # the smallest margin.
+      #
+      # Unless the optional argument +warn_first_dif_min+ is set to +false+ (or
+      # +nil+), a warning is produced when the margin of the first line differs
+      # from the minimum.
+      #
+      # @example
+      #
+      #   if true
+      #     s = <<-EOS
+      #       How sad it is to be unable to unindent heredocs
+      #     EOS
+      #     t = <<-EOS.unindent
+      #       How wonderful it is to be able to do it!
+      #     EOS
+      #   end
+      #  
+      #   s[0..12]  #=>  "      How sad"
+      #   t[0..12]  #=>  "How wonderful"
+      #
+      # @param  [Boolean] warn_first_not_min toggle warning if the margin of the first line differs from minimum margin
+      # @return [::String] unindented string
+      #
+      def heredoc_unindent(warn_first_not_min=true)
+        unindent_base(false, warn_first_not_min)
       end
       alias unindent heredoc_unindent
 
-      # Performs HeredocUnindent#heredoc_unindent in place, returning self, or nil if no changes were made
+      # Same as #heredoc_unindent, but works in-place. Returns self, or nil if
+      # no changes were made
+      #
+      # @note Avoid attributing the return value of this method because it
+      #       may be nil (see Example 2).
+      #
+      # @example 1 Recommended
+      #
+      #   s = "   foo"  #=> "   foo"
+      #   s.unindent!   #=>  "foo"
+      #   s.unindent!   #=>  nil
+      #
+      # @example 2 Disencouraged
+      #   
+      #   s = <<-EOS.unindent!
+      #     the result would be as intended
+      #   if this line weren't unindented
+      #   EOS
+      #   s  #=>  nil
+      #
+      # @param  [Boolean] warn_first_dif_min toggle warning if the margin of the first line differs from minimum margin
+      # @return [::String, NilClass] unindented self, or nil if no changes were made
       #
-      def  heredoc_unindent!(warn_first_dif_min=true)
-        orig = self.dup
-        self.replace(self.heredoc_unindent(warn_first_dif_min))
-        self != orig ? self : nil
+      def  heredoc_unindent!(warn_first_not_min=true)
+        unindent_base(true, warn_first_not_min)
       end
       alias unindent! heredoc_unindent!
     end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 0
-  - 4
-  version: 1.0.4
+  - 5
+  version: 1.0.5
 platform: ruby
 authors: 
 - Adriano Mitre

metadata.gz.sig

@@ -1,2 +1,2 @@
-LuO�k�
-rs��z����VJlA���[�d�S����"��"���F�v���GX�p���d��<3b1��N�6}W��X\�9��sL���qc����˺2�[�H*:��)�Z�vӏ2�L�l�E⛑������8�����~H�f�-������W���x]II�&�l5��g���Q������|�*����+R�v\r�\+i�������V�n��(`IJ
+JZi�����y�ZDĕaKA5�-oF	�����?V�3hQ�Ź'GB[}����<�D�n��p�Q�Α�r
I��,W���-��oW�
NPv��b9�
+Z��̡`� aE��A��=kƖ�!A7Y����/i��Q���