Environment(args, opts, adaperopt)

Environment object is responsible of handling the lifecyle and bootstrap of generators in a specific environment (your app).

It provides a high-level API to create and run generators, as well as further tuning where and how a generator is resolved.

An environment is created using a list of arguments and a Hash of options. Usually, this is the list of arguments you get back from your CLI options parser.

An optional adapter can be passed to provide interaction in non-CLI environment (e.g. IDE plugins), otherwise a TerminalAdapter is instantiated by default

new Environment(args, opts, adaperopt)

Parameters:
Name Type Attributes Description
args String | Array
opts Object
Properties
Name Type Attributes Description
experimental Boolean <optional>
sharedOptions Object <optional>
console Console <optional>
stdin Stream <optional>
stdout Stream <optional>
stderr Stream <optional>
adaper TerminalAdapter <optional>

A TerminalAdapter instance or another object implementing this adapter interface. This is how you'd interface Yeoman with a GUI or an editor.

Mixes In:

Members

static util

Expose the utilities on the module

See:
  • env/util

Methods

static createEnv() → {Environment}

Factory method to create an environment instance. Take same parameters as the Environment constructor.

Returns:
Environment -

a new Environment instance

See:
  • This method take the same arguments as Environment constructor

static createEnvWithVersion(version, …args) → {Environment}

Factory method to create an environment instance. Take same parameters as the Environment constructor.

Parameters:
Name Type Attributes Description
version String

Version of the Environment

args any <repeatable>

Same arguments as Environment constructor.

Returns:
Environment -

a new Environment instance

static enforceUpdate(env) → {Environment}

Make sure the Environment present expected methods if an old version is passed to a Generator.

Parameters:
Name Type Description
env Environment
Returns:
Environment -

The updated env

static lookupGenerator(namespace, optionsopt) → {String}

Lookup for a specific generator.

Parameters:
Name Type Attributes Description
namespace String
options Object <optional>
Properties
Name Type Attributes Default Description
localOnly Boolean <optional>
false

Set true to skip lookups of globally-installed generators.

packagePath Boolean <optional>
false

Set true to return the package path instead of generators file.

singleResult Boolean <optional>
true

Set false to return multiple values.

Returns:
String -

generator

static namespaceToName(namespace) → {String}

Convert a generators namespace to its name

Parameters:
Name Type Description
namespace String
Returns:
String

alias(match, value)

Get or create an alias.

Alias allows the get() and lookup() methods to search in alternate filepath for a given namespaces. It's used for example to map generator-* npm package to their namespace equivalent (without the generator- prefix), or to default a single namespace like angular to angular:app or angular:all.

Given a single argument, this method acts as a getter. When both name and value are provided, acts as a setter and registers that new alias.

If multiple alias are defined, then the replacement is recursive, replacing each alias in reverse order.

An alias can be a single String or a Regular Expression. The finding is done based on .match().

Parameters:
Name Type Description
match String | RegExp
value String
Mixes In:
Example
env.alias(/^([a-zA-Z0-9:\*]+)$/, 'generator-$1');
    env.alias(/^([^:]+)$/, '$1:app');
    env.alias(/^([^:]+)$/, '$1:all');
    env.alias('foo');
    // => generator-foo:all

create(namespaceOrPath, options)

Create is the Generator factory. It takes a namespace to lookup and optional hash of options, that lets you define arguments and options to instantiate the generator with.

An error is raised on invalid namespace.

Parameters:
Name Type Description
namespaceOrPath String
options Object

error(err, verifyListeneropt) → {Error}

Error handler taking err instance of Error.

The error event is emitted with the error object, if no error listener is registered, then we throw the error.

Parameters:
Name Type Attributes Description
err Object
verifyListener Boolean <optional>

Only emit error if a listener is registered.

Returns:
Error -

err

findGeneratorsIn(List, optionsopt) → {Array}

Search npm for every available generators. Generators are npm packages who's name start with generator- and who're placed in the top level node_module path. They can be installed globally or locally.

Parameters:
Name Type Attributes Description
List Array

of search paths

options Object <optional>
Properties
Name Type Attributes Default Description
packagePatterns boolean <optional>
'generator-*'

Pattern pattern.

Returns:
Array -

List of the generator modules path

Mixes In:
Deprecated:
  • Yes

get(namespaceOrPath) → {Generator|null}

Get a single generator from the registered list of generators. The lookup is based on generator's namespace, "walking up" the namespaces until a matching is found. Eg. if an angular:common namespace is registered, and we try to get angular:common:all then we get angular:common as a fallback (unless an angular:common:all generator is registered).

Parameters:
Name Type Description
namespaceOrPath String
Returns:
Generator | null -
  • the generator registered under the namespace

getByPath(path) → {Generator|null}

Get a generator by path instead of namespace.

Parameters:
Name Type Description
path String
Returns:
Generator | null -
  • the generator found at the location

getGeneratorNames() → {Array}

Get registered generators names

Returns:
Array

getGeneratorsMeta() → {Object}

Returns stored generators meta

Returns:
Object

getNpmPaths(optionsopt) → {Array}

Get the npm lookup directories (node_modules/)

Parameters:
Name Type Attributes Description
options boolean | Object <optional>
Properties
Name Type Attributes Default Description
localOnly boolean <optional>
false

Set true to skip lookups of globally-installed generators.

