Skip to end of metadata
Go to start of metadata

Introduction

This article discusses CLI plugins that can be hooked into the Titanium CLI.  With a plugin, you can either create your own CLI command or hook into existing CLI commands using functions or events.  Plugins can either be available globally or on a per-project basis.  These APIs are supported with the Titanium CLI 3.1.0 and SDK Release 3.1.0 and later unless otherwise specified.

Plugins

Structure

Create a folder for your plugin.  You can optionally include a version folder directly under the plugin folder.  Create a commands folder for your CLI plugin commands and a hooks folder for your CLI plugin hooks.  Both of these folders will contain JavaScript files that implement your commands or hooks, respectively.  Currently, the package.json file is not used.

The CLI executes each JavaScript file in the commands and hooks directory.  If you have a JavaScript file with helper functions, place that file in a directory that is not named commands or hooks.  For example, in the file structure below, a helper library is placed in the libs folder.

Using a Plugin

Plugins can either be global or required in per project.

To include a plugin globally, add the paths to CLI configuration options paths.commands and paths.hooks.  For example, run the following CLI commands to add the command and hook files: 

These command and hooks will be executed each time you run the Titanium CLI.

To include a plugin for a specific project:

  1. Create a folder called plugins in your Titanium project.  This will be at the same-level as the Resources folder.
  2. Copy your plugin to the plugins folder.
  3. Open your tiapp.xml file.
  4. Add your plugin information to the plugins section.  Specify the plugin's folder name as node text of the plugin element.  You can optionally specify the version attribute to use a specific version of the plugin.  For example: 

This plugin will be executed each time the project is built.  Note that only hooks are supported when required in locally.

Commands

To add a command to the CLI, you need to create a JavaScript file in your plugin's commands folder and add the path of the file to the paths.commands CLI configuration setting.  The name of the JavaScript file is used as the command name.  This command file registers with the CLI help command to output your commands options based on the exported properties defined in the command file and the object returned by the command's exported config method.  The CLI automatically performs validation against the options you specify in the command file.


myplugin/1.0/commands/mycommand.js

 

CLI Command API

All of the following APIs are optional.  Prepend the APIs with the exports variables to expose them as public.

Properties

cliVersion: String
Specify which version(s) of the CLI the command supports.  For example, "3.2.0" specifies the command only supports version 3.2.0, while ">=3.2.0" specifies the command supports version 3.2.0 and greater.

desc: String
Defines the shorthand help description of the command when executing titanium --help.

extenededDesc: String
Defines the extended help description of the command when using the --help option with the command.

title: String
Title to display in the help menu.  If not specified, the filename is used (without the extension). 

Functions

config

Use the config method to define the command-line options and flags for the command.  The CLI uses the information returned by this method to output information to the help command and provide basic validation of the command-line options.

Syntax

Parameters:

NameTypeDescription
loggerObjectHandle to the logger object. See logger.
configObjectCLI configuration options. Same properties as reported by the titanium config command.
cliObjectHandle to the CLI object. See cli.

Returns:

Returns an object specifying the commands configurable options.  All properties are optional.

NameTypeDescription
noAuthBooleanIf set to true, the user does not need to be logged in to use the command. If set to false, the user is required to be logged in to use the command.
skipBannerBooleanIf set to true, the CLI's banner message is not outputted to the console. If set to false, the CLI's banner message is outputted to the console when the command is executed.
flagsObject

Contains key-value pairs for the command-line flags. The key is the name of the flag, while the value is an object with the following optional key-value pairs:

NameTypeDescription
abbrStringShorthand notation for the flag. Use capital letters. Lowercase letters is the notation used by global CLI flags. If there is a conflict, the flag will be ignored.
descStringHelp description for the flag.

 

Example:

optionsObject

Contains key-value pairs for the command-line options. The key is the name of the option, while the value is an object with the following optional key-value pairs:

NameTypeDescription
abbrStringShorthand notation for the flag. Use capital letters. Lowercase letters is the notation used by global CLI flags. If there is a conflict, the flag will be ignored.
defaultString/Number/BooleanDefault value for the option.
descStringHelp description for the flag.
valuesArray<String/Number/Boolean>Values that the option will accept. The CLI will automatically validate the option against these values when the command is invoked.

 

Example:

 

validate

Use the validate method to execute code after the command is invoked but before actually running the command.  This method can be used to provide advance validation of the command-line options.

Syntax

Parameters:

