Class: PatternPatch::Patch

Inherits:
Object
  • Object
show all
Defined in:
lib/pattern_patch/patch.rb

Overview

The PatternPatch::Patch class defines a patch as an operation that may be applied to any file. Often the operation may also be reverted.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Patch

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.

Parameters:

  • options (Hash) (defaults to: {}) —

    ] Parameters used to construct the Patch

Options Hash (options):

  • :regexp (Regexp) —

    Value for the regexp attribute

  • :text (String) —

    Value for the text attribute

  • :text_file (String) —

    Value for the text_file attribute

  • :mode (Symbol) — default: :append —

    Value for the mode attribute

  • :global (true, false) — default: false —

    Value for the global attribute

Raises:

  • (ArgumentError) —

    If both :text and :text_file are specified



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/pattern_patch/patch.rb', line 96

def initialize(options = {})
  raise ArgumentError, "text and text_file are mutually exclusive" if options[:text] && options[:text_file]

  @regexp = options[:regexp]
  @text_file = options[:text_file]

  if @text_file
    @text = File.read @text_file
  else
    @text = options[:text]
  end

  @mode = options[:mode] || :append
  @global = options[:global].nil? ? false : options[:global]
end

Instance Attribute Details

#global ⇒ true, false

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.

Returns:

  • (true, false) —

    Whether this patch is global



28
29
30
 
# File 'lib/pattern_patch/patch.rb', line 28

def global
  @global
end

#mode ⇒ Symbol

Symbol specifying the patch mode: :append (default), :prepend or :replace

Returns:

  • (Symbol) —

    The mode of this patch



22
23
24
 
# File 'lib/pattern_patch/patch.rb', line 22

def mode
  @mode
end

#regexp ⇒ Regexp

Regexp defining one or more matching regions in a file.

Returns:

  • (Regexp) —

    The regular expression associated with this patch



12
13
14
 
# File 'lib/pattern_patch/patch.rb', line 12

def regexp
  @regexp
end

#text ⇒ String

String with text to use in the patch operation. May contain ERB.

Returns:

  • (String) —

    The text to use with this patch



17
18
19
 
# File 'lib/pattern_patch/patch.rb', line 17

def text
  @text
end

#text_file ⇒ String

Path to a text file used to populate the text attribute. Setting this after construction modifies the text attribute.

Returns:

  • (String) —

    Path to a text file used to populate the text attribute



34
35
36
 
# File 'lib/pattern_patch/patch.rb', line 34

def text_file
  @text_file
end

Class Method Details

.from_yaml(path) ⇒ Patch

Load a Patch from a YAML file. The following special processing applies: The mode field is converted to a symbol. The text_file field will be interpreted relative to the YAML file. A Regexp will be constructed from the regexp field using Regexp.new unless it is a String containing a Regexp literal using slash delimiters, e.g. /x/i. This format may be used to specify a Regexp with modifiers in YAML. Raises if the file cannot be loaded.

Parameters:

  • path (String) —

    Path to a YAML file containing a patch definition

Returns:

  • (Patch) —

    A Patch initialized from the file



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/pattern_patch/patch.rb', line 47

def from_yaml(path)
  hash = YAML.load_file(path).symbolize_keys

  # Adjust string fields from YAML

  if hash[:regexp].kind_of? String
    regexp_string = hash[:regexp]
    if (matches = %r{^/(.+)/([imx]*)$}.match regexp_string)
      flags = 0
      if matches[2] =~ /i/
        flags |= Regexp::IGNORECASE
      end
      if matches[2] =~ /x/
        flags |= Regexp::EXTENDED
      end
      if matches[2] =~ /m/
        flags |= Regexp::MULTILINE
      end
      hash[:regexp] = Regexp.new matches[1], flags
    else
      hash[:regexp] = /#{regexp_string}/
    end
  end

  if hash[:mode].kind_of? String
    hash[:mode] = hash[:mode].to_sym
  end

  if hash[:text_file]
    hash[:text_file] = File.expand_path hash[:text_file], File.dirname(path)
  end

  new hash
end

Instance Method Details

#apply(files, options = {}) ⇒ Object

Applies the patch to one or more files. ERB is processed in the text field, whether it comes from a text_file or not. Pass a Binding to ERB using the :binding option. Pass the :offset option to specify a starting offset, in characters, from the beginning of the file.

Parameters:

  • files (Array, String) —

    One or more file paths to which to apply the patch.

  • options (Hash) (defaults to: {}) —

    Options for applying the patch.

Options Hash (options):

  • :binding (Binding) — default: nil —

    A Binding object to use when rendering ERB

  • :offset (Integer) — default: 0 —

    Offset in characters

  • :safe_level (Object, nil) — default: PatternPatch.safe_level —

    A valid value for $SAFE for use with ERb

  • :trim_mode (String) — default: PatternPatch.trim_mode —

    A valid ERb trim mode

Raises:

  • (ArgumentError) —

    In case of invalid mode (other than :append, :prepend, :replace)



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/pattern_patch/patch.rb', line 129

def apply(files, options = {})
  offset = options[:offset] || 0
  files = [files] if files.kind_of? String

  safe_level = options[:safe_level] || PatternPatch.safe_level
  trim_mode = options[:trim_mode] || PatternPatch.trim_mode

  patch_text = ERB.new(text, safe_level, trim_mode).result options[:binding]

  files.each do |path|
    modified = Utilities.apply_patch File.read(path),
                                     regexp,
                                     patch_text,
                                     global,
                                     mode,
                                     offset
    File.write path, modified
  end
end

#inspect ⇒ String

Returns a diagnostic string representation

Returns:

  • (String) —

    Diagnostic string representation of this Patch



183
184
185
 
# File 'lib/pattern_patch/patch.rb', line 183

def inspect
  "#<PatternPatch::Patch regexp=#{regexp.inspect} text=#{text.inspect} text_file=#{text_file.inspect} mode=#{mode.inspect} global=#{global.inspect}>"
end

#revert(files, options = {}) ⇒ Object

Reverse the effect of a patch on one or more files. ERB is processed in the text field, whether it comes from a text_file or not. Pass a Binding to ERB using the :binding option. Pass the :offset option to specify a starting offset, in characters, from the beginning of the file.

Parameters:

  • files (Array, String) —

    One or more file paths to which to apply the patch.

  • options (Hash) (defaults to: {}) —

    Options for applying the patch.

Options Hash (options):

  • :binding (Binding) — default: nil —

    A Binding object to use when rendering ERB

  • :offset (Integer) — default: 0 —

    Offset in characters

  • :safe_level (Object, nil) — default: PatternPatch.safe_level —

    A valid value for $SAFE for use with ERb

  • :trim_mode (String) — default: PatternPatch.trim_mode —

    A valid ERb trim mode

Raises:

  • (ArgumentError) —

    In case of invalid mode (other than :append or :prepend)



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/pattern_patch/patch.rb', line 161

def revert(files, options = {})
  offset = options[:offset] || 0
  files = [files] if files.kind_of? String

  safe_level = options[:safe_level] || PatternPatch.safe_level
  trim_mode = options[:trim_mode] || PatternPatch.trim_mode

  patch_text = ERB.new(text, safe_level, trim_mode).result options[:binding]

  files.each do |path|
    modified = Utilities.revert_patch File.read(path),
                                      regexp,
                                      patch_text,
                                      global,
                                      mode,
                                      offset
    File.write path, modified
  end
end

#to_s ⇒ String

Returns a string representation

Returns:

  • (String) —

    String representation of this Patch



189
190
191
 
# File 'lib/pattern_patch/patch.rb', line 189

def to_s
  inspect
end