mojombo/jekyll — pull request #575 by tombell (2012-06-13 00:27:32+00:00)
Title: Refactoring migrators into importers

This pull request is based upon the work that @mojombo and I started working on refactoring the existing migrators, adding some structure and testability. It is also currently work in progress.

## General

Importers are simple classes in the `Jekyll::Importers` namespace, that extend `Importer` and implement 3 methods.

* `self.help` - return a string of the usage and command line options required
* `self.validate` - validate and return an array of error messages for command line options
* `self.process` - process the import and return a specific data structure

```ruby
module Jekyll
module Importers
class CSV < Importer
def self.help
# ...
end

def self.validate(options)
# ...
end

def self.process(options)
# ...
end
end
end
end
```

## Help

The `self.help` method basically returns a string which will be used for the help message and if zero options are passed.

## Validation

The `self.validate` method will check that the required options are present and valid in the `options` hash passed to the method. Should there be any errors, the messages for these errors should be pushed into an array that is returned by `self.validate`.

## Processing

The `self.process` method will process the import and return a hash that the `write_files` method in `Importer` will use to write all the different files.

### File Hash

Each file to be written is represent with it's own hash with specific keys.

```ruby
{
:name => 'the-file-name.md',
:body => 'The contents to be written',

:header => {
:layout => 'post',
:title => 'The Title'
}
}
```

### Files Hash

This is the hash that is going to be returned from the `self.process` method. Some importers may wish to import other types of files like `pages` from WordPress. Just specify another key in the array with the type of file and include an array of file hashes. The type will also determine which directory the files are written into.

```ruby
{
:posts => posts
# :pages => pages
}
```