NameTypeDescription
loggerObjectHandle to the logger object. See logger.
configObjectCLI configuration options. Same properties as reported by the titanium config command.
cliObjectHandle to the CLI object. See cli.

 

run

Use the run method to execute the command when it is invoked.

Syntax

Parameters:

NameTypeDescription
loggerObjectHandle to the logger object. See logger.
configObjectCLI configuration options. Same properties as reported by the titanium config command.
cliObjectHandle to the CLI object. See cli.

Function and Event Hooks

CLI hooks allow you to execute code when the CLI commands are invoked.  Hooks are evaluated for every command regardless if they are used or not.  The build, clean and create commands have additional hooks compared to the other CLI commands.  Hooks are available as either functions or events.

Functions are designed to modify the build process by modifying the build arguments and results.  Functions have a pre and post callbacks, which are executed before and after a execution step.  By default, the function is a post callback if you only specify one.  The callbacks are passed in a data object and a callback.  Both parameters are optional.  After you are done executing your function hook and if you passed in the callback, invoke the callback function and pass it an error and data object.  If you do not invoke the callback, the CLI process stops and cannot continue to the next step.

E vents are not designed to modify the build process and can only stop the build process using the process.exit() method.  Event hooks only execute one callback.  The callback is passed a builder object and a callback.  After you are done executing your event hook, invoke the callback function without any parameters.

To add a hook to the CLI, create a JavaScript file in your plugin's hooks folder.  To globally add the hook to always be executed, add the path of the file to the  paths.commands  CLI configuration setting.  To add it locally to a project, add the plugin containing the hook to your project and add a plugin entry to the project's tiapp.xml file.   Note that local hooks cannot call every hook event.  The earliest hook a local plugin can call is cli:post-validate.

In the hook file, call the init method to setup your hook events and functions.  Use the CLI object's on method to bind hook events and functions to callbacks.  This is explained in further detail in the next section.

For multiple executed hooks, set the priority to change when the hook is executed.  By default, all hooks have a priority value of 1000.  A hook with a lower priority value is executed before one with a higher priority.

Listening to Hooks

In the init method of the hook, use the passed in CLI object to bind your methods to hook events or functions by using the CLI object's on method.  The on method is similar to addEventListener.  The first parameter is the name of the hook event or function; and the second parameter is either the callback function, or a JavaScript object that contains the callback function(s) and optionally a priority value.

The callback function can either be passed nothing, a data object or a data object and a callback function.  If the callback function is passed, you need to invoke it with an err and data object after executing the hook.

 

Order of Hooks

When invoking a CLI command, the hooks are fired in the order below if a global plugin is loaded. For local plugins, hooks can only be monitored starting with the cli:post-validate event hook.

Certain commands, such as the build, clean or create command, fire additional hook events.  For builds, the events vary by platform, and whether you are building a production application or not.

  1. Invoke a CLI command 
  2. cli:go (First hook that can be monitored by global plugins)
  3. [command.config] if invoking the build, clean or create command
  4. cli:command-loaded
  5. cli:pre-validate
  6. CLI displays its banner message.
  7. cli:post-validate (First hook that can be monitored by local plugins)
  8. cli:pre-execute
  9. [help:header] if the help menu is invoked
  10. cli:post-execute or other command hooks if invoking the build, clean or create command (see description below)

Android build hooks

The following hooks are fired after the  cli:pre-execute  hook when building a project for the Android platform:

  1. build.pre.construct
  2. build.pre.compile
  3. build.android.startEmulator
  4. build.android.copyResource (all builds) / build.android.compileJsFile (device and distribution builds only)
  5. build.android.titaniumprep (device and distribution builds only)
  6. build.android.writeAndroidManifest
  7. build.android.aapt
  8. build.android.javac
  9. build.android.proguard (requires special settings)
  10. build.android.dexer
  11. build.android.jarsigner
  12. build.android.zipalign
  13. build.post.compile
  14. build.finalize

iOS build hooks

The following hooks are fired after the cli:pre-execute hook when building a project for the iOS platform:

  1. build.pre.construct
  2. build.pre.compile
  3. build.ios.copyResource (all builds) / build.ios.compileJsFile (device and distribution builds only)
  4. build.ios.prerouting (device and distribution builds only)
  5. build.ios.titaniumprep (device and distribution builds only)
  6. build.ios.xcodebuild
  7. build.ios.writeEntitlements
  8. build.ios.writeExtensionEntitlements
  9. build.ios.writeBuildManifest
  10. build.post.compile
  11. build.finalize

