roc

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <base data-ice="baseUrl" href="../../../"> <title data-ice="title">src/cli/helpers.js | API Document</title> <link type="text/css" rel="stylesheet" href="css/style.css"> <link type="text/css" rel="stylesheet" href="css/prettify-tomorrow.css"> <script src="script/prettify/prettify.js"></script> <script src="script/manual.js"></script> </head> <body class="layout-container" data-ice="rootContainer"> <header> <a href="./">Home</a> <a href="identifiers.html">Reference</a> <a href="source.html">Source</a> <a data-ice="repoURL" href="https://github.com/vgno/roc.git" class="repo-url-github">Repository</a> <div class="search-box"> <img src="./image/search.png"> <input class="search-input"> <ul class="search-result"></ul> </div> </header> <nav class="navigation" data-ice="nav"><div> <ul> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">cli</div>F<a href="function/index.html#static-function-execute">execute</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-buildCompleteConfig">buildCompleteConfig</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-generateCommandDocumentation">generateCommandDocumentation</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-generateCommandsDocumentation">generateCommandsDocumentation</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getMappings">getMappings</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getSuggestions">getSuggestions</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-parseArguments">parseArguments</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-parseOptions">parseOptions</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-runCli">runCli</a></li> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">commands</div>F<a href="function/index.html#static-function-init">init</a></li> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">commands/helpers</div>F<a href="function/index.html#static-function-validRocProject">validRocProject</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-get">get</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getVersions">getVersions</a></li> <li data-ice="doc">V<a href="variable/index.html#static-variable-defaultPrompt">defaultPrompt</a></li> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">configuration</div>F<a href="function/index.html#static-function-getApplicationConfig">getApplicationConfig</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-appendConfig">appendConfig</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-appendSettings">appendSettings</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getConfig">getConfig</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getSettings">getSettings</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-merge">merge</a></li> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">documentation</div>F<a href="function/index.html#static-function-buildDocumentationObject">buildDocumentationObject</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-generateTable">generateTable</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-addPadding">addPadding</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getDefaultValue">getDefaultValue</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-pad">pad</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-toCliFlag">toCliFlag</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-generateMarkdownDocumentation">generateMarkdownDocumentation</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-generateTextDocumentation">generateTextDocumentation</a></li> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">helpers</div>F<a href="function/index.html#static-function-fileExists">fileExists</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getAbsolutePath">getAbsolutePath</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getPackageJson">getPackageJson</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-getRocDependencies">getRocDependencies</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-error">error</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-errorLabel">errorLabel</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-important">important</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-importantLabel">importantLabel</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-ok">ok</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-okLabel">okLabel</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-warning">warning</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-warningLabel">warningLabel</a></li> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">typedef</div>T<a href="typedef/index.html#static-typedef-infoObject">infoObject</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocCommandObject">rocCommandObject</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocConfig">rocConfig</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocDocumentationObject">rocDocumentationObject</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocMapObject">rocMapObject</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocMetaConfig">rocMetaConfig</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocMetaSettings">rocMetaSettings</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocMetaSettings">rocMetaSettings</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocOptions">rocOptions</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocSettings">rocSettings</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocTableHeader">rocTableHeader</a></li> <li data-ice="doc">T<a href="typedef/index.html#static-typedef-rocTableSettings">rocTableSettings</a></li> <li data-ice="doc"><div data-ice="dirPath" class="nav-dir-path">validation</div>F<a href="function/index.html#static-function-isValid">isValid</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-throwError">throwError</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-validate">validate</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-validateMightThrow">validateMightThrow</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-isArray">isArray</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-isArrayOrSingle">isArrayOrSingle</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-isBoolean">isBoolean</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-isInteger">isInteger</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-isObject">isObject</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-isPath">isPath</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-isString">isString</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-oneOf">oneOf</a></li> <li data-ice="doc">F<a href="function/index.html#static-function-required">required</a></li> </ul> </div> </nav> <div class="content" data-ice="content"><h1 data-ice="title">src/cli/helpers.js</h1> <pre class="source-code line-number raw-source-code"><code class="prettyprint linenums" data-ice="content">import 'source-map-support/register'; import chalk from 'chalk'; import { isPlainObject, isBoolean, isString, set, difference } from 'lodash'; import resolve from 'resolve'; import leven from 'leven'; import trimNewlines from 'trim-newlines'; import redent from 'redent'; import { merge } from '../configuration'; import buildDocumentationObject from '../documentation/build-documentation-object'; import generateTable from '../documentation/generate-table'; import { getDefaultValue } from '../documentation/helpers'; import { fileExists, getRocDependencies, getPackageJson } from '../helpers'; import { throwError } from '../validation'; import { isValid } from '../validation'; import { warning, importantLabel, errorLabel, warningLabel } from '../helpers/style'; /** * Builds the complete configuration objects. * * @param {boolean} debug - If debug mode should be enabled, logs some extra information. * @param {rocConfig} config - The base configuration. * @param {rocMetaConfig} meta - The base meta configuration. * @param {rocConfig} newConfig - The new configuration to base the merge on. * @param {rocMetaConfig} newMeta - The new meta configuration to base the merge on. * @param {string} [directory=process.cwd()] - The directory to resolve relative paths from. * @param {boolean} [validate=true] - If the newConfig and the newMeta structure should be validated. * * @returns {Object} - The result of with the built configurations. * @property {rocConfig} extensionConfig - The extensions merged configurations * @property {rocConfig} config - The final configuration, with application configuration. * @property {rocMetaConfig} meta - The merged meta configuration. */ export function buildCompleteConfig( debug, config = {}, meta = {}, newConfig = {}, newMeta = {}, directory = process.cwd(), validate = true ) { let finalConfig = { ...config }; let finalMeta = { ...meta }; let usedExtensions = []; const mergeExtension = (extensionName) => { const { baseConfig, metaConfig = {} } = getExtension(extensionName, directory); if (baseConfig) { usedExtensions.push(extensionName); finalConfig = merge(finalConfig, baseConfig); finalMeta = merge(finalMeta, metaConfig); } }; if (fileExists('package.json', directory)) { // If extensions are defined we will use them to merge the configurations if (newConfig.extensions && newConfig.extensions.length) { newConfig.extensions.forEach(mergeExtension); } else { const packageJson = getPackageJson(directory); getRocDependencies(packageJson) .forEach(mergeExtension); } if (usedExtensions.length && debug) { console.log(importantLabel('The following Roc extensions will be used:'), usedExtensions, '\n'); } // Check for a mismatch between application configuration and extensions. if (validate) { if (Object.keys(newConfig).length) { console.log(validateConfigurationStructure(finalConfig, newConfig)); } if (Object.keys(newMeta).length) { console.log(validateConfigurationStructure(finalMeta, newMeta)); } } } return { extensionConfig: finalConfig, config: merge(finalConfig, newConfig), meta: merge(finalMeta, newMeta) }; } function getExtension(extensionName, directory) { try { const { baseConfig, metaConfig } = require(resolve.sync(extensionName, { basedir: directory })); return { baseConfig, metaConfig }; } catch (err) { console.log( errorLabel( 'Failed to load Roc extension ' + chalk.bold(extensionName) + '. ' + 'Make sure you have it installed. Try running:' ) + ' ' + chalk.underline('npm install --save ' + extensionName) , '\n'); return {}; } } function validateConfigurationStructure(config, applicationConfig) { const getKeys = (obj, oldPath = '', allKeys = []) => { Object.keys(obj).forEach((key) => { const value = obj[key]; const newPath = oldPath + key; if (isPlainObject(value)) { getKeys(value, newPath + '.', allKeys); } else { allKeys.push(newPath); } }); return allKeys; }; const info = []; const keys = getKeys(config); const diff = difference(getKeys(applicationConfig), keys); if (diff.length > 0) { info.push(errorLabel('Configuration problem') + ' There was a mismatch in the application configuration structure, make sure this is correct.\n'); info.push(getSuggestions(diff, keys)); info.push(''); } // } return info.join('\n'); } /** * Will create a string with suggestions for possible typos. * * @param {string[]} current - The current values that might be incorrect. * @param {string[]} possible - All the possible correct values. * @param {boolean} [command=false] - If the suggestion should be managed as a command. * * @returns {string} - A string with possible suggestions for typos. */ export function getSuggestions(current, possible, command = false) { const info = []; current.forEach((currentKey) => { let shortest = 0; let closest; for (let key of possible) { let distance = leven(currentKey, key); if (distance <= 0 || distance > 4) { continue; } if (shortest && distance >= shortest) { continue; } closest = key; shortest = distance; } const extra = command ? '--' : ''; if (closest) { info.push('Did not understand ' + chalk.underline(extra + currentKey) + ' - Did you mean ' + chalk.underline(extra + closest)); } else { info.push('Did not understand ' + chalk.underline(extra + currentKey)); } }); return info.join('\n'); } /** * Generates a string with information about all the possible commands. * * @param {rocConfig} commands - The Roc config object, uses commands from it. * @param {rocMetaConfig} commandsmeta - The Roc meta config object, uses commands from it. * * @returns {string} - A string with documentation based on the available commands. */ export function generateCommandsDocumentation({ commands }, { commands: commandsMeta }) { const header = { name: true, description: true }; const noCommands = {'No commands available.': ''}; commandsMeta = commandsMeta || {}; let body = [{ name: 'Commands', objects: Object.keys(commands || noCommands).map((command) => { const options = commandsMeta[command] ? ' ' + getCommandOptionsAsString(commandsMeta[command]) : ''; const description = commandsMeta[command] && commandsMeta[command].description ? commandsMeta[command].description : ''; return { name: (command + options), description }; }) }]; return generateCommandDocsHelper(body, header, 'Options', 'name'); } function getCommandOptionsAsString(command = {}) { let options = ''; (command.options || []).forEach((option) => { options += option.required ? `<${option.name}> ` : `[${option.name}] `; }); return options; } /** * Generates a string with information about a specific command. * * @param {rocConfig} settings - The Roc config object, uses settings from it. * @param {rocMetaConfig} commands+meta - The Roc meta config object, uses commands and settings from it. * @param {string} command - The selected command. * @param {string} name - The name of the cli. * * @returns {string} - A string with documentation based on the selected commands. */ export function generateCommandDocumentation({ settings }, { commands = {}, settings: meta }, command, name) { const rows = []; rows.push('Usage: ' + name + ' ' + command + ' ' + getCommandOptionsAsString(commands[command])); rows.push(''); if (commands[command] && commands[command].help) { rows.push(redent(trimNewlines(commands[command].help))); rows.push(''); } let body = []; // Generate the options table if (commands[command] && commands[command].settings) { rows.push('Options:'); rows.push(''); const filter = commands[command].settings === true ? [] : commands[command].settings; body = buildDocumentationObject(settings, meta, filter); } const header = { cli: true, description: { name: 'Description', padding: false }, defaultValue: { name: 'Default', renderer: (input) => { input = getDefaultValue(input); if (input === undefined) { return ''; } if (!input) { return warning('No default value'); } return chalk.cyan(input); } } }; rows.push(generateCommandDocsHelper(body, header, 'CLI options', 'cli')); return rows.join('\n'); } function generateCommandDocsHelper(body, header, options, name) { body.push({ name: options, objects: [{ [name]: '-h, --help', description: 'Output usage information.' }, { [name]: '-v, --version', description: 'Output version number.' }, { [name]: '-d, --debug', description: 'Enable debug mode.' }, { [name]: '-c, --config', description: `Path to configuration file, will default to ${chalk.bold('roc.config.js')} in current ` + `working directory.` }, { [name]: '-D, --directory', description: 'Path to working directory, will default to the current working directory. Can be either ' + 'absolute or relative.' }] }); return generateTable(body, header, { compact: true, titleWrapper: (input) => input + ':', cellDivider: '', rowWrapper: (input) => `${input}`, header: false, groupTitleWrapper: (input) => input + ':' }); } /** * Parses options and validates them. * * @param {string} command - The command to parse options for. * @param {Object} commands - commands from {@link rocMetaConfig}. * @param {Object[]} options - Options parsed by minimist. * * @returns {Object} - Parsed options. * @property {object[]} options - The parsed options that was matched against the meta configuration for the command. * @property {object[]} rest - The rest of the options that could not be matched against the configuration. */ export function parseOptions(command, commands, options) { // If the command supports options if (commands[command] && commands[command].options) { let parsedOptions = {}; commands[command].options.forEach((option, index) => { const value = options[index]; if (option.required && !value) { throw new Error(`Required option "${option.name}" was not provided.`); } if (value && option.validation) { const validationResult = isValid(value, option.validation); if (validationResult !== true) { try { throwError(option.name, validationResult, value, 'option'); } catch (err) { /* eslint-disable no-process-exit, no-console */ console.log(errorLabel('Arguments problem') + ' An option was not valid.\n'); console.log(err.message); process.exit(1); /* eslint-enable */ } } } parsedOptions[option.name] = value; }); return { options: parsedOptions, rest: options.splice(Object.keys(parsedOptions).length) }; } return { options: undefined, rest: options }; } /** * Creates mappings between cli commands to their "path" in the configuration structure, their validator and type * convertor. * * @param {rocDocumentationObject} documentationObject - Documentation object to create mappings for. * * @returns {Object} - Properties are the cli command without leading dashes that maps to a {@link rocMapObject}. */ export function getMappings(documentationObject) { const recursiveHelper = (groups) => { let mappings = {}; groups.forEach((group) => { group.objects.forEach((element) => { // Remove the two dashes in the beginning to match correctly mappings[element.cli.substr(2)] = { name: element.cli, path: element.path, convertor: getConvertor(element.defaultValue, element.cli), validator: element.validator }; }); mappings = Object.assign({}, mappings, recursiveHelper(group.children)); }); return mappings; }; return recursiveHelper(documentationObject); } // Convert values based on their default value function getConvertor(value, name) { if (isBoolean(value)) { return (input) => { if (isBoolean(input)) { return input; } if (input === 'true' || input === 'false') { return input === 'true'; } console.log( warningLabel(`Invalid value given for ${chalk.bold(name)}.`), `Will use the default ${chalk.bold(value)}.` ); return value; }; } else if (Array.isArray(value)) { return (input) => { let parsed; try { parsed = JSON.parse(input); } catch (err) { // Ignore this case } if (Array.isArray(parsed)) { return parsed; } return input.toString().split(','); }; } else if (Number.isInteger(value)) { return (input) => parseInt(input, 10); } else if (!isString(value) && (!value || Object.keys(value).length === 0)) { return (input) => JSON.parse(input); } return (input) => input; } /** * Converts a set of arguments to {@link rocConfigSettings} object. * * @param {Object} args - Arguments parsed from minimist. * @param {Object} mappings - Result from {@link getMappings}. * * @returns {Object} - The mapped Roc configuration settings object. */ export function parseArguments(args, mappings) { const config = {}; const info = []; Object.keys(args).forEach((key) => { if (mappings[key]) { const value = convert(args[key], mappings[key]); set(config, mappings[key].path, value); } else { // We did not find a match info.push(getSuggestions([key], Object.keys(mappings), true)); } }); if (info.length > 0) { console.log(errorLabel('CLI problem'), 'Some commands were not understood.\n'); console.log(info.join('\n') + '\n'); } return config; } function convert(value, mapping) { const val = mapping.convertor(value); const validationResult = isValid(val, mapping.validator); if (validationResult === true) { return val; } console.log( warning(`There was a problem when trying to automatically convert ${chalk.bold(mapping.name)}. This ` + `value will be ignored.`) ); console.log( `Received ${chalk.underline(value)} and it was converted to ${chalk.underline(val)}.`, validationResult, '\n' ); } </code></pre> </div> <footer class="footer"> Generated by <a href="https://esdoc.org">ESDoc(0.4.3)</a> </footer> <script src="script/search_index.js"></script> <script src="script/search.js"></script> <script src="script/pretty-print.js"></script> <script src="script/inherited-summary.js"></script> <script src="script/test-summary.js"></script> <script src="script/inner-link.js"></script> <script src="script/patch-for-local.js"></script> </body> </html>