(maint) Clarify docs and add new tests

Based on a Stack Overflow question, it was noted that the documentation
for `file_line` isn't complete and the underlying behaviour somewhat
confusing.

https://stackoverflow.com/questions/46468922/how-to-change-the-contents-of-a-file-by-using-puppet/46473458

In this patch I add additional unit tests and better examples and
complete documentation.

2 files changed, 92 insertions, 2 deletions

diff --git a/spec/unit/puppet/provider/file_line/ruby_spec.rb b/spec/unit/puppet/provider/file_line/ruby_spec.rb
index dcca4a4..4ec9bae 100755
--- a/spec/unit/puppet/provider/file_line/ruby_spec.rb
+++ b/spec/unit/puppet/provider/file_line/ruby_spec.rb
@@ -337,7 +337,7 @@ describe provider_class, :unless => Puppet::Util::Platform.windows? do
     end
   end
 
-  context "when removing" do
+  context "when removing with a line" do
     before :each do
       # TODO: these should be ported over to use the PuppetLabs spec_helper
       #  file fixtures once the following pull request has been merged:
@@ -378,6 +378,23 @@ describe provider_class, :unless => Puppet::Util::Platform.windows? do
       @provider.destroy
       expect(File.read(@tmpfile)).to eql("foo1\nfoo2\n")
     end
+
+    it 'example in the docs' do
+      @resource = Puppet::Type::File_line.new(
+        {
+          :name   => 'bashrc_proxy',
+          :ensure => 'absent',
+          :path   => @tmpfile,
+          :line   => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
+        }
+      )
+      @provider = provider_class.new(@resource)
+      File.open(@tmpfile, 'w') do |fh|
+        fh.write("foo1\nfoo2\nexport HTTP_PROXY=http://squid.puppetlabs.vm:3128\nfoo4\n")
+      end
+      @provider.destroy
+      expect(File.read(@tmpfile)).to eql("foo1\nfoo2\nfoo4\n")
+    end
   end
 
   context "when removing with a match" do
@@ -416,6 +433,41 @@ describe provider_class, :unless => Puppet::Util::Platform.windows? do
       expect(File.read(@tmpfile)).to eql("foo1\nfoo2")
     end
 
+    it 'the line parameter is actually not used at all but is silently ignored if here' do
+      @resource = Puppet::Type::File_line.new(
+        {
+          :name              => 'foo',
+          :path              => @tmpfile,
+          :line              => 'supercalifragilisticexpialidocious',
+          :ensure            => 'absent',
+          :match             => 'o$',
+          :match_for_absence => true,
+        }
+      )
+      File.open(@tmpfile, 'w') do |fh|
+        fh.write("foo1\nfoo\nfoo2")
+      end
+      @provider.destroy
+      expect(File.read(@tmpfile)).to eql("foo1\nfoo2")
+    end
+
+    it 'and may not be here and does not need to be here' do
+      @resource = Puppet::Type::File_line.new(
+        {
+          :name              => 'foo',
+          :path              => @tmpfile,
+          :ensure            => 'absent',
+          :match             => 'o$',
+          :match_for_absence => true,
+        }
+      )
+      File.open(@tmpfile, 'w') do |fh|
+        fh.write("foo1\nfoo\nfoo2")
+      end
+      @provider.destroy
+      expect(File.read(@tmpfile)).to eql("foo1\nfoo2")
+    end
+
     it 'should raise an error if more than one line matches' do
       File.open(@tmpfile, 'w') do |fh|
         fh.write("foo1\nfoo\nfoo2\nfoo\nfoo")
@@ -480,6 +532,41 @@ describe provider_class, :unless => Puppet::Util::Platform.windows? do
       expect(File.read(@tmpfile)).to eql("foo1\nfoo\n")
     end
 
-  end
+    it 'example in the docs' do
+      @resource = Puppet::Type::File_line.new(
+        {
+          :name              => 'bashrc_proxy',
+          :ensure            => 'absent',
+          :path              => @tmpfile,
+          :line              => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
+          :match             => '^export\ HTTP_PROXY\=',
+          :match_for_absence => true,
+        }
+      )
+      @provider = provider_class.new(@resource)
+      File.open(@tmpfile, 'w') do |fh|
+        fh.write("foo1\nfoo2\nexport HTTP_PROXY=foo\nfoo4\n")
+      end
+      @provider.destroy
+      expect(File.read(@tmpfile)).to eql("foo1\nfoo2\nfoo4\n")
+    end
 
+    it 'example in the docs showing line is redundant' do
+      @resource = Puppet::Type::File_line.new(
+        {
+          :name              => 'bashrc_proxy',
+          :ensure            => 'absent',
+          :path              => @tmpfile,
+          :match             => '^export\ HTTP_PROXY\=',
+          :match_for_absence => true,
+        }
+      )
+      @provider = provider_class.new(@resource)
+      File.open(@tmpfile, 'w') do |fh|
+        fh.write("foo1\nfoo2\nexport HTTP_PROXY=foo\nfoo4\n")
+      end
+      @provider.destroy
+      expect(File.read(@tmpfile)).to eql("foo1\nfoo2\nfoo4\n")
+    end
+  end
 end
diff --git a/spec/unit/puppet/type/file_line_spec.rb b/spec/unit/puppet/type/file_line_spec.rb
index 150149b..db07352 100755
--- a/spec/unit/puppet/type/file_line_spec.rb
+++ b/spec/unit/puppet/type/file_line_spec.rb
@@ -78,6 +78,9 @@ describe Puppet::Type.type(:file_line) do
   it 'should not require that a line is specified when matching for absence' do
     expect { Puppet::Type.type(:file_line).new(:name => 'foo', :path => tmp_path, :ensure => :absent, :match_for_absence => :true, :match => 'match') }.not_to raise_error
   end
+  it 'although if a line is specified anyway when matching for absence it still works and the line is silently ignored' do
+    expect { Puppet::Type.type(:file_line).new(:name => 'foo', :path => tmp_path, :line => 'i_am_irrelevant', :ensure => :absent, :match_for_absence => :true, :match => 'match') }.not_to raise_error
+  end
   it 'should require that a file is specified' do
     expect { Puppet::Type.type(:file_line).new(:name => 'foo', :line => 'path') }.to raise_error(Puppet::Error, /path is a required attribute/)
   end