Other platform build hooks

The following hooks are fired after the cli:pre-execute hook when building a project for non-Android or non-iOS platforms:

  1. build.pre.construct
  2. build.pre.compile
  3. build.post.compile
  4. build.finalize

 

Examples

Execute a Script Before Building a Project

The following example checks for a custom application property in the tiapp.xml file and executes a script before starting the build process.  If the return code returned by the script is non-zero, the CLI stops.

 

Modify Android Dexer Command

The following example modifies the arguments passed to the dexer command if the correct module is included in the project.

 

CLI Hook API

Prepend the APIs with the exports variables to expose them as public.

Properties

cliVersion: String
Specify which version(s) of the CLI the command supports.  For example, "3.2.0" specifies the command to only support version 3.2.0, while ">=3.2.0" specifies the command to support version 3.2.0 and greater.

Functions

init

Use the init method to initialize the hook.  Implement the hook listeners, which hook into the CLI commands, inside this function.

Syntax

Parameters:

NameTypeDescription
loggerObjectHandle to the logger object. See logger.
configObjectCLI configuration options. Same properties as reported by the titanium config command.
cliObjectHandle to the CLI object. See cli.
nodeappcObjectHandle to the node-appc object. See nodeappc.

CLI Common API

cli

The CLI class.

Properties

argv: Object
Command-line arguments passed to the CLI.

command: Object
Information about the command invoked, such as the complete command-line options.

completion: Boolean
Indicates if tab completion is enabled or not.

config: Object
Information reported by the titanium config command as a JSON object.

env: Object
Information about the Titanium build environment similar to titanium info -t titanium.

globalContext: Object
CLI command, flag and option context.

hooks: Object
Information about the currently loaded CLI hooks.

logger: Object
Handle to the logger object.

scannedCommandPaths: Object
List of directories scanned for CLI commands.

sdk: Object
Information about the Titanium SDK the application is being built against.

startTime: Number
Start time of the command as a Unix Timestamp.

tiapp: Object
The tiapp.xml file of the project in JSON format.

version: Number
CLI version.

Functions

emit

Fires a hook event.

Parameters:

NameTypeDescription
hookNameStringName of the hook.
contextObjectContext to send to the hook callback.
callbackFunctionFunction to call after the event finishes firing.

 

on

Binds a callback to a hook.

Parameters:

NameTypeDescription
hookNameStringName of the hook.
callbackFunction/Object

Function to call after the event finishes firing.

If an object is used, specify any of the optional properties:

NameTypeDescription
postFunctionCallback to execute after the hook finishes.
preFunctionCallback to execute before the hook starts.
priorityNumberHook execution priority. Lower values are executed first. Default value is 1000.

 

Events

The hook events are namespaced.  If a command name is the first element, then that event is only triggered by that command.  Events prefixed with "cli" are executed for all CLI commands (except for the cli:post-execute hook).  If an event contains a platform name, then it is only executed for that platform (except for the config hooks).

Properties returned by the events are listed below.

build.android.aapt (function hook)

Fired when executing the aapt executable to package Android resources.

build.android.compileJsFile (function hook)

Fired when compiling a JavaScript file for production builds.

build.android.config (function hook)

Fired when configuring the build options for Android.

build.android.copyResource (function hook)

Fired when copying a file from the Resources folder to the build folder.

build.android.dexer (function hook)

Fired when executing the dx script.

build.android.jarsigner (function hook)

Fired when executing the jarsigner executable to sign the APK file.

build.android.javac (function hook)

Fired when executing the javac executable to compile the source code.

build.android.proguard (function hook)

Fired when running ProGuard for code obfuscation.  Requires special settings.

build.android.startEmulator (function hook)

Fired after starting the Android emulator.

build.android.titaniumprep (function hook)

Fired when the titanium_prep executable encrypts the JavaScript files.  Only fired when the build target is device or dist-playstore.

build.android.writeAndroidManifest (function hook)

Fired when writing the AndroidManifest.xml file.

build.android.zipalign (function hook)

Fired when executing the zipalign executable to ZIP align the APK file.

build.config (function hook)

Fired when configuring the build options.

build.finalize (event hook)

Fired when the build completes.

build.ios.config (function hook)

Fired when configuring the build options for iOS.

build.ios.compileJsFile (function hook)

