[](https://ci.appveyor.com/project/ApacheSoftwareFoundation/cordova-common/branch/master) [](https://travis-ci.org/apache/cordova-common) [](https://nodei.co/npm/cordova-common/) # cordova-common Exposes shared functionality used by [cordova-lib](https://github.com/apache/cordova-lib/) and Cordova platforms. ## Exposed APIs ### `events` Represents special instance of NodeJS EventEmitter which is intended to be used to post events to cordova-lib and cordova-cli Usage: ```js var events = require('cordova-common').events; events.emit('warn', 'Some warning message') ``` There are the following events supported by cordova-cli: `verbose`, `log`, `info`, `warn`, `error`. ### `CordovaError` An error class used by Cordova to throw cordova-specific errors. The CordovaError class is inherited from Error, so CordovaError instances is also valid Error instances (`instanceof` check succeeds). Usage: ```js var CordovaError = require('cordova-common').CordovaError; throw new CordovaError('Some error message', SOME_ERR_CODE); ``` See [CordovaError](src/CordovaError/CordovaError.js) for supported error codes. ### `ConfigParser` Exposes functionality to deal with cordova project `config.xml` files. For ConfigParser API reference check [ConfigParser Readme](src/ConfigParser/README.md). Usage: ```js var ConfigParser = require('cordova-common').ConfigParser; var appConfig = new ConfigParser('path/to/cordova-app/config.xml'); console.log(appconfig.name() + ':' + appConfig.version()); ``` ### `PluginInfoProvider` and `PluginInfo` `PluginInfo` is a wrapper for cordova plugins' `plugin.xml` files. This class may be instantiated directly or via `PluginInfoProvider`. The difference is that `PluginInfoProvider` caches `PluginInfo` instances based on plugin source directory. Usage: ```js var PluginInfo: require('cordova-common').PluginInfo; var PluginInfoProvider: require('cordova-common').PluginInfoProvider; // The following instances are equal var plugin1 = new PluginInfo('path/to/plugin_directory'); var plugin2 = new PluginInfoProvider().get('path/to/plugin_directory'); console.log('The plugin ' + plugin1.id + ' has version ' + plugin1.version) ``` ### `ActionStack` Utility module for dealing with sequential tasks. Provides a set of tasks that are needed to be done and reverts all tasks that are already completed if one of those tasks fail to complete. Used internally by cordova-lib and platform's plugin installation routines. Usage: ```js var ActionStack = require('cordova-common').ActionStack; var stack = new ActionStack() var action1 = stack.createAction(task1, [], task1_reverter, []); var action2 = stack.createAction(task2, [], task2_reverter, []); stack.push(action1); stack.push(action2); stack.process() .then(function() { // all actions succeded }) .catch(function(error){ // One of actions failed with error }) ``` ### `superspawn` Module for spawning child processes with some advanced logic. Usage: ```js var superspawn = require('cordova-common').superspawn; superspawn.spawn('adb', ['devices']) .progress(function(data){ if (data.stderr) console.error('"adb devices" raised an error: ' + data.stderr); }) .then(function(devices){ // Do something... }) ``` ### `xmlHelpers` A set of utility methods for dealing with XML files. Usage: ```js var xml = require('cordova-common').xmlHelpers; var xmlDoc1 = xml.parseElementtreeSync('some/xml/file'); var xmlDoc2 = xml.parseElementtreeSync('another/xml/file'); xml.mergeXml(doc1, doc2); // doc2 now contains all the nodes from doc1 ``` ### Other APIs The APIs listed below are also exposed but are intended to be only used internally by cordova plugin installation routines. ``` PlatformJson ConfigChanges ConfigKeeper ConfigFile mungeUtil ``` ## Setup * Clone this repository onto your local machine `git clone https://github.com/apache/cordova-common.git` * Navigate to cordova-common directory, install dependencies and npm-link `cd cordova-common && npm install && npm link` * Navigate to cordova-lib directory and link cordova-common `cd && npm link cordova-common && npm install`