filterPaths boolean <optional>
false

Remove paths that don't ends with a supported path (don't touch at NODE_PATH paths).

Returns:
Array -

lookup paths

Mixes In:
Deprecated:
  • Yes

getPackagePath(namespace) → {String}

Get last added path for a namespace

Parameters:
Name Type Description
namespace String

namespace

Returns:
String -
  • path of the package

getPackagePaths(namespace) → {Array}

Get paths for a namespace

Parameters:
Name Type Description
namespace String

namespace

Returns:
Array -
  • array of paths.

getRegisteredPackages() → {Array}

Get all registered packages namespaces.

Returns:
Array -
  • array of namespaces.

getVersion(packageName) → {String}

Returns the environment or dependency version.

Parameters:
Name Type Description
packageName String

Module to get version.

Returns:
String -

Environment version.

help(name)

Outputs the general help and usage. Optionally, if generators have been registered, the list of available generators is also displayed.

Parameters:
Name Type Description
name String

installLocalGenerators(packages) → {Boolean}

Install generators at the custom local repository and register.

Parameters:
Name Type Description
packages Object

packages to install key(packageName): value(versionRange).

Returns:
Boolean -
  • true if the install succeeded.
Mixes In:

instantiate(generator, optionsopt)

Instantiate a Generator with metadatas

Parameters:
Name Type Attributes Description
generator Class.<Generator>

Generator class

options Object <optional>
Properties
Name Type Attributes Description
arguments Array | String <optional>

Arguments to pass the instance

options Object <optional>

Options to pass the instance

isPackageRegistered(packageNSopt) → {boolean}

Verify if a package namespace already have been registered.

Parameters:
Name Type Attributes Description
packageNS String <optional>

namespace of the package.

Returns:
boolean -
  • true if any generator of the package has been registered

lookup(optionsopt, cb) → {Array.<Object>}

Search for generators and their sub generators.

A generator is a :lookup/:name/index.js file placed inside an npm package.

Defaults lookups are:

  • ./
  • generators/
  • lib/generators/

So this index file node_modules/generator-dummy/lib/generators/yo/index.js would be registered as dummy:yo generator.

Parameters:
Name Type Attributes Description
options boolean | Object <optional>
Properties
Name Type Attributes Default Description
localOnly boolean <optional>
false

Set true to skip lookups of globally-installed generators.

packagePaths string | Array <optional>

Paths to look for generators.

npmPaths string | Array <optional>

Repository paths to look for generators packages.

filePatterns string | Array <optional>
'*\/index.js'

File pattern to look for.

packagePatterns string | Array <optional>
'generator-*'

Package pattern to look for.

singleResult boolean <optional>
false

Set true to stop lookup on the first match.

globbyDeep Number <optional>

Deep option to be passed to globby.

cb function

Callback called once the lookup is done. Take err as first parameter.

Returns:
Array.<Object> -

List of generators

Mixes In:

lookupLocalPackages(packagesToLookupopt)

Lookup and register generators from the custom local repository.

Parameters:
Name Type Attributes Default Description
packagesToLookup Array.<String> <optional>
'generator-*'

packages to lookup.

Mixes In:

namespace(filepath, lookups)

Given a String filepath, tries to figure out the relative namespace.

Examples:

this.namespace('backbone/all/index.js');
// => backbone:all

this.namespace('generator-backbone/model');
// => backbone:model

this.namespace('backbone.js');
// => backbone

this.namespace('generator-mocha/backbone/model/index.js');
// => mocha:backbone:model
Parameters:
Name Type Description
filepath String
lookups Array

paths

namespaces() → {Array}

Returns the list of registered namespace.

Returns:
Array

register(name, namespace, packagePath) → {Object}

Registers a specific generator to this environment. This generator is stored under provided namespace, or a default namespace format if none if available.

Parameters:
Name Type Description
name String

Filepath to the a generator or a npm package name

namespace String

Namespace under which register the generator (optional)

packagePath String

PackagePath to the generator npm package (optional)

Returns:
Object -

environment - This environment

registerStub(Generator, namespace, resolvedopt, packagePathopt) → {this}

Register a stubbed generator to this environment. This method allow to register raw functions under the provided namespace. registerStub will enforce the function passed to extend the Base generator automatically.

Parameters:
Name Type Attributes Description
Generator function

A Generator constructor or a simple function

namespace String

Namespace under which register the generator

resolved String <optional>

The file path to the generator

packagePath String <optional>

The generator's package path

Returns:
this

resolveModulePath(moduleId) → {String}

Resolve a module path

Parameters:
Name Type Description
moduleId String

Filepath or module name

Returns:
String -
  • The resolved path leading to the module

rootGenerator() → {Generator}

Get the first generator that was queued to run in this environment.

Returns:
Generator -

generator queued to run in this environment.

run(args, optionsopt, doneopt)

Tries to locate and run a specific generator. The lookup is done depending on the provided arguments, options and the list of registered generators.

When the environment was unable to resolve a generator, an error is raised.

Parameters:
Name Type Attributes Description
args String | Array
options Object <optional>
done function <optional>

runGenerator(generator, doneopt)

Convenience method to run the generator with callbackWrapper. See https://github.com/yeoman/environment/pull/101

Parameters:
Name Type Attributes Description
generator Object
done function <optional>