Fired when compiling a JavaScript file for production builds.

build.ios.copyResource (function hook)

Fired when copying a file from the Resources folder to the build folder.

build.ios.prerouting (event hook)

Fired before the titaniumprep hook.  Only fired when the build target is device or dist-*.

build.ios.titaniumprep (function hook)

Fired when the titanium_prep executable encrypts the JavaScript files.  Only fired when the build target is device or dist-*.

build.ios.writeBuildManifest (function hook)

Fired when writing the build-manifest.json file.

build.ios.xcodebuild (function hook)

Fired when the xcodebuild executable is invoked.

build.ios.writeEntitlements (function hook)

Fired when the project entitlements file is written.

build.ios.writeExtensionEntitlements (function hook)

Fired when the extension entitlements file is written.

build.mobileweb.config (function hook)

Fired when configuring the build options for Mobile Web.

build.post.compile (event hook)

Fired after the build completes.

build.pre.compile (event hook)

Fired before starting the pre-compile phase, such as copying and encrypting resources..

build.pre.construct (event hook)

Fired when initializing build options before the pre-compilation phase.

clean.config (event hook)

Fire when configuring the clean options.

clean.post (event hook)

Fired after cleaning the project.

clean.pre (event hook)

Fired before cleaning the project.

cli:command-loaded (event hook)

Fired after command paths have been scanned and all command files are loaded in to the CLI. Only available for globally required hooks.

cli:go (event hook)

Fired right after invoking a CLI command. Only available for globally required hooks.

cli:post-execute (event hook)

Fired after the command executes.

cli:post-validate (event hook)

Fired after validating the command options.  First hook available for locally required hooks.

cli:pre-execute (event hook)

Fired before executing the command but after validation.  Only available for globally required hooks.

cli:pre-validate (event hook)

Fire before validating the command options.  Only available for globally required hooks.

create.config (event hook)

Fired when configuring the create options.  Available on Release 3.3.0 and later.

create.finalize (event hook)

Fired when the create command completes.  Available on Release 3.3.0 and later.

create.post (event hook)

Fired after executing the create command.  Available on Release 3.3.0 and later.

create.pre (event hook)

Fired before executing the create command.  Available on Release 3.3.0 and later.

help:header (event hook)

Fired before the help menu is displayed.

 

Event Properties

Event Hook
NameTypeDescription
argsArrayArguments passed to the function specified by the  fn property.
cliObjectHandle to the CLI object.
commandObjectInformation about the command invoked, such as the complete command-line options.
ctxObjectEvent-specific context.
fnFunctionFunction before the hook callback.
resultArrayReturn value of executing the function fn.
typeStringName of the hook fired.
Function Hook
NameTypeDescription
argsArrayArguments passed to the function specified by the fn property.
ctxObjectCommand- and platform-specific context.
fnFunctionFunction invoked between the pre and post hook callbacks.
resultArrayReturn value of executing the function fn. Only available for post functions.
typeStringName of the hook fired.

 

logger

The logger class based on the winston library.  Use this class to output messages to the console.

Properties

levels: Array<String> – READ-ONLY
Log levels.

Functions

debug

Outputs a debug-level message to the console.

Syntax

Parameters:

NameTypeDescription
messageStringMessage to display in the console.

 

error

Outputs a error-level message to the console.

Syntax

Parameters:

NameTypeDescription
messageStringMessage to display in the console.
exception

Outputs a JavaScript error object to the console.  Outputs the error message and stack trace.

Syntax

Parameters:

NameTypeDescription
eErrorThis is a standard JavaScript Error object. Refer to the  ECMAScript Language Specification Section 15.11  for more information.


getLevels

Retrieves the settable log levels.

Syntax

Returns:

Array of strings indicating the possible settable log levels.

 

info

Outputs an info-level message to the console.

Syntax

Parameters: 

 

NameTypeDescription
messageStringMessage to display in the console.

 

log

Outputs a generic log message to the console.  This message does not have a log level associated with it.

Syntax

Parameters:

NameTypeDescription
messageStringMessage to display in the console.

 

setLevel

Sets the highest log level to display.  Pass one of the the logger's levels property as the argument, for example, logger.levels.info.

Syntax

Parameters:

NameTypeDescription
logLevelNumberValue indicating the highest log level that may be outputted to the console.

 

silence

Set to true to disable console output or false to enable console output.

Syntax

Parameters:

