Development repository for the line cookbook
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Add dokken workflow in circleci & remove travis (#127) Oct 17, 2018
.delivery Working tests for Ubuntu platform for all resources. May 17, 2017
.github Add/update codeowners to use github teams (#132) Dec 12, 2018
libraries Add the comment filter (#129) Dec 13, 2018
recipes Rspec unit tests to inspec (#51) Jul 3, 2017
resources Add the comment filter (#129) Dec 13, 2018
spec Add the comment filter (#129) Dec 13, 2018
test Add the comment filter (#129) Dec 13, 2018
.gitignore adding .gitignore May 30, 2014
.kitchen.dokken.yml Add dokken workflow in circleci & remove travis (#127) Oct 17, 2018
.kitchen.yml Add the comment filter (#129) Dec 13, 2018
.rubocop.yml Ignore Dangerfile like everyone else does Oct 16, 2018
.travis.yml Sensitive: Test on chef 12. Minor fix for the sensitive attribute (#111) Jun 6, 2018
Berksfile Fix the missing file test. May 23, 2018
CHANGELOG.md Add the comment filter (#129) Dec 13, 2018
CONTRIBUTING.md Add CONTRIBUTING.md and TESTING.md May 26, 2018
Dangerfile Removed labels requirement from Dangerfile Dec 10, 2018
Gemfile WIP - Introduces a Dangerfile to the project. (#65) Feb 10, 2018
LICENSE initial commit Dec 8, 2012
README.md Add the before filter method (#126) Dec 10, 2018
TESTING.md Add CONTRIBUTING.md and TESTING.md May 26, 2018
appveyor.yml Add CircleCI Support (Danger) May 19, 2018
chefignore Add CONTRIBUTING.md and TESTING.md May 26, 2018
metadata.rb Add the before filter method (#126) Dec 10, 2018

README.md

line cookbook

Build Status

Motivation

Quite often, the need arises to do line editing instead of managing an entire file with a template resource. This cookbook supplies various resources that will help you do this.

Limitations

  • The line resources processes the entire target file in memory. Trying to edit large files may fail.

  • The end of line processing was only tested using \n and \r\n. Using other line endings very well may not work.

  • The end of line string used needs to match the actual end of line used in the file \n and \r\n are used as the defaults but if they don't match the actual end of line used in the file the results will be weird.

  • Adding a line implies there is a separator on the previous line. Adding a line differs from appending characters.

  • Lines to be added should not contain EOL characters. The providers do not do multiline regex checks.

  • Missing file processing is the way it is by intention

    • add_to_list do nothing, list not found so there is nothing to add to.
    • append_if_no_line create file, add the line.
    • delete_from_list do nothing, the list was not found which implies there is nothing to delete
    • delete_lines do nothing, the line isn't there which implies there is nothing to delete
    • replace_or_add create file, add the line
  • Chef client version 13 or greater is expected.

Usage

Add "depends 'line'" to your cookbook's metadata.rb to gain access to the resources.

append_if_no_line "make sure a line is in some file" do
  path "/some/file"
  line "HI THERE I AM STRING"
end

replace_or_add "why hello" do
  path "/some/file"
  pattern "Why hello there.*"
  line "Why hello there, you beautiful person, you."
end

delete_lines "remove hash-comments from /some/file" do
  path "/some/file"
  pattern "^#.*"
end

delete_lines "remove hash-comments from /some/file with a regexp" do
  path "/some/file"
  pattern /^#.*/
end

replace_or_add "change the love, don't add more" do
  path "/some/file"
  pattern "Why hello there.*"
  line "Why hello there, you beautiful person, you."
  replace_only true
end

add_to_list "add entry to a list" do
  path "/some/file"
  pattern "People to call: "
  delim [","]
  entry "Bobby"
end

delete_from_list "delete entry from a list" do
  path "/some/file"
  pattern "People to call: "
  delim [","]
  entry "Bobby"
end

delete_lines 'remove from nonexisting' do
  path '/tmp/doesnotexist'
  pattern /^#/
  ignore_missing true
end

filter_lines 'Shift lines to at least 8 leading spaces' do
  path '/some/file'
  filter proc { |current| current.map(|line| line =~ /^ {8}/ ? line : "       #{line}") }
end

insert_lines = %w(line1 line2 line3)
match_pattern = /^COMMENT ME|^HELLO/
filter_lines 'Insert lines after match' do
  path '/some/file'
  filter after: [match_pattern, insert_lines]
end

filter_lines 'Built in example filters' do
  path '/tmp/multiple_filters'
  sensitive false
  filters(
    [
    # insert lines after the last match
      { after:  [match_pattern, insert_lines, :last] },
    # insert lines before the first  match
      { before: [match_pattern, insert_lines, :first]  },
    ]
  )
end

Resource Notes

The resources implemented are:

append_if_no_line - Add a missing line
replace_or_add    - Replace a line that matches a pattern or add a missing line
delete_lines      - Delete an item from a list
add_to_list       - Add an item to a list
delete_from_list  - Delete lines that match a pattern
filter_lines      - Supply a proc or use a sample filter
  Sample filters:
    after         - Insert lines after a matched line
    before        - Insert lines before a matched lined

Resource: append_if_no_line

Actions

Action Description
edit Append a line if it is missing.

Properties

Properties Description Type Values and Default
path File to update String Required, no default
line Line contents String 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

Notes

This resource is intended to match the whole line exactly. That means if the file contains this is my line (trailing whitespace) and you've specified line "this is my line", another line will be added. You may want to use replace_or_add instead, depending on your use case.

Resource: replace_or_add

Actions

Action Description
edit Replace lines that match the pattern. Append the line unless a source line matches the pattern.

Properties

Properties Description Type Values and Default
path File to update String Required, no default
pattern Regular expression to select lines Regular expression or String Required, no default
line Line contents String Required, no default
replace_only Don't append only replace matching lines true or false 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

Resource: delete_lines

Actions

Action Description
edit Delete lines that match the pattern.

Properties

Properties Description Type Values and Default
path File to update String Required, no default
pattern Regular expression to select lines Regular expression or String 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

Notes

Removes lines based on a string or regex.

Resource: add_to_list

Actions

Action Description
edit Add an item to a list

Properties

Properties Description Type Values and Default
path File to update String Required, no default
pattern Regular expression to select lines Regular expression or String Required, no default
delim Delimiter entries Array Array of 1, 2 or 3 multi-character elements
entry Value to add String Required, No default
ends_with List ending String 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

Notes

If one delimiter is given, it is assumed that either the delimiter or the given search pattern will proceed each entry and each entry will be followed by either the delimiter or a new line character.

Example:
Input -      People to call: Joe, Bobby
Delimeters - delim [","]
Add this -   entry 'Karen'
Output -     People to call: Joe, Bobby, Karen

If two delimiters are given, the first is used as the list element delimiter and the second as entry delimiters.

Example:
Input -      net1918 = "10.0.0.0/8", "172.16.0.0/12"
Delimeters - delim [", ", "\""]
Add this -   entry "192.168.0.0/16"
Output -     net1918 = "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"

If three delimiters are given, the first is used as the list element delimiter, the second as the leading entry delimiter and the third as the trailing delimiter.

Example:
Input -      multi = ([310], [818])
Delimeters - delim [", ", "[", "]"]
Add this -   entry "425"
Output -     multi = ([310], [818], [425])

ends_with is an optional property. If specified a list is expected to end with the given string.

Resource: delete_from_list

Actions

Action Description
edit Delete an item from a list

Properties

Properties Description Type Values and Default
path File to update String Required, no default
pattern Regular expression to select lines Regular expression or String Required, no default
delim Delimiter entries Array Array of 1, 2 or 3 multi-character elements
entry Value to delete String Required, No default
ends_with List ending String 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

Notes

Delimiters works exactly the same way as add_to_list, see above.

Resource: filter_lines

Actions

Action Description
edit Use a proc

Properties

Properties Description Type Values and Default
path String Path to file Required, no default
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

Notes

The filter_lines resource passes the contents of the path file in an array of lines to a Proc or Method filter. 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 Grammar


filters ::= filter | [<filter>, ...]
filter  ::= <code> | { <code> => <args>  }
args    ::= <String> | <Array>
code    ::= <Symbol> | <Method> | <Proc>
Symbol  ::= :after | :before | :between | :comment | :replace | :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 Arguments arg1 arg2 arg3
:after Insert lines after a matching line Pattern to match String or Array of lines to insert :each, :first, or :last to select the matching lines
:before Insert lines before a matching line Pattern to match String or Array of lines to insert :each, :first, or :last to select the matching lines
:missing Insert lines before or after existing lines Pattern to match String or Array of lines to insert :before, :after

Author

  • Contributor: Mark Gibbons
  • Contributor: Dan Webb
  • Contributor: Sean OMeara
  • Contributor: Antek S. Baranski