mirror of https://github.com/lalbornoz/roar.git
156 lines
5.1 KiB
Markdown
156 lines
5.1 KiB
Markdown
<!--
|
|
#
|
|
# 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`
|