NameTypeDescription
valBooleanDisable (true) or enable (false) console output.

 

trace

Outputs a trace-level message to the console.

Syntax

Parameters:

NameTypeDescription
messageStringMessage to display in the console.

 

warn

Outputs a warning-level message to the console.

Syntax

Parameters:

NameTypeDescription
messageStringMessage to display in the console.

 

nodeappc

The node-appc class provides access to various utility libraries.

 

async

Namespace for helper library built on top of the async library.

parallel method

Run multiple tasks in parallel.

Syntax

Parameters :

NameTypeDescription
contextObjectContext to pass to the tasks
tasksArray<Function>Array of tasks
callbackFunctionA function to call after executing all the tasks
series method

Run multiple tasks in series.

Syntax

Parameters :

NameTypeDescription
contextObjectContext to pass to the tasks
tasksArray<Function>Array of tasks
callbackFunctionA function to call after executing all the tasks

 

busyindicator

CLI busyindicator class.  Create an instance of this class, then use the start and stop methods to start and stop the indicator, respectively.

constructor

Constructor method.

 

start

Starts the busy indicator.

 

stop

Stops the busy indicator.


Example

 

clitools

Namespace for Mac OS X command-line tools helper library.

detect method

Detects if the Mac OS X command-line tools are installed.

Syntax

Parameters :

NameTypeDescription
cliObjectHandle to the CLI object.
callbackFunctionCallback function. Takes an optional object as its only parameter, which contains the environment information.

 

encoding

Namespace for string encoding/decoding helper library.

decodeOctalUTF8 method

Decodes a string with octals to a UTF-8 string.

Syntax

Parameters:

NameTypeDescription
inputStringString to decode

Returns:

Decoded string.

Example:

 

environ

Namespace for OS and Titanium SDK environment helper library.

getOSInfo method

Retrieves OS and Node.js information.

Syntax

Parameters:

NameTypeDescription
callbackFunctionCallback to invoke when done. Takes an optional object as its only parameter, which contains the environment information.

Example:

 

getSDK method

Retrieves information about the specified SDK.

Syntax

Parameters:

NameTypeDescription
versionStringVersion of the SDK, for example, "3.2.0.GA".

Returns:

Information about the SDK or null if it cannot found.

Example:

 

exception

CLI AppcException class.  Create an instance of this class by passing in an error message, then invoke:

  • dump(logger) to output the error message to the console
  • log(String error) to log additional errors
  • toString(void) to convert the error to a string
constructor

Constructor method.

Parameters

NameTypeDescription
messageString

Error message to log

 

dump method

Outputs the exception to the console using the specified logger handle.

Parameters

NameTypeDescription
loggerObject

Handle to a logger instance

 

log method

Logs another error message for the exception.

Parameters

NameTypeDescription
messageString

Error message to log

 

toString method

Converts the exception to a string

Returns:

Exception as a string value.

 

Example

 

haxm

Namespace for Intel HAXM helper library.

detect method

Detects if HAXM is installed.

Syntax

Parameters:

NameTypeDescription
configObjectCLI configuration object.
optionsObject

Device options:

NameTypeDescription
bypassCacheBooleanIf set to false, returns the cached info. If set to true, retrieves values directly from the system.
callbackFunctionCallback to invoke when done. Takes an optional object as its only parameter, which contains the environment information.

Example:


image

Namespace for the image helper library built on top of the imgscalr library.

resize method

Resizes the source image according to the destination parameters.

Syntax

Parameters:  

NameTypeDescription
srcStringCLI configuration object.
dstArray<Object>

Array of objects specifying the required destination properties:

NameTypeDescription
fileStringPath and name of the resize images.
heightNumberHeight to scale the image.
widthNumberWidth to scale the image.
callbackFunctionCallback to invoke when done. Takes an optional error and result objects as its only parameter.
loggerObjectHandle to the logger object.

Example:

   

jdk 

Namespace for the Java helper library.

detect method

Detects if Java and the JDK are installed.

Syntax

Parameters: 

NameTypeDescription
configObjectCLI configuration object.
optionsObject

Device options:

NameTypeDescription
bypassCacheBooleanIf set to false, returns the cached info. If set to true, retrieves values directly from the system.
callbackFunctionCallback to invoke when done. Takes an optional results object as its only parameter, which contains the environment information.

Example:    

 

net 

Namespace for the network helper library.

interface method

Detects all network interfaces.

Syntax

Parameters: 

