osx-defaults/README.md

Access to OS X defaults program via simple API.

# osx-defaults

This module provides access to __defaults__ program via simple API.

## Usage

Information about __defaults__ program itself available [here](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/defaults.1.html).

Here is basic usage, you can also browse [examples](https://github.com/over-powdered/defaults/tree/master/examples) directory.

```js
'use strict';

const defaults = require('osx-defaults');

let value = defaults.read({
  isGlobalDomain: true,
  key: 'AppleInterfaceStyle'
});

console.log(value); // Will output "Dark" or null if value is not set/exists

let result = defaults.write({
    isGlobalDomain: true,
    key: 'AppleInterfaceStyle',
    valueType: defaults.STRING,
    value: 'Dark'
});

if (result) {
  console.log('Value of AppleInterfaceStyle updated');
}

```

## API
 - `defaults.read(options[, next])`
 - `defaults.write(options[, next])`
 - `defaults.rename(options[, next])`
 - `defaults.delete(options[, next])`

If you provide `next` callback, then execution will be performed asynchronously.

`next` callback is a function of the following form:
```js
function(error, result) {
  // do stuff here
}
```

## Options

### _hostname_
 Restricts preferences operations to hostname.

### _isCurrentHost_
 Restricts preferences operations to the host the user is currently logged in on.

### _domain_
 If no `isGlobalDomain` flag is specified, `domain` is a domain name of the form _com.companyname.appname_.
 __Example__: _'com.apple.TextEdit'_.

 The name of application may be provided instead of domain using the `-app` prefix.
 __Example__: _'-app TextEdit'_.

 Domains may also be specified as a path to an arbitrary plist file, with or without the '.plist' extension.
 __Example__: _'~/Library/Containers/com.apple.TextEdit/Data/Library/Preferences/com.apple.TextEdit.plist'_.
>  WARNING: The defaults command will be changed in an upcoming major release to only operate on preferences domains. General plist manipulation utilities will be folded into a different command-line program.

### _isGlobalDomain_
 Specify the global domain.

### _key_
 The identifier of the default.

### _valueType_
 Specify value type for preference keys. `String` is used by default, you can also use following constants to specify the value:
  - STRING
  - INT or INTEGER
  - FLOAT
  - BOOL or BOOLEAN
  - ARRAY
  - DICT or DICTIONARY

  __Example__:
  ```js
   'use strict';

   const defaults = require('osx-defaults');

   defaults.write({
       isGlobalDomain: true,
       key: 'foo',
       valueType: defaults.INT, // Value is integer
       value: 1
   });

   defaults.write({
       isGlobalDomain: true,
       key: 'bar',
       valueType: defaults.FLOAT, // Value is float
       value: Math.PI
   });
  ```

### _value_
 Specify the default value when using `defaults.write` method.

### _new_key_
 Specify new key name when using `defaults.rename` method.

---

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.