Skip to content

Latest commit

 

History

History
104 lines (84 loc) · 6.57 KB

filter_lines.md

File metadata and controls

104 lines (84 loc) · 6.57 KB
Raw

Resource: filter_lines

Actions

Action Description
edit Use a proc

Properties

Properties Description Type Values and Default
path String Path to file Required, resource name property
filters Array of filters, Proc, Method See the filter grammar Required, no default
ignore_missing Don't fail if the file is missing true or false Default is true
eol Alternate line end characters String default \n on unix, \r\n on windows
backup Backup before changing Boolean, Integer default false
safe Verify that the inserts don't cause a file to grow with each converge. The filter must support safe mode for this to work. Boolean default true
sensitive Print the file changes Boolean default false

Example Usage

filter_lines 'Shift lines to have at least 8 leading spaces' do
  path '/some/file'
  filters proc { |current| current.map(|line| line =~ /^ {8}/ ? line : "       #{line}") }
end
# For the provided sample filters the line input can be in an array or string with line delimeters
insert_lines = %w(line1 line2 line3)

or

text_lines =
'line1
line2
line3'

match_pattern = /^COMMENT ME|^HELLO/
filter_lines 'Insert lines after match' do
  path '/some/file'
  filters after: [match_pattern, insert_lines]
end

# multiple filters may be applied to a file
filter_lines 'Built in example filters' do
  path '/tmp/multiple_filters'
  filters(
    [
    # insert lines after the last match
      { after:  [match_pattern, insert_lines, :last] },
    # insert lines before the first  match
      { before: [match_pattern, text_lines, :first]  },
    # delete lines between matching patterns
      { delete_between: [/startpattern/, /endpattern/ ]  },
    ]
  )
end

Notes

The filter_lines resource passes the contents of the path file in an array of lines to the specified Procs or Methods. The filter should return an array of lines. The output array will be written to the file or passed to the next filter. The built in filters are usable examples of what can be done with a filter, please write your own when you have specific needs. The built in filters all take an array of positional arguments.

Filter Options

Options are expected to be either a hash, with the following keys and values, or nil.

  • safe: true or false. Overrides the default set by the resource property. If an inserted line matches the insert point selection pattern the line may be inserted repeatedy. Setting safe to true prevents those inserts.

Filter Grammar

filters ::= filter | [<filter>, ...]
filter  ::= <code> | { <code> => <args>  }
args    ::= <String> | <Array>
code    ::= <Symbol> | <Method> | <Proc>
Symbol  ::= :after | :before | :between | :comment | :delete | :missing | :replace | :replace_between | :stanza | :substitute
            Symbols are translated to methods in Line::Filter
Method  ::= A reference to a method that has a signature of method(current lines is Array, args is Array)
            and that  returns an array
Proc    ::= A reference to a proc that has a signature of proc(current lines is Array, args is Array)
            and returns an array

Filters

Built in Filter Description Argument Array Arg0 arg1 arg2 arg3
:after Insert lines after a matching line Pattern to match insert lines String or Array of lines to insert :each, :first, or :last to select the matching lines Options
:before Insert lines before a matching line Pattern to match insert lines String or Array of lines to insert :each, :first, or :last to select the matching lines Options
:between Insert lines between matched lines Pattern - Insert after this Pattern - Insert before this Lines to insert
:comment Change lines to comments Pattern to match lines Comment string String to add after the comment indicator
:delete_between Delete lines between matching patterns Pattern - delete after this Pattern - delete before this :exclude, :include, :first, :last
:missing Insert lines before or after existing lines String or Array of lines to add :before, :after
:replace Replace matching lines Pattern to match lines String or Array to replace the matched line Options
:replace_between Replace lines between matches Start pattern End Pattern String or Array to replace the lines between matches Boundary line processing :exclude, :include, :first, :last, :next
:stanza Insert or change keys in a stanza Stanza name Hash of keys and values to set :equal, :value to select the key style
:substitute Substitute text in matching lines Pattern to select lines Pattern to select text Replacement text Options