diff options
Diffstat (limited to 'cordova/node_modules/cordova-common/README.md')
| -rwxr-xr-x | cordova/node_modules/cordova-common/README.md | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/cordova/node_modules/cordova-common/README.md b/cordova/node_modules/cordova-common/README.md new file mode 100755 index 0000000..422c98b --- /dev/null +++ b/cordova/node_modules/cordova-common/README.md @@ -0,0 +1,155 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +--> + +[](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, [<task parameters>], task1_reverter, [<reverter_parameters>]); +var action2 = stack.createAction(task2, [<task parameters>], task2_reverter, [<reverter_parameters>]); + +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 <cordova-lib directory> && npm link cordova-common && npm install` |