Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: correct doc issues #136

Merged
merged 2 commits into from
Jan 26, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/aliases.md
Original file line number Diff line number Diff line change
Expand Up @@ -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']
Expand Down
2 changes: 1 addition & 1 deletion docs/args.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [
Expand Down
6 changes: 3 additions & 3 deletions docs/base_class.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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() {
Expand Down
4 changes: 2 additions & 2 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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 = `
Expand Down
18 changes: 9 additions & 9 deletions docs/flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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() {
Expand All @@ -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
Expand All @@ -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`).
Expand All @@ -68,19 +68,19 @@ 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<string> {
// 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(),
})

// 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 = {
Expand Down
15 changes: 7 additions & 8 deletions docs/prompting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}`)
}
Expand All @@ -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() {
Expand Down
1 change: 0 additions & 1 deletion docs/related_repos.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
6 changes: 3 additions & 3 deletions docs/running_programmatically.md
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand All @@ -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() {
Expand Down Expand Up @@ -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() {
Expand Down
15 changes: 7 additions & 8 deletions docs/spinner.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
}
}
```
Expand Down
25 changes: 12 additions & 13 deletions docs/table.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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: {
Expand All @@ -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,
Expand All @@ -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,
},
Expand Down