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
manage_symlink_source	Pass through Chef's symlink-source handling; setting it explicitly also suppresses Chef's symlink warning	true or false	no default
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. If manage_symlink_source is set to true, Chef manages the symlink source file. If it is set to false, Chef disables symlink-source handling and may require the symlink to be removed before writing.

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

:after

Inserts lines after a matching line.

Arguments: pattern to match insert lines, string or array of lines to insert, :each, :first, or :last to select the matching lines, options.

:before

Inserts lines before a matching line.

Arguments: pattern to match insert lines, string or array of lines to insert, :each, :first, or :last to select the matching lines, options.

:between

Inserts lines between matched lines.

Arguments: pattern to insert after, pattern to insert before, lines to insert.

:comment

Changes lines to comments.

Arguments: pattern to match lines, comment string, string to add after the comment indicator.

:delete_between

Deletes lines between matching patterns.

Arguments: pattern to delete after, pattern to delete before, :exclude, :include, :first, or :last.

:missing

Inserts lines before or after existing lines.

Arguments: string or array of lines to add, :before or :after.

:replace

Replaces matching lines.

Arguments: pattern to match lines, string or array to replace the matched line, options.

:replace_between

Replaces lines between matches.

Arguments: start pattern, end pattern, string or array to replace the lines between matches, boundary line processing with :exclude, :include, :first, :last, or :next, options.

:stanza

Inserts or changes keys in a stanza.

Arguments: stanza name, hash of keys and values to set, :equal or :value to select the key style.

:substitute

Substitutes text in matching lines.

Arguments: pattern to select lines, pattern to select text, replacement text, options.