npm package: @giuband/pitchfork
Description: An Unofficial Pitchfork Music API client for Node.js
Author: Omar Delarosa, Giuseppe Bandiera
Latest version: 0.1.0

#Pitchfork Client

![Travis CI](https://travis-ci.org/omardelarosa/pitchfork-npm.svg?branch=master)

An unofficial Node.js client for [Pitchfork](http://pitchfork.com/) reviews based on the [Pitchfork API Client for Python](https://github.com/michalczaplinski/pitchfork).

## Install

### Using NPM
```bash
npm install pitchfork
```
### Using Github
```bash
git clone git@github.com:omardelarosa/pitchfork-npm.git
```
You can then use it as a [command-line tool](#cli-command-line-interface) or as a [node module](#api)

##API

You can require ``pitchfork`` and use it inside of any Node.JS application.

```javascript
var p4k = require('pitchfork')
```

### Search

A ``Search`` constructor that extends [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).  Listeners can be attached to the 'ready' event which will fire when all reviews have been fetched and parsed.  For example:

```javascript

var p = require('pitchfork')
var s = new p.Search('wilco')

s.on('ready', function(results){
  console.log("results", results)
})

//=> [ {Review}, {Review}, {Review}, ... ]
```

``.results``

An ``Array`` of ``Review`` objects.

``.init()``

Called once when Search is instantiated to fetch results.  Not usually called directly

### Page

A ``Page`` constructor that extends [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).  This constructor takes an integer argument specifying which page of reviews you wish to fetch from ``/reviews/albums/:page_num``. Listeners can be attached to the 'ready' event which will fire when all reviews have been fetched and parsed.  For example, this would return all the most recent reviews:

```javascript

var p = require('pitchfork')
var s = new p.Page(1)

s.on('ready', function(results){
  console.log("results", results)
})

//=> [ {Review}, {Review}, {Review}, ... ]
```

### Review

The ``Review`` constructor encapsulates methods and data relating to the Pitchfork review.  The ``Review`` extends ``EventEmitter`` and fires a 'ready' event when the review has been fetched and parsed.


``.attributes``

An ``Object`` with information about the album and its text.  Sample below:

```json
{
  "url": "/reviews/albums/9419-the-letting-go/",
  "name": "Bonnie \"Prince\" Billy - The Letting Go",
  "artist": "Bonnie \"Prince\" Billy",
  "album": "The Letting Go",
  "title": "Bonnie \"Prince\" Billy: The Letting Go | Album Reviews | Pitchfork",
  "label": "Palace / Drag City",
  "year": "2006",
  "score": 8.2,
  "cover": "http://cdn.pitchfork.com/albums/9255/homepage_large.e8a2bd20.jpg",
  "author": "Mark Richardson",
  "date": "September 18, 2006",
  "editorial": {
    "text": "...",
    "html": "..."
}
```

``.fetch()``

This method is automatically called when the ``Review`` is instantiated and returns a [Promise](https://github.com/kriskowal/q).  This generally isn't called directly.

``.promise``

This stores the thennable promise object generated by .fetch for attaching .then-style callbacks.


``.verbose()``

The full ``Review`` instance represented as JSON.

```json
{
  "url": "/reviews/albums/9419-the-letting-go/",
  "name": "Bonnie \"Prince\" Billy - The Letting Go",
  "artist": "Bonnie \"Prince\" Billy",
  "album": "The Letting Go",
  "title": "Bonnie \"Prince\" Billy: The Letting Go | Album Reviews | Pitchfork",
  "label": "Palace / Drag City",
  "year": "2006",
  "score": 8.2,
  "cover": "http://cdn.pitchfork.com/albums/9255/homepage_large.e8a2bd20.jpg",
  "author": "Mark Richardson",
  "date": "September 18, 2006",
  "editorial": {
    "html": " <p>Though Will Oldham began his musical career while in his early twenties, ... deep absorption or self-reflection so much as a kind of fond familiarity. </p> ",
    "text": " Though Will Oldham began his musical career while in his early twenties ... deep absorption or self-reflection so much as a kind of fond familiarity.  "
  }
}
```

``.truncated()``

The attributes of the ``Review`` instance with editorial.html/editorial.text condensed into the first 300 characters of of the text assigned to the key '.text'.

```json
{
  "url": "/reviews/albums/9419-the-letting-go/",
  "name": "Bonnie \"Prince\" Billy - The Letting Go",
  "artist": "Bonnie \"Prince\" Billy",
  "album": "The Letting Go",
  "title": "Bonnie \"Prince\" Billy: The Letting Go | Album Reviews | Pitchfork",
  "label": "Palace / Drag City",
  "year": "2006",
  "score": 8.2,
  "cover": "http://cdn.pitchfork.com/albums/9255/homepage_large.e8a2bd20.jpg",
  "author": "Mark Richardson",
  "date": "September 18, 2006",
  "text": " Though Will Oldham began his musical career while in his early twenties, he's never exactly sounded young. From his first releases as Palace Music, Oldham's whiskey-soaked vocals and lyrical obsessions with death, sex, and religion have made \"maturity\" something of a non-issue. And yet, with his mo..."
}
```

``.text_pretty_print()``

Prints a plain-text representation of the review.

```

```

## CLI (Command-Line Interface)

Returns a review for a given artist and album title.

```bash
$ pitchfork wilco 'yankee hotel foxtrot'
# { ... pretty-printed, colorized quasi-JSON object... }
```
or you can use -a and -t flags.

```bash
$ pitchfork -a wilco -t 'yankee hotel foxtrot'
# { ... pretty-printed, colorized quasi-JSON object... }
```

Returns a list of reviews for a given artist with no album.

```bash
$ pitchfork -a 'wilco'
# [ 
#    { ... pretty-printed, colorized quasi-JSON object... },
#    { ... pretty-printed, colorized quasi-JSON object... },
#    { ... pretty-printed, colorized quasi-JSON object... }
# ]
```

For valid, uncolored JSON, use the --json flag:

```bash
$ pitchfork -a 'wilco' -t 'yankee hotel foxtrot' --json
# { ... valid JSON object... }
```

### Flags

| flag(s)      |  required | argument    | description  |
| -------      | ---- | ---------   | ------------ |
| -a           |  y  | artist_name |  returns a review by given artist           |
| -t           |    | album_title |  returns a review by given album title |
| -j,--json     |   |    |  returns review attributes as un-prettified json |
| -v, --verbose  |  |    |  returns review entire object as json |
| -V, --version   |  |    | returns version number |
| -T,--truncated |  |    |  returns a truncated json object of the review attributes | 
| -tx,--text      |  |    | returns a text version of review (ex: to pipe output to 'less' ) |
| -p           | | page_number | returns a list of reviews located on the specified page