Epic Castle

line-in-file

Manage lines in text files

Overview

This module ensures a particular line is in a text file, or can replace an existing line using a regular expression.
It can ensure a particular line is absent from a file.
It can gather a line or lines that match a regular expression from a file for further processing.
This is most useful when only a few lines need changing. Often it is better to template the entire file with the template module.

Form

(line-in-file mode options)

Arguments

mode

The mode to operate in. Should be one of :get, :present or :absent

:get

Return all lines matching the regular expression :regexp from the file. Also returns their line numbers.

:present

Ensure that the passed in :line is in the file optionally placing it in the specified position.

:absent

Ensure that any lines maching the regular expression :regexp are not in the file.

options

A hashmap of options. All available option keys and their values are described below

Options

Option	Description
`:path` required `true` type `string`	Path to the file
`:regexp` aliases `:regex` type `regexp`	The regular expression to look for in every line of the file In `:present` mode, the pattern to replace if found. Replaces the last occurance of that pattern. In `:absent` mode, the pattern of lines to remove. All occurances of that line will be removed. In `:get` mode, the pattern of lines to be returned. All occurances that match will be returned. If the regular expression is not matched, the line will be added to the file. `:before` and `:after` will allow you to control where in the file the line is inserted. If `:before` or `:after` is not used then ensure the regular expression matches both the initial state of the line as well as its state after replacement to ensure idempotence. NOTE: The regular expression is passed as a clojure regex literal or a Java regex but is converted into a sed regular expression for operation on the host. As such the semantics of the regular expression are those of the sed implementation on the host and not of Java's Pattern class.
`:string-match` type `string`	A string to look for in every line of the file. In `:present` mode, the line that contains a match for the string will be replaced. In `:absent` mode, the line that contains a match for the string will be removed. In `:get` mode, the line that contains a match for the string will be returned. The same `:before`, `:after` and `:insert-at` rules apply as they do for `:regexp`.
`:line-match` type `string`	An entire line to look for in every line of the file. In `:present` mode, the line that matches will be replaced. In `:absent` mode, the line that matches will be removed. In `:get` mode, the lines that match will be returned. The same `:before`, `:after` and `:insert-at` rules apply as they do for `:regexp`. If neither `:regexp` nor `:string-match` nor `:line-match` is specified, then the contents of `:line` is used as a value for `:line-match`.
`:line-num` type `integer`	Specify the line to match by line number instead of regular expression. or string
`:line` type `string`	The contents of the line to insert into the file
`:after` type `regexp`	Used with mode `:present` If specified, the line will be inserted after the last (or first) match of the specified regular expression. If the first match is required, use `:first-match true` If the specified search expression has no matches, the line will be appended to the end (or prepended to the start) of the file. If the prepending to the start is required, use `:insert-at :bof` If a match is found for `:regexp`, `:string-match` or `:line-match`, insertion is skipped and this parameter is ignored May not be used in conjunction with `:before`
`:before` type `regexp`	Used with mode `:present` If specified, the line will be inserted before the last (or first) match of the specified regular expression. If the first match is required, use `:first-match true` If the specified search expression has no matches, the line will be appended to the end (or prepended to the start) of the file. If the prepending to the start is required, use `:insert-at :bof` If a match is found for `:regexp`, `:string-match` or `:line-match`, insertion is skipped and this parameter is ignored May not be used in conjunction with `:after`
`:match` required `true` type `keyword`	How to handle files with multiple lines that match. Should be `:first`, `:last` or `:all`
`:insert-at` required `true` type `keyword`	If no line matches and no `:after` or `:before` matches, describes where to insert the line. Should be `:eof` for end of file, or `:bof` for beginning of file.

Examples

Replace localhost entry with a custom line

(line-in-file :present
              {:path "/etc/hosts"
               :regexp #"^127\.0\.0\.1"
               :line "127.0.0.1 localhost local myhostname"})

Add a comment to the web port definition in /etc/services

(line-in-file :present
              {:path "/etc/services"
               :regexp #"^# http service port"
               :line "# http service port"})