pattern_patch 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 020a46e316bbe314edeee3920555b57699d37ca1668d10f1d3e7c7b68325c523
-  data.tar.gz: 8cd9d162362f0a168f3950cce7b3a67083638fb55f629c89fbbc36ba89d73c6a
+  metadata.gz: cb0842afd6861b0575ba1aec38ae58f7b63634b40b0701e6a203f6657bfe5b30
+  data.tar.gz: 4f75f07d932d25c2072453a08267ca277db019f1960bc1eee415e9e154efb089
 SHA512:
-  metadata.gz: bb2bdeb2fd23ff22dcd79741e37e449f10b808174d6401b74fbae472f97a53d3589db604c272f7ed34f98799f7ee3382009059ef3f18a9879296e7c55b811314
-  data.tar.gz: e65d3f77114df163c67fd263f9471b320f6656541ab5b13173405887926755f1a8ae9dbce44030368f9974d8d337309ce0a7366abca636a4c82c3d8095f9647e
+  metadata.gz: 2b46b2c0340cb8d37976d28cd753a0f124bbd37d80816f97a9599fb216bc6df03bdbfa98e76323889246edd77d3342c9be722e473d4a0c1d1e2d34f8b57ff281
+  data.tar.gz: ac9a4e6bc36cb2b03282c988aeb6cf2a4de7ba2e304e99723e1d91575d7b2e2d5d1e13c6c9a81ac8244af01bec00d52e96bd7f5452362e209c9184e95a1f0ea4

data/lib/pattern_patch/core_ext/string.rb

@@ -3,7 +3,8 @@ class String
   # data from matches. Modifies the receiver. The receiver
   # need not match the matches.regexp.
   #
-  # [matches] [MatchData] A MatchData object returned by Regexp#match
+  # @param matches [MatchData] A MatchData object returned by Regexp#match
+  # @return nil
   def apply_matches!(matches)
     search_position = 0
     while (m = /\\(\d+)/.match(self, search_position))
@@ -19,7 +20,8 @@ class String
   # in self replaced by appropriate data from matches. The receiver
   # need not match the matches.regexp.
   #
-  # [matches] [MatchData] A MatchData object returned by Regexp#match
+  # @param matches [MatchData] A MatchData object returned by Regexp#match
+  # @return [String] A modified copy of the receiver
   def apply_matches(matches)
     string = clone
     string.apply_matches! matches

data/lib/pattern_patch/patch.rb

@@ -6,22 +6,31 @@ module PatternPatch
   # The PatternPatch::Patch class defines a patch as an operation that
   # may be applied to any file. Often the operation may also be reverted.
   class Patch
+    # @!attribute regexp
     # Regexp defining one or more matching regions in a file.
+    # @return [Regexp] The regular expression associated with this patch
     attr_accessor :regexp
 
+    # @!attribute text
     # String with text to use in the patch operation. May contain ERB.
+    # @return [String] The text to use with this patch
     attr_accessor :text
 
+    # @!attribute mode
     # Symbol specifying the patch mode: :append (default), :prepend or :replace
+    # @return [Symbol] The mode of this patch
     attr_accessor :mode
 
+    # @!attribute global
     # Setting this to true will apply the patch to all matches in the file.
     # By default (when false), the patch is only applied to the first match.
+    # @return [true, false] Whether this patch is global
     attr_accessor :global
 
-    # If set to a file path, the contents of that file will be used to populate
-    # the text attribute. Setting this after construction modifies the text
-    # field.
+    # @!attribute text_file
+    # Path to a text file used to populate the text attribute. Setting this
+    # after construction modifies the text attribute.
+    # @return [String] Path to a text file used to populate the text attribute
     attr_reader :text_file
 
     class << self
@@ -33,7 +42,8 @@ module PatternPatch
       # used to specify a Regexp with modifiers in YAML. Raises if the file
       # cannot be loaded.
       #