NameTypeDescription
callbackFunctionCallback to invoke when done. Takes an optional results object as its only parameter, which contains the environment information.

Example:    

 

online method

Detects if the current computer is online.

Syntax

Parameters

NameTypeDescription
callbackFunctionCallback to invoke when done. Takes an optional error object and result value as its only parameter. The results value is a boolean value indicating if the computer is online or not.

Example:  

 

urlEncode method

Converts an object into an escaped URL-safe string.

Syntax

Parameters

NameTypeDescription
objObjectObject to convert

Returns:

An escaped URL-safe string.

Example:  

 

plist

CLI plist class.  Create an instance of this class by passing it a file (or nothing to create an empty plist file), then invoke the methods on the object to traverse to update the progress.

constructor

Constructor method.

Syntax

Parameters

NameTypeDescription
fileString

plist file to open and parse

Returns:

plist file in JSON format or an empty dictionary.

 

progress

CLI progress bar class.  Create an instance of this class by passing it a format string and options object, then invoke the tick method to update the progress.

constructor

Constructor method.

Syntax

Parameters

NameTypeDescription
formatString

Use the following strings to format the progress bar:

  • ':bar' - progress bar
  • ':current' - current progress value
  • ':total' - total progress value
  • ':elapsed' - current elapsed time of the task
  • ':eta' - estimated time when the task completes
  • ':percent' - percent value of the current progress
  • ':paddedPercent' - padded percent value of the current progress
optionsObject

Optional progress bar options:

NameTypeDescription
completeStringCharacter to indicate completed progress in the bar.
incompleteStringCharacter to indicate incomplete progress in the bar.
totalNumberTotal number to be tracked by the progress bar.
widthNumberWidth in characters of the progress bar.

 

 

tick method

Increments the progress and redraws the progress bar.

Syntax

Parameters

NameTypeDescription
lenNumber

Value to increment to progress bar by. Default value is 1.

 

Example
 

string

Namespace for the string helper library.

capitalize method

Capitalizes the string.

Syntax

Parameters:  

NameTypeDescription
strStringString to capitalize.

Returns:

Capitalized string.

 

levenshtein method

Calculates the Levenshtein distance of two strings.

Syntax

Parameters:  

NameTypeDescription
str1StringFirst string.
str2StringSecond string.

Returns:

The distance between the two strings.

 

lpad method

Pads the left side of a string so that the total length equals the specified length. If the string is longer than the length, the string is not padded.

Syntax

Parameters:  

NameTypeDescription
strStringString to pad. 
lenNumberTotal length of the string.
padStringCharacter to use as the padding. Default is a space.

Returns:  

Padded string.

 

renderColumns method

Renders an array of items into columns.

Syntax

Parameters:  

NameTypeDescription
itemsArray<String>Array of items to render.
marginStringRow title in the left margin.
maxwidthNumberMaximum width before wrapping.

Returns:  

Formatted string.

 

rpad method

Pads the right side of a string so that the total length equals the specified length. If the string is longer than the length, the string is not padded.

Syntax

Parameters:  

NameTypeDescription
strStringString to pad. 
lenNumberTotal length of the string.
padStringCharacter to use as the padding. Default is a space.

Returns:

Padded string.

   

suggest method

Compares a string to an array of options and suggests close matches based on a given threshold.

Syntax

Parameters:  

NameTypeDescription
strStringString to find a match for. 
optionsArray<String>Array of strings to find a match with.
loggerFunctionCallback to output the suggestions. Takes one string value as a parameter.
thresholdNumberMatch threshold. Default is 3.

 

wrap method

Inserts line breaks into a string so that the text does not exceed the specified width.

Syntax

Parameters:  

NameTypeDescription
strStringString to wrap. 
wrapNumberLength to wrap the text. Default is the console width.

Returns:

Wrapped string.

 

Examples

 

 

subprocess 

Namespace for the helper library to spawn subprocesses.

findExecutable method 

Tries to locate the executable. 

Syntax

Parameters 

NameTypeDescription
filesArray<String>/StringExecutable to locate or locations to check.
callbackFunctionCallback to invoke when done. Takes an error and results object as its first and second parameters, respectively.

Example:  

 

getRealName method 

Try to get the 8.3 formatted file name for Windows systems.  Returns the original file name for Mac OS X.

Syntax

Parameters 

NameTypeDescription
fileStringExecutable to locate or absolute location to check.
callbackFunctionCallback to invoke when done. Takes an error and results object as its first and second parameters, respectively.

 

