# Read JSON

> Read a file as [JSON][json].


<section class="usage">

## Usage

``` javascript
var readJSON = require( '@stdlib/fs/read-json' );
```

<a name="read-json"></a>

#### readJSON( file, \[ options,\] clbk )

Asynchronously reads a file as [JSON][json].

``` javascript
var join = require( 'path' ).join;

readJSON( join( __dirname, 'package.json' ), onJSON );

function onJSON( error, data ) {
    if ( error ) {
        throw error;
    }
    console.dir( data );
}
```

The function accepts the following `options`:

* __encoding__: file encoding.
* __flag__: file status flag.
* __reviver__: [JSON][json] transformation `function`.

The `options` parameter may also be a `string` specifying the file `encoding`.

``` javascript
var join = require( 'path' ).join;

readJSON( join( __dirname, 'package.json' ), 'utf8', onJSON );

function onJSON( error, data ) {
    if ( error ) {
        throw error;
    }
    console.dir( data );
}
```


#### readJSON.sync( file\[, options\] )

Synchronously reads a file as [JSON][json].

``` javascript
var join = require( 'path' ).join;

var out = readJSON.sync( join( __dirname, 'package.json' ) );
if ( out instanceof Error ) {
    throw out;
}
console.dir( out );
```

The function accepts the same `options` as [`readJSON()`](#read-json) above.

</section>

<!-- /.usage -->


<section class="notes">

## Notes

* If the `encoding` option is set to `utf8` and the file has a UTF-8 [byte order mark][bom] (BOM), the byte order mark is __removed__ before attempting to parse as [JSON][json].

</section>

<!-- /.notes -->


<section class="examples">

## Examples

``` javascript
var join = require( 'path' ).join;
var readJSON = require( '@stdlib/fs/read-json' );

var file = join( __dirname, 'package.json' );

// Sync //

var data = readJSON.sync( file, 'utf8' );
// returns <Object>

data = readJSON.sync( 'beepboop', {
    'encoding': 'utf8'
});
// returns <Error>


// Async //

readJSON( file, onJSON );
readJSON( 'beepboop', onJSON );

function onJSON( error, data ) {
    if ( error ) {
        if ( error.code === 'ENOENT' ) {
            console.error( 'JSON file does not exist.' );
        } else {
            throw error;
        }
    } else {
        console.log( 'Package description: %s', data.description );
    }
}
```

</section>

<!-- /.examples -->


<section class="links">

[json]: http://www.json.org/
[bom]: https://en.wikipedia.org/wiki/Byte_order_mark

</section>

<!-- /.links -->