-      # [patch] [String] Path to a YAML file containing a patch definition.
+      # @param path [String] Path to a YAML file containing a patch definition
+      # @return [Patch] A Patch initialized from the file
       def from_yaml(path)
         hash = YAML.load_file(path).symbolize_keys
 
@@ -73,8 +83,16 @@ module PatternPatch
     # Construct a new Patch from the options. The following fields are mapped
     # to the corresponding attributes: :regexp, :text, :text_file, :mode,
     # :global. Raises ArgumentError if both :text and :text_file are specified.
+    # All values may be modified between construction and calling #apply or
+    # #revert.
     #
-    # [options] [Hash] Parameters used to construct the Patch
+    # @param options [Hash)] Parameters used to construct the Patch
+    # @option options [Regexp] :regexp Value for the regexp attribute
+    # @option options [String] :text Value for the text attribute
+    # @option options [String] :text_file Value for the text_file attribute
+    # @option options [Symbol] :mode (:append) Value for the mode attribute
+    # @option options [true, false] :global (false) Value for the global attribute
+    # @raise [ArgumentError] If both :text and :text_file are specified
     def initialize(options = {})
       raise ArgumentError, "text and text_file are mutually exclusive" if options[:text] && options[:text_file]
 
@@ -101,8 +119,11 @@ module PatternPatch
     # ERB using the :binding option. Pass the :offset option to specify a
     # starting offset, in characters, from the beginning of the file.
     #
-    # [files] [Array or String] One or more file paths to which to apply the patch.
-    # [options] [Hash] Options for applying the patch.
+    # @param files [Array, String] One or more file paths to which to apply the patch.
+    # @param options [Hash] Options for applying the patch.
+    # @option options [Binding] :binding (nil) A Binding object to use when rendering ERB
+    # @option options [Integer] :offset (0) Offset in characters
+    # @raise [ArgumentError] In case of invalid mode (other than :append, :prepend, :replace)
     def apply(files, options = {})
       offset = options[:offset] || 0
       files = [files] if files.kind_of? String
@@ -125,8 +146,11 @@ module PatternPatch
     # ERB using the :binding option. Pass the :offset option to specify a
     # starting offset, in characters, from the beginning of the file.
     #
-    # [files] [Array or String] One or more file paths to which to apply the patch.
-    # [options] [Hash] Options for applying the patch.
+    # @param files [Array, String] One or more file paths to which to apply the patch.
+    # @param options [Hash] Options for applying the patch.
+    # @option options [Binding] :binding (nil) A Binding object to use when rendering ERB
+    # @option options [Integer] :offset (0) Offset in characters
+    # @raise [ArgumentError] In case of invalid mode (other than :append or :prepend)
     def revert(files, options = {})
       offset = options[:offset] || 0
       files = [files] if files.kind_of? String
@@ -144,8 +168,16 @@ module PatternPatch
       end
     end
 
+    # Returns a diagnostic string representation
+    # @return [String] Diagnostic string representation of this Patch
     def inspect
-      "#<PatternPatch::Patch regexp=#{regexp.inspect} text=#{text.inspect} mode=#{mode.inspect} global=#{global.inspect}>"
+      "#<PatternPatch::Patch regexp=#{regexp.inspect} text=#{text.inspect} text_file=#{text_file.inspect} mode=#{mode.inspect} global=#{global.inspect}>"
+    end
+
+    # Returns a string representation
+    # @return [String] String representation of this Patch
+    def to_s
+      inspect
     end
   end
 end

data/lib/pattern_patch/utilities.rb

@@ -4,12 +4,14 @@ module PatternPatch
       # Add the specified text after the specified pattern.
       # Returns a modified copy of the string.
       #
