From a0a932b535a489101b5b457c16a2fd9b7f59c311 Mon Sep 17 00:00:00 2001 From: Peter Hale Date: Thu, 20 Jan 2022 14:39:49 -0700 Subject: [PATCH 1/2] fix: correct doc issues --- docs/aliases.md | 2 +- docs/args.md | 2 +- docs/base_class.md | 6 +++--- docs/commands.md | 4 ++-- docs/flags.md | 18 +++++++++--------- docs/prompting.md | 15 +++++++-------- docs/related_repos.md | 1 - docs/running_programmatically.md | 6 +++--- docs/spinner.md | 15 +++++++-------- docs/table.md | 25 ++++++++++++------------- 10 files changed, 45 insertions(+), 49 deletions(-) diff --git a/docs/aliases.md b/docs/aliases.md index 23dbc962..37fb832b 100644 --- a/docs/aliases.md +++ b/docs/aliases.md @@ -5,7 +5,7 @@ title: Aliases Aliases let you define a string that maps to a command. This command can be run as `mycli config`, `mycli config:index`, or `mycli config:list`: (this only applies to multi-CLIs) ```js -import Command, {flags} from '@oclif/core' +import {Command, Flags} from '@oclif/core' export class ConfigIndex extends Command { static aliases = ['config:index', 'config:list'] diff --git a/docs/args.md b/docs/args.md index 48642ed7..c954c2a9 100644 --- a/docs/args.md +++ b/docs/args.md @@ -5,7 +5,7 @@ title: Command Arguments Arguments are positional arguments passed to the command. For example, if this command was run with `mycli arg1 arg2` it would be declared like this: ```js -import Command from '@oclif/core' +import {Command} from '@oclif/core' export class MyCLI extends Command { static args = [ diff --git a/docs/base_class.md b/docs/base_class.md index 5e5f1f8d..e3719c18 100644 --- a/docs/base_class.md +++ b/docs/base_class.md @@ -8,11 +8,11 @@ For large CLIs with multiple plugins, it's useful to put this base class into it ```js // src/base.ts -import Command, {flags} from '@oclif/core' +import {Command, Flags} from '@oclif/core' export default abstract class extends Command { static flags = { - loglevel: flags.string({options: ['error', 'warn', 'info', 'debug']}) + loglevel: Flags.string({options: ['error', 'warn', 'info', 'debug']}) } log(msg, level) { @@ -46,7 +46,7 @@ import Command from '../base' export class MyCommand extends Command { static flags = { ...Command.flags, - extraflag: flags.string() + extraflag: Flags.string() } async run() { diff --git a/docs/commands.md b/docs/commands.md index 3177c032..014603c9 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -5,7 +5,7 @@ title: Commands A basic command looks like the following in TypeScript: ```js -import Command from '@oclif/core' +import {Command} from '@oclif/core' export class MyCommand extends Command { static description = 'description of this example command' @@ -41,7 +41,7 @@ Note that the following examples will be in TypeScript. As JavaScript does not y [See the base class to get an idea of what methods can be called on a command](https://github.com/oclif/core/blob/main/src/command.ts). ```js -import Command, {flags} from '@oclif/core' +import {Command, Flags} from '@oclif/core' export class MyCommand extends Command { static description = ` diff --git a/docs/flags.md b/docs/flags.md index bbe4bdf2..74bb9e1a 100644 --- a/docs/flags.md +++ b/docs/flags.md @@ -13,13 +13,13 @@ $ mycli --force --file=./myfile It would be declared like this: ```js -import Command, {flags} from '@oclif/core' +import Command, {Flags} from '@oclif/core' export class MyCLI extends Command { static flags = { // can pass either --force or -f - force: flags.boolean({char: 'f'}), - file: flags.string(), + force: Flags.boolean({char: 'f'}), + file: Flags.string(), } async run() { @@ -36,7 +36,7 @@ Here are the options flags can have: ```js static flags = { - name: flags.string({ + name: Flags.string({ char: 'n', // shorter flag version description: 'name to print', // help description for flag hidden: false, // hide from help @@ -51,7 +51,7 @@ static flags = { }), // flag with no value (-f, --force) - force: flags.boolean({ + force: Flags.boolean({ char: 'f', default: true, // default value if flag not passed (can be a function that returns a boolean) // boolean flags may be reversed with `--no-` (in this case: `--no-force`). @@ -68,11 +68,11 @@ For larger CLIs, it can be useful to declare a custom flag that can be shared am ```js // src/flags.ts -import {flags} from '@oclif/core' -function getTeam() { +import {Flags} from '@oclif/core' +function getTeam(): Promise { // imagine this reads a configuration file or something to find the team } -export const team = flags.build({ +export const team = Flags.build({ char: 't', description: 'team to use', default: () => getTeam(), @@ -80,7 +80,7 @@ export const team = flags.build({ // src/commands/mycommand.ts import {team} from '../flags' -import Command from '@oclif/core' +import {Command} from '@oclif/core' export class MyCLI extends Command { static flags = { diff --git a/docs/prompting.md b/docs/prompting.md index a0ff49e3..d284f6ec 100644 --- a/docs/prompting.md +++ b/docs/prompting.md @@ -5,24 +5,23 @@ title: Prompting [cli-ux](https://github.com/oclif/cli-ux) provides a simple `cli.prompt()` function, for more complex input prompts, we recommend using the [inquirer](https://github.com/SBoudrias/Inquirer.js) library. -## `cli.prompt()` +## `CliUx.ux.prompt()` Prompt for basic input with `cli-ux`: ```typescript -import {Command} from '@oclif/core' -import cli from 'cli-ux' +import {Command, CliUx} from '@oclif/core' export class MyCommand extends Command { async run() { // just prompt for input - const name = await cli.prompt('What is your name?') + const name = await CliUx.ux.prompt('What is your name?') // mask input after enter is pressed - const secondFactor = await cli.prompt('What is your two-factor token?', {type: 'mask'}) + const secondFactor = await CliUx.ux.prompt('What is your two-factor token?', {type: 'mask'}) // hide input while typing - const password = await cli.prompt('What is your password?', {type: 'hide'}) + const password = await CliUx.ux.prompt('What is your password?', {type: 'hide'}) this.log(`You entered: ${name}, ${secondFactor}, ${password}`) } @@ -38,12 +37,12 @@ Demo: Here is an example command that uses [inquirer](https://github.com/SBoudrias/Inquirer.js). You will need to add `inquirer` and `@types/inquirer` (for TypeScript CLIs) for this to work. ```typescript -import {Command, flags} from '@oclif/core' +import {Command, Flags} from '@oclif/core' import * as inquirer from 'inquirer' export class MyCommand extends Command { static flags = { - stage: flags.string({options: ['development', 'staging', 'production']}) + stage: Flags.string({options: ['development', 'staging', 'production']}) } async run() { diff --git a/docs/related_repos.md b/docs/related_repos.md index 0c5cfb9e..7c1c84f0 100644 --- a/docs/related_repos.md +++ b/docs/related_repos.md @@ -3,5 +3,4 @@ title: Related Repositories --- * [@oclif/core](https://github.com/oclif/core) - Base library for oclif CLIs or plugins. This can be used directly without the generator. -* [@oclif/cli-ux](https://github.com/oclif/cli-ux) - Library for common CLI UI utilities. * [@oclif/test](https://github.com/oclif/test) - Test helper for oclif. diff --git a/docs/running_programmatically.md b/docs/running_programmatically.md index 1b9f8ff6..8a395c5e 100644 --- a/docs/running_programmatically.md +++ b/docs/running_programmatically.md @@ -15,7 +15,7 @@ For example, if we use `heroku config` as an example, we could have a command th ```typescript export class HerokuConfig extends Command { static flags = { - app: flags.string({required: true}) + app: Flags.string({required: true}) } async run() { @@ -37,7 +37,7 @@ import {displayConfigVars} from '../display_config_vars' export class HerokuRelease extends Command { static flags = { - app: flags.string({required: true}) + app: Flags.string({required: true}) } async run() { @@ -72,7 +72,7 @@ import {HerokuConfig} from './config' export class HerokuRelease extends Command { static flags = { - app: flags.string({required: true}) + app: Flags.string({required: true}) } async run() { diff --git a/docs/spinner.md b/docs/spinner.md index aaaa95ac..5894cada 100644 --- a/docs/spinner.md +++ b/docs/spinner.md @@ -2,29 +2,28 @@ title: Spinner --- -[cli-ux](https://github.com/oclif/cli-ux) provides a simple `cli.action`, for more complex progress indicators we recommend using the [listr](https://www.npmjs.com/package/listr) library. +[@oclif/core](https://github.com/oclif/core) provides a simple `ux.action`, for more complex progress indicators we recommend using the [listr](https://www.npmjs.com/package/listr) library. -## `cli-ux.action` +## `CliUx.ux.action` Shows a basic spinner ```typescript -import {Command} from '@oclif/core' -import cli from 'cli-ux' +import {Command, CliUx} from '@oclif/core' export class MyCommand extends Command { async run() { // start the spinner - cli.action.start('starting a process') + CliUx.ux.action.start('starting a process') // do some action... // stop the spinner - cli.action.stop() // shows 'starting a process... done' + CliUx.ux.action.stop() // shows 'starting a process... done' // show on stdout instead of stderr - cli.action.start('starting a process', 'initializing', {stdout: true}) + CliUx.ux.action.start('starting a process', 'initializing', {stdout: true}) // do some action... // stop the spinner with a custom message - cli.action.stop('custom message') // shows 'starting a process... custom message' + CliUx.ux.action.stop('custom message') // shows 'starting a process... custom message' } } ``` diff --git a/docs/table.md b/docs/table.md index 0b61778a..7e942d06 100644 --- a/docs/table.md +++ b/docs/table.md @@ -2,21 +2,21 @@ title: Table --- -## `cli-ux.table` +## `CliUx.ux.table` Displays tabular data ```typescript -cli.table(data, columns, options) +CliUx.ux.table(data, columns, options) ``` Where: - `data`: array of data objects to display -- `columns`: [Table.Columns](https://github.com/oclif/cli-ux/blob/master/src/styled/table.ts) -- `options`: [Table.Options](https://github.com/oclif/cli-ux/blob/master/src/styled/table.ts) +- `columns`: [Table.Columns](https://github.com/oclif/core/blob/main/src/cli-ux/styled/table.ts) +- `options`: [Table.Options](https://github.com/oclif/core/blob/main/src/cli-ux/styled/table.ts) -`cli.table.flags()` returns an object containing all the table flags to include in your command. +`CliUx.ux.table.flags()` returns an object containing all the table flags to include in your command. ```typescript { @@ -32,10 +32,10 @@ Where: Passing `{only: ['columns']}` or `{except: ['columns']}` as an argument into `cli.table.flags()` will allow/block those flags from the returned object. -`Table.Columns` defines the table columns and their display options. +`CliUx.Table.Columns` defines the table columns and their display options. ```typescript -const columns: Table.Columns = { +const columns: CliUx.Table.Columns = { // where `.name` is a property of a data object name: {}, // "Name" inferred as the column header id: { @@ -47,10 +47,10 @@ const columns: Table.Columns = { } ``` -`Table.Options` defines the table options, most of which are the parsed flags from the user for display customization, all of which are optional. +`CliUx.Table.Options` defines the table options, most of which are the parsed flags from the user for display customization, all of which are optional. ```typescript -const options: Table.Options = { +const options: CliUx.Table.Options = { printLine: myLogger, // custom logger columns: flags.columns, sort: flags.sort, @@ -65,20 +65,19 @@ const options: Table.Options = { Example class: ```typescript -import {Command} from '@oclif/core' -import {cli} from 'cli-ux' +import {Command, CliUx} from '@oclif/core' import axios from 'axios' export default class Users extends Command { static flags = { - ...cli.table.flags() + ...CliUx.ux.table.flags() } async run() { const {flags} = this.parse(Users) const {data: users} = await axios.get('https://jsonplaceholder.typicode.com/users') - cli.table(users, { + CliUx.ux.table(users, { name: { minWidth: 7, }, From 9fd7d8ae92fac7e2489a335d2d98baf21e697a17 Mon Sep 17 00:00:00 2001 From: Peter Hale Date: Thu, 20 Jan 2022 15:16:00 -0700 Subject: [PATCH 2/2] chore: apply changes from review comments --- docs/flags.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/flags.md b/docs/flags.md index 74bb9e1a..d9321ca7 100644 --- a/docs/flags.md +++ b/docs/flags.md @@ -13,7 +13,7 @@ $ mycli --force --file=./myfile It would be declared like this: ```js -import Command, {Flags} from '@oclif/core' +import {Command, Flags} from '@oclif/core' export class MyCLI extends Command { static flags = {