<commit_before># Revisionist

Revisionist is a simple tool to help you manage versions of content in your web application.
Everytime your data changes, you can save it as a revision in a Revisionist instance.
You can then access the last x versions of your content (10 by default).

## Plugin Architecture

Revisionist uses a plugin architecture, so you can override the default behavior of it's two main functions.

The "Simple" plugin shipped by default simply stores and returns the values as they're passed in.
<commit_msg>Adds API docs and example usage.<commit_after># Overview
Revisionist is a simple tool to help you manage versions of content in your web application.
Everytime your data changes, you can save it as a revision in a Revisionist instance.
You can then access the last x versions of your content (10 by default).

Revisionist is open source. View the [annotated source code](http//inf0rmer.github.io/revisionist/docs/revisionist.html).

# How to use it

## In a <script> tag
Include the script in your page. A global "Revisionist" variable will be made available.

## With an AMD loader
Using an AMD loader such as [RequireJS](http://requirejs.org):

```javascript
require(['path/to/revisionist'], function(Revisionist) {
  // The "Revisionist" variable is available
});
```

## In Node

``` javascript
Revisionist = require('path/to/revisionist')
```

Create an instance of Revisionist:
```javascript
rev = new Revisionist()
```

# API

Any instance has these two methods available:

**change(newValue)**

Creates a new revision. It returns the same value you passed in
```javascript
rev.change('bananas')
// -> 'bananas'
```

**recover(version)**

Recovers a previous version of your content and returns it.
```javascript
rev.change('tomatoes')

rev.recover(0)
// -> 'bananas'

rev.recover(1)
// -> 'tomatoes'
```

# Options
When creating a Revisionist instance, you can pass it an options hash to change the default behaviour. The available options are:

**versions | Number**
The maximum number of revisions you wish to store. Defaults to 10.

**plugin | String**
The plugin you wish to use with this instance. The plugin must have been registered before using the class method ```registerPlugin```

# Plugin Architecture
Revisionist uses a plugin architecture, so you can wrap around it's two main functions, ```change``` and ```recover``` to implement your own logic.

The "Simple" plugin shipped by default simply stores and returns the values as they're passed in.

## Authoring a plugin
To write a plugin, all you really have to do is provide Revisionist with a hash containing two methods:

**change(newValue)**

This method will be called by the Revisionist instance when you do ```instance.change("bananas")```. In this case, your implementation of ```change``` would receive an argument with a value of ```bananas```.

**recover(oldValue)**

This method will be called by the Revisionist instance when you do ```instance.recover(2)```. Your implementation of ```recover``` gets an argument with the value previously stored as revision #2.

Both of these methods are executed in the context of your own plugin.

### Registering the plugin
The ```Revisionist``` class exposes a class method to register your plugins.

**registerPlugin(name | String, hash | Object)**

Registers a plugin with a name and a hash containing ```change``` and ```recover``` functions. If your plugin does not follow this naming convention, it will not work properly.

{'fraction_non_alphanumeric': 0.0902558206381144, 'fraction_numerical': 0.0031618281115263006, 'mean_word_length': 4.733113673805601, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1474545', 'n_tokens_mistral': 937, 'n_tokens_neox': 897, 'n_words': 478}