inkan

Inspired by coming features for Ben Hoskings’ Babushka, inkan is a library for writing out (generated) files and then checking whether they’ve had (manual) changes made to them.

This is particularly useful for generating configuration files and then wanting to check whether people have edited it before overwriting, but you may find other uses for it.

All it actually does is generate a SHA hash of the file’s contents, and adds it as a comment at the top of the file. If the file’s contents are changed, the SHA won’t match, and then you can decide whether you want to overwrite the file.

The name inkan comes from the Japanese word for a document seal.

Installing

gem install inkan

Usage

Reading

To write the files

inkan = Inkan.new('path/to/file.txt')
inkan.print 'foo'
inkan.seal

Or:

Inkan.seal('path/to/file.txt') { |inkan|
  inkan.print 'foo'
}

Writing

Inkan.legitimate?('/path/to/file.txt')

Customising

You can customise the header comment using the following settings:

inkan = Inkan.new('/path/to/file.txt')
inkan.comment_prefix = '/*'            # Default is '#'.
inkan.comment_suffix = '*/'            # Default is ''.
inkan.credit         = 'My Magic Code' # Default is 'Generated by Inkan'

Note on Patches/Pull Requests

The process is (ideally):

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so things don’t break in future versions.
When committing, please don’t mess with Rakefile or VERSION file. Unless, of course, you want your own version, but it’d be nice if you keep custom changes in a branch to be easily merged in.
Send a pull request. Bonus points for topic branches.