-      # :contents: A string to modify, e.g. the contents of a file
-      # :regexp: A regular expression specifying a pattern to be matched
-      # :text: Text to be appended to the specified pattern
-      # :global: Boolean flag. If true, patch all occurrences of the regex.
-      # :mode: :append, :prepend or :replace to specify how to apply the patch
-      # :offset: Starting position for matching
+      # @param contents [String] A string to modify, e.g. the contents of a file
+      # @param regexp [Regexp] A regular expression specifying a pattern to be matched
+      # @param text [String] Text to be appended to the specified pattern
+      # @param global [true, false] Boolean flag. If true, patch all occurrences of the regex.
+      # @param mode [Symbol] :append, :prepend or :replace to specify how to apply the patch
+      # @param offset [Integer] Starting position for matching
+      # @return [String] A modified copy of the contents argument
+      # @raise [ArgumentError] In case of invalid mode (other than :append, :prepend, :replace)
       def apply_patch(contents, regexp, text, global, mode, offset)
         search_position = offset
         while (matches = regexp.match(contents, search_position))
@@ -37,12 +39,14 @@ module PatternPatch
       # cannot be reverted.
       # Returns a modified copy of the string.
       #
-      # :contents: A string to modify, e.g. the contents of a file
-      # :regexp: A regular expression specifying a pattern to be matched
-      # :text: Text to be appended to the specified pattern
-      # :global: Boolean flag. If true, patch all occurrences of the regex.
-      # :mode: :append or :prepend. :replace patches cannot be reverted automatically.
-      # :offset: Starting position for matching
+      # @param contents [String] A string to modify, e.g. the contents of a file
+      # @param regexp [Regexp] A regular expression specifying a pattern to be matched
+      # @param text [String] Text to be appended to the specified pattern
+      # @param global [true, false] Boolean flag. If true, patch all occurrences of the regex.
+      # @param mode [Symbol] :append or :prepend. :replace patches cannot be reverted automatically.
+      # @param offset [Integer] Starting position for matching
+      # @return [String] A modified copy of the contents argument
+      # @raise [ArgumentError] In case of invalid mode (other than :append or :prepend)
       def revert_patch(contents, regexp, text, global, mode, offset)
         search_position = offset
         regexp_string = regexp.to_s

data/lib/pattern_patch/version.rb

@@ -1,3 +1,3 @@
 module PatternPatch
-  VERSION = "0.5.2"
+  VERSION = "0.5.3"
 end

data/lib/pattern_patch.rb

@@ -2,3 +2,35 @@ require "pattern_patch/core_ext"
 require "pattern_patch/patch"
 require "pattern_patch/utilities"
 require "pattern_patch/version"
+
+# Utility gem for modifying arbitrary text files using a method similar to
+# rendering Rails partials.
+#
+# @author Jimmy Dee (https://github.com/jdee)
+module PatternPatch
+  # Generic exception class for PatternPatch exceptions
+  class Error < RuntimeError; end
+
+  # Exception generated by patch method when patch_dir is not set properly
+  class ConfigurationError < Error; end
+
+  module Methods
+    # @!attribute patch_dir
+    # Set this to conveniently load patches from a common folder with
+    # the patch method.
+    # @return [String] Path to a directory for use with patch
+    attr_accessor :patch_dir
+
+    # Loads a patch from the patch_dir
+    # @param name [#to_s] Name of a patch to load from the patch_dir
+    # @return [Patch] A patch loaded from the patch_dir
+    # @raise [ConfigurationError] If patch_dir is nil or is not a valid directory path
+    def patch(name)
+      raise ConfigurationError, "patch_dir has not been set" if patch_dir.nil?
+      raise ConfigurationError, "patch_dir is not a directory" unless Dir.exist?(patch_dir)
+      Patch.from_yaml File.join(patch_dir, "#{name}.yml")
+    end
+  end
+
+  extend Methods
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pattern_patch
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Jimmy Dee
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-09 00:00:00.000000000 Z
+date: 2017-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -136,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: This is a utility gem that identifies positions in any text using regular
   expressions and then inserts patch text at the specified location or replaces matching
   text. Many patches can be reverted.
@@ -170,7 +184,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.1
+rubygems_version: 2.7.2
 signing_key: 
 specification_version: 4
 summary: Apply and revert pattern-based patches to text files of any kind