whatsthis/README.md

Discover embedable content from URL's

# whatisthis

A small embed classification library for URL's. Give an an URL and it will give
you information about how to embed it as well as provide methods that generated
the embed code for you.

## Installation

The module is released in the public npm registry and can be installed by
running:

```
npm install --save whatsthis
```

## Usage

The module exposes it's classification class as primary interface.

```js
'use strict';

var What = require('whatisthis');
```

It can be constructed with the following options:

- *defaults* Do you want to include the default classification methods. Defaults
  to `true`.

```js
var match = new What({ /* options here */ });
```

## API

The following methods are exposed on the instance.

#### use, before

The classification uses a middleware system called `supplies` to allow adding of 
middleware layers. These middleware layers are the actual functions that can
categorize the content that we feed them. 

The use method adds a method at the end of all checks while the before method
adds it at the beginning of the stack. To add your own or extra classification
functionality you can register them as followed:

```js
what.use('my custom classification', function (result, next) {
  if (!result.match === 'pewpew.com') return next();

  result.html = '<strong>pewpew</strong>';
  next(undefined, true); // supply true to stop other classifcations
});
```

### parse

This is the core method of the module, it parses the content you supply it,
finds a or the last URL in the content and tries to classify it's content based
on the various of classification methods that are registered. 

The method accepts 2 arguments:

1. The message or content that needs to be parsed
2. Completion callback function that follows an error first callback pattern.

```js
what.parse('hello this is http://youtu.be/dQw4w9WgXcQ amazing', function (err, result) {
  console.log(result.html); // <iframe src..>
});
```

As you can see from above you receive a `result` object. This object contains
the following information:

- **match** The found URL in the content.
- **source** The supplied content.
- **url** The parsed result of the URL.
- **service** Generally the name of the parser that classified it.
- **type** Media type. Can be one of the following:
    - social
    - image
    - video
    - link
- **html** Generated embed content.