run method 

Spawns a new process.

Syntax

Parameters 

NameTypeDescription
cmdStringExecutable to run.
argsArrayArguments to pass to the command.
optsObjectOptions to pass to the spawn command. See the Node.js: Child Process documentation.
callbackFunctionCallback to invoke when done. Takes a code, results, and error object as its first, second and third parameters, respectively.

Example:  

   

time 

Namespace for the time-formatting helper library.

prettyDiff method 

Format the time difference between two JavaScript Date objects in to an easily readable format.

Syntax

Parameters 

NameTypeDescription
fromDateFirst date.
toDateSecond date.
optionsObject

Options:

NameTypeDescription
colorizeBooleanIf set to true, colorizes the output. False by default.
hideMSBooleanIf set to true, hides the millisecond results. False by default.
showFullNameBooleanIf set to true, uses the full name rather than an abbreviation. False by default.

Returns:

Formatted string describing the difference between the date.

Example:  

 

timestamp method 

Creates an ISO-like timestamp.

Syntax

Returns :

Timestamp.

Example: 

 

 

timodule 

Namespace for Titanium module helper library. 

detect method 

Scans the specified paths for Titanium module as well as all known Titanium SDK directories. 

Syntax

Parameters: 

NameTypeDescription
searchPathsArray<String>Paths to search for modules.
loggerObjectHandle to the CLI object.
callbackFunctionCallback function. Takes an optional object as its only parameter, which contains the module information.

   

find method 

Finds Titanium modules with the specified restrictions and groups them in to found, missing, incompatible and conflict categories. 

Syntax

Parameters:   

NameTypeDescription
modulesArray<Object>Modules to search for.
platformArray<String>/StringPlatforms to search for.
deployTypesArray<String>/StringDeploy types to search for.
sdkVersionStringSDK version for minimum SDK version check.
searchPathsArray<String>Paths to search for modules.
loggerObjectHandle to the CLI object.
callbackFunctionCallback function. Takes an optional object as its only parameter, which contains the module information.

 

scopedDetect method

Only scans the specified paths for Titanium module.

Syntax

Parameters:

NameTypeDescription
searchPathsArray<String>Paths to search for modules.
configObjectCLI configuration object.
loggerObjectHandle to the CLI object.
callbackFunctionCallback function. Takes an optional object as its only parameter, which contains the module information.

 

tiplugin

Namespace for Titanium plugin helper library.

detect method

Scans the specified paths for Titanium plugins as well as any globally or user-configured search paths. 

Syntax

Parameters: 

NameTypeDescription
projectDirStringProject path to search for plugins.
configObjectCLI configuration object.
loggerObjectHandle to the CLI object.
callbackFunctionCallback function. Takes an optional object as its only parameter, which contains the plugin information.

 

find method

Finds Titanium plugins with the specified restrictions and groups them in to found or missing categories.

Syntax

Parameters:   

NameTypeDescription
pluginsArray<Object>Plugins to search for.
searchPathsStringPath to the project directory.
configObjectCLI configuration object.
loggerObjectHandle to the CLI object.
callbackFunctionCallback function. Takes an optional object as its only parameter, which contains the plugin information.

 

scopedDetect method

Only scans the specified paths for Titanium plugins.  

Syntax

Parameters: 

NameTypeDescription
searchPathsArray<String>Paths to search for modules.
configObjectCLI configuration object.
loggerObjectHandle to the CLI object.
callbackFunctionCallback function. Takes an optional object as its only parameter, which contains the plugin information.

 

util 

Namespace for the miscellaneous utility library.

mix method 

Mix multiple objects into a single object.

Syntax

Parameters 

NameTypeDescription
obj1ObjectFirst object to mix in other objects with.
...ObjectMore objects to mix in with the first object.

Returns:

Mixed object.

mixObj method 

Deep mixes multiple objects into a single object.

Syntax

Parameters:  

NameTypeDescription
obj1ObjectFirst object to mix in other objects with.
...ObjectMore objects to mix in with the first object.

Returns:

Mixed object.

Example

 

xcconfig 

Loads an Xcode xcconfig file and converts it to JSON format.  Pass the file as the only required parameter to the constructor.

Example: 

 

xml 

Namespace for the XML parsing utility library.  Use the xmldom library to provide an XML document to the library.

forEachAttr method 

Loops through the attributes for an XML DOM object and invokes the callback for each attribute found.

Syntax

Parameters:  

NameTypeDescription
nodeObjectXML node.
callbackFunctionCallback function. Takes an object as it only parameter, which represents the attribute information.
forEachElement method 

Loops through the elements for an XML DOM object and invokes the callback for each element found.

Syntax

Parameters:  

NameTypeDescription
nodeObjectXML node.
callbackFunctionCallback function. Takes an object as it only parameter, which represents the element information.

 

getAttr method 

Retrieves and parses an attribute of an XML node.  If the attribute does not exist, an empty string is returned.

Syntax

Parameters:  

NameTypeDescription
nodeObjectXML node.
attrStringAttribute to get.

Returns:

Returns the value of the attribute or an empty string if it does not exist.

getValue method 

Determines if the XML node has a child node and returns it.

Syntax

Parameters:  

NameTypeDescription
nodeObjectXML node.

Returns:

Returns the value of the child node.

 

parse method 

Parse a XML value and coverts it to a JavaScript value.

Syntax

Parameters:  

NameTypeDescription
valueStringValue of the XML node.

Returns:

Returns the value of the node as a JavaScript primitive.

 

Example

 

version

Namespace for a version helper library.

eq method

Converts two versions to three segment format, then compares if they are equal.

Parameters:

NameTypeDescription
version1StringFirst version to compare
version2StringSecond version to compare

Returns:

True is the versions are equal otherwise false.

 

format method

Formats a version based on the minimum or maximum number of segments.

Parameters:

NameTypeDescription
versionStringVersion to format
minNumberMinimum number of segments
minNumberMaximum number of segments
chopDashBooleanIf true, remove everything after a dash in the version string

Returns:

Formatted version string.

 

gt method

Converts two versions to three segment format, then compares if the first one is greater than the second one.

Parameters:

NameTypeDescription
version1StringFirst version to compare
version2StringSecond version to compare

Returns:

True is the first version is greater than the second version otherwise false.

 

gte method

Converts two versions to three segment format, then compares if the first one is greater than or equal to the second one.

Parameters:

NameTypeDescription
version1StringFirst version to compare
version2StringSecond version to compare

Returns:

True is the first version is greater than or equal to the second version otherwise false.

 

lt method

Converts two versions to three segment format, then compares if the first one is less than the second one.

Parameters:

NameTypeDescription
version1StringFirst version to compare
version2StringSecond version to compare

Returns:

True is the first version is less than the second version otherwise false.

 

lte method

Converts two versions to three segment format, then compares if the first one is less than or equal to the second one.

Parameters:

NameTypeDescription
version1StringFirst version to compare
version2StringSecond version to compare

Returns:

True is the first version is less than or equal to the second version otherwise false.

 

parseMax method

Determines the maximum possible version in the supplied range.

Parameters:

NameTypeDescription
rangeStringSpace-delimited list of versions or version expressions, such as ">3.2.0" or "<3.2.0"

Returns:

Determined maximum version.

 

parseMin method

Determines the minimum possible version in the supplied range.

Parameters:

NameTypeDescription
rangeStringSpace-delimited list of versions or versions expressions, such as ">3.2.0" or "<3.2.0"

Returns:

Determined minimum version.

 

satisfies method

Determines if a version occurs in the supplied versions.

Parameters:

NameTypeDescription
versionStringVersion to check
rangeStringSpace-delimited list of versions or version expressions, such as ">3.2.0" or "<3.2.0"
maybeBooleanIf true and the version is greater than at least one of the supplied version, returns "maybe".

Returns:

Returns true if found or "maybe" if it meets the maybe property condition, otherwise false.

 

sort method

Sorts the array of versions from smallest to largest.

Parameters:

NameTypeDescription
versionsArray<String>Array of versions to sort

Returns:

Sorted array of versions from smallest to largest.

 

Example

 

zip

Namespace for the ZIP archive helper library built on top of the adm-zip library.

unzip method

Decompresses a ZIP archive.

Syntax

Parameters:

NameTypeDescription
fileStringThe file to extract
destStringThe destination to extract the files to
optsObject

Optional extract options:

NameTypeDefaultDescription
visitorFunction A function to call when visiting each file being extracted
overwriteBooleantrueIf true, overwrites files on extraction
defaultPermNumber0644The default file permissions; should be in octet format
callbackFunctionA function to call when done extracting all files

 

 

 

  • No labels