effect 4.0.5 → 4.0.7

package/src/cli/Flag.ts

@@ -712,6 +712,123 @@ export const withOptionalValue: {
   <A>(self: Flag<A>, value: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, value: string) => Param.withOptionalValue(self, value))
 
+/**
+ * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+ *
+ * **Details**
+ *
+ * The new name replaces the default, so `--no-<name>` is no longer accepted
+ * and shell completions offer the new name instead. Has no effect on
+ * non-boolean flags.
+ *
+ * **Example** (Renaming a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const validate = Flag.Boolean("validate").pipe(
+ *   Flag.withDefault(true),
+ *   Flag.withNegation("skip-validate")
+ * )
+ * // --validate       => true
+ * // --skip-validate  => false
+ * // --no-validate    => unrecognized flag
+ * validate.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withNegation: {
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted
+   * and shell completions offer the new name instead. Has no effect on
+   * non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const validate = Flag.Boolean("validate").pipe(
+   *   Flag.withDefault(true),
+   *   Flag.withNegation("skip-validate")
+   * )
+   * // --validate       => true
+   * // --skip-validate  => false
+   * // --no-validate    => unrecognized flag
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (name: string): <A>(self: Flag<A>) => Flag<A>
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted
+   * and shell completions offer the new name instead. Has no effect on
+   * non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const validate = Flag.Boolean("validate").pipe(
+   *   Flag.withDefault(true),
+   *   Flag.withNegation("skip-validate")
+   * )
+   * // --validate       => true
+   * // --skip-validate  => false
+   * // --no-validate    => unrecognized flag
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Flag<A>, name: string): Flag<A>
+} = dual(2, <A>(self: Flag<A>, name: string) => Param.withNegation(self, name))
+
+/**
+ * Removes the negated `--no-<name>` form of a boolean flag.
+ *
+ * **Details**
+ *
+ * The negated form is then rejected as an unrecognized flag and left out of
+ * shell completions. Has no effect on non-boolean flags.
+ *
+ * **Example** (Disabling a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const unsafe = Flag.Boolean("unsafe").pipe(
+ *   Flag.withDefault(false),
+ *   Flag.withoutNegation
+ * )
+ * // --unsafe     => true
+ * // --no-unsafe  => unrecognized flag
+ * unsafe.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withoutNegation = <A>(self: Flag<A>): Flag<A> => Param.withoutNegation(self)
+
 // -------------------------------------------------------------------------------------
 // metadata
 // -------------------------------------------------------------------------------------
@@ -1038,6 +1155,11 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required flag is missing.
  *
+ * **Gotchas**
+ *
+ * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+ * the original `MissingOption` error is returned.
+ *
  * **Example** (Falling back to prompts)
  *
  * ```ts import.meta.vitest
@@ -1057,6 +1179,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required flag is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingOption` error is returned.
+   *
    * **Example** (Falling back to prompts)
    *
    * ```ts import.meta.vitest
@@ -1076,6 +1203,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required flag is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingOption` error is returned.
+   *
    * **Example** (Falling back to prompts)
    *
    * ```ts import.meta.vitest

package/src/cli/GlobalFlag.ts

@@ -21,7 +21,6 @@ import * as CliOutput from "./CliOutput.ts"
 import type * as Command from "./Command.ts"
 import * as Completions_ from "./Completions.ts"
 import * as Flag from "./Flag.ts"
-import * as CommandDescriptor from "./internal/completions/descriptor.ts"
 import * as HelpInternal from "./internal/help.ts"
 
 /* ========================================================================== */
@@ -169,9 +168,9 @@ export const Help: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { builtIns, command, commandPath }) {
-    const formatter = yield* CliOutput.Formatter
+    const presenter = yield* CliOutput.Presenter
     const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, builtIns)
-    yield* Console.log(formatter.formatHelpDoc(helpDoc))
+    yield* presenter.present({ _tag: "Help", reason: "Requested", commandPath, helpDoc })
   })
 })
 
@@ -193,8 +192,8 @@ export const Version: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { command, version }) {
-    const formatter = yield* CliOutput.Formatter
-    yield* Console.log(formatter.formatVersion(command.name, version))
+    const presenter = yield* CliOutput.Presenter
+    yield* presenter.present({ _tag: "Version", name: command.name, version })
   })
 })
 
@@ -249,7 +248,7 @@ export const Completions: Action<Option.Option<Completions_.Shell>> = Action({
   ),
   run: Effect.fnUntraced(function*(shell, { command }) {
     if (Option.isNone(shell)) return
-    const descriptor = CommandDescriptor.fromCommand(command)
+    const descriptor = Completions_.fromCommand(command)
     yield* Console.log(
       Completions_.generate(command.name, shell.value, descriptor)
     )

package/src/cli/Param.ts

@@ -25,6 +25,7 @@ import * as CliError from "./CliError.ts"
 import type { Environment } from "./Command.ts"
 import * as Primitive from "./Primitive.ts"
 import * as Prompt from "./Prompt.ts"
+import * as TerminalCapabilities from "./TerminalCapabilities.ts"
 
 const TypeId = "~effect/cli/Param"
 
@@ -217,6 +218,11 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
    * Raw value used for a bare flag. See `withOptionalValue`.
    */
   readonly optionalValue?: string | undefined
+  /**
+   * Long name that sets a boolean flag to `false`. `undefined` means the
+   * default `no-<name>`, `false` means no negated form. See `withNegation`.
+   */
+  readonly negation?: string | false | undefined
 }
 
 /**
@@ -367,6 +373,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly aliases?: ReadonlyArray<string> | undefined
   readonly hidden?: boolean | undefined
   readonly optionalValue?: string | undefined
+  readonly negation?: string | false | undefined
 }): Single<Kind, A> => {
   const parse: Parse<A> = (args) =>
     params.kind === argumentKind
@@ -1925,6 +1932,9 @@ export const withFallbackConfig: {
  *
  * This only handles missing options and missing arguments. Invalid values do not
  * prompt, and prompt cancellation re-fails with the original missing error.
+ * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+ * entirely: no prompt is built or shown, and the original missing error is
+ * returned.
  *
  * @see {@link FallbackPrompt} for accepted fallback prompt forms
  * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1952,6 +1962,9 @@ export const withFallbackPrompt: {
    *
    * This only handles missing options and missing arguments. Invalid values do not
    * prompt, and prompt cancellation re-fails with the original missing error.
+   * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+   * entirely: no prompt is built or shown, and the original missing error is
+   * returned.
    *
    * @see {@link FallbackPrompt} for accepted fallback prompt forms
    * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1979,6 +1992,9 @@ export const withFallbackPrompt: {
    *
    * This only handles missing options and missing arguments. Invalid values do not
    * prompt, and prompt cancellation re-fails with the original missing error.
+   * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+   * entirely: no prompt is built or shown, and the original missing error is
+   * returned.
    *
    * @see {@link FallbackPrompt} for accepted fallback prompt forms
    * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1993,11 +2009,16 @@ export const withFallbackPrompt: {
   self: Param<Kind, A>,
   prompt: FallbackPrompt<B>
 ): Param<Kind, A | B> => {
-  const runPrompt = (error: CliError.MissingOption | CliError.MissingArgument, args: ParsedArgs) =>
-    Effect.flatMap(Prompt.isPrompt(prompt) ? Effect.succeed(prompt) : prompt, Prompt.run).pipe(
-      Effect.map((value) => [args.arguments, value as A | B] as const),
-      Effect.catchTag("QuitError", () => Effect.fail(error))
-    )
+  const runPrompt = Effect.fnUntraced(function*(
+    error: CliError.MissingOption | CliError.MissingArgument,
+    args: ParsedArgs
+  ) {
+    const { canPrompt } = yield* TerminalCapabilities.TerminalCapabilities
+    if (!canPrompt) return yield* Effect.fail(error)
+    const built = Prompt.isPrompt(prompt) ? prompt : yield* prompt
+    const value = yield* Effect.catchTag(Prompt.run(built), "QuitError", () => Effect.fail(error))
+    return [args.arguments, value as A | B] as const
+  })
   return transform(
     self,
     (parse) => (args) =>
@@ -2760,6 +2781,122 @@ export const withOptionalValue: {
       optionalValue: value
     })))
 
+/**
+ * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+ *
+ * **Details**
+ *
+ * The new name replaces the default, so `--no-<name>` is no longer accepted.
+ * Has no effect on non-boolean flags.
+ *
+ * **Example** (Renaming a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Param } from "effect/cli"
+ *
+ * // --validate sets true, --skip-validate sets false
+ * const validate = Param.Boolean(Param.flagKind, "validate").pipe(
+ *   Param.withNegation("skip-validate")
+ * )
+ * validate.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withNegation: {
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted.
+   * Has no effect on non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * // --validate sets true, --skip-validate sets false
+   * const validate = Param.Boolean(Param.flagKind, "validate").pipe(
+   *   Param.withNegation("skip-validate")
+   * )
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (name: string): <A>(self: Param<typeof flagKind, A>) => Param<typeof flagKind, A>
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted.
+   * Has no effect on non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * // --validate sets true, --skip-validate sets false
+   * const validate = Param.Boolean(Param.flagKind, "validate").pipe(
+   *   Param.withNegation("skip-validate")
+   * )
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Param<typeof flagKind, A>, name: string): Param<typeof flagKind, A>
+} = dual(2, <A>(
+  self: Param<typeof flagKind, A>,
+  name: string
+) =>
+  transformSingle(self, (single) =>
+    makeSingle({
+      ...single,
+      negation: name
+    })))
+
+/**
+ * Removes the negated `--no-<name>` form of a boolean flag.
+ *
+ * **Details**
+ *
+ * The negated form is then rejected as an unrecognized flag and left out of
+ * shell completions. Has no effect on non-boolean flags.
+ *
+ * **Example** (Disabling a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Param } from "effect/cli"
+ *
+ * // --unsafe sets true, --no-unsafe is rejected
+ * const unsafe = Param.Boolean(Param.flagKind, "unsafe").pipe(
+ *   Param.withoutNegation
+ * )
+ * unsafe.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withoutNegation = <A>(self: Param<typeof flagKind, A>): Param<typeof flagKind, A> =>
+  transformSingle(self, (single) =>
+    makeSingle({
+      ...single,
+      negation: false
+    }))
+
 /**
  * Validates parsed values against a Schema, providing detailed error messages.
  *
@@ -3069,7 +3206,15 @@ const parseFlag: <A>(
     return yield* new CliError.MissingOption({ option: name })
   }
 
-  // Parse the first value (later we can handle multiple)
+  if (providedValues.length > 1) {
+    return yield* new CliError.InvalidValue({
+      option: name,
+      value: `${providedValues.length} occurrences`,
+      expected: "at most 1 value",
+      kind: "flag"
+    })
+  }
+
   const arg = providedValues[0]
   const value = yield* Effect.mapError(
     primitiveType.parse(arg),

package/src/cli/TerminalCapabilities.ts

@@ -0,0 +1,159 @@
+/**
+ * Detection of whether a CLI can color, animate, or prompt.
+ *
+ * The default reads `NO_COLOR`, `FORCE_COLOR`, `TERM`, and the TTY state of
+ * the current process. The layer reads the same variables through
+ * `ConfigProvider`, plus the TTY state of `Stdio`. Unless a
+ * `CliOutput.Formatter` is provided, the built-in help, version, and error
+ * output of `Command` follows `canColor`. Fallback prompts added with
+ * `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` only run when
+ * `canPrompt` is `true`.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Config from "../Config.ts"
+import * as Context from "../Context.ts"
+import * as Effect from "../Effect.ts"
+import * as Layer from "../Layer.ts"
+import * as Option from "../Option.ts"
+import * as Stdio from "../Stdio.ts"
+
+/**
+ * Terminal rendering flags for the current process.
+ *
+ * **Details**
+ *
+ * `canColor` says whether styling will be rendered rather than stored as
+ * bytes. `canAnimate` says whether output is being watched, so pacing means
+ * something. `canPrompt` says whether a question can be asked and answered.
+ * The built-in `Command` output reads `canColor`, and fallback prompts for
+ * missing flags and arguments are skipped when `canPrompt` is `false`.
+ * `canAnimate` is for application code that renders its own output.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface TerminalCapabilities {
+  readonly canColor: boolean
+  readonly canAnimate: boolean
+  readonly canPrompt: boolean
+}
+
+/**
+ * Reference to the terminal capabilities of the current process.
+ *
+ * **When to use**
+ *
+ * Use when application output should share the built-in help, version, and
+ * error output's answer. Provide `layer` to detect through
+ * `ConfigProvider` and `Stdio`, or provide a value to override detection.
+ *
+ * **Details**
+ *
+ * The default is detected from the current process the first time it is
+ * read, so later changes to the environment do not affect it. Without a
+ * `process` global, every flag is `false`.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export const TerminalCapabilities: Context.Reference<TerminalCapabilities> = Context.Reference(
+  "effect/cli/TerminalCapabilities",
+  { defaultValue: () => fromProcess() }
+)
+
+const isPresent = (value: string | undefined): value is string => value !== undefined && value.length > 0
+
+const isForcingColor = (value: string | undefined): boolean =>
+  isPresent(value) && value !== "0" && value.toLowerCase() !== "false"
+
+const detect = (input: {
+  readonly noColor: string | undefined
+  readonly forceColor: string | undefined
+  readonly term: string | undefined
+  readonly stdinIsTerminal: boolean
+  readonly stdoutIsTerminal: boolean
+}): TerminalCapabilities => {
+  if (input.term === "dumb") {
+    return { canColor: false, canAnimate: false, canPrompt: false }
+  }
+
+  return {
+    canColor: !isPresent(input.noColor) && (isForcingColor(input.forceColor) || input.stdoutIsTerminal),
+    canAnimate: input.stdoutIsTerminal,
+    canPrompt: input.stdinIsTerminal && input.stdoutIsTerminal
+  }
+}
+
+const fromProcess = (): TerminalCapabilities => {
+  const process = (globalThis as any).process
+  return detect({
+    noColor: process?.env?.NO_COLOR,
+    forceColor: process?.env?.FORCE_COLOR,
+    term: process?.env?.TERM,
+    stdinIsTerminal: process?.stdin?.isTTY === true,
+    stdoutIsTerminal: process?.stdout?.isTTY === true
+  })
+}
+
+const environment = Config.all({
+  noColor: Config.option(Config.String("NO_COLOR")),
+  forceColor: Config.option(Config.String("FORCE_COLOR")),
+  term: Config.option(Config.String("TERM"))
+})
+
+/**
+ * Detects terminal capabilities from `Stdio` and the current `ConfigProvider`.
+ *
+ * **Details**
+ *
+ * `TERM=dumb` clears all three flags, because a terminal that cannot move the
+ * cursor can neither animate nor redraw a prompt. Otherwise `NO_COLOR`, when
+ * set to any non-empty value, disables color and wins over `FORCE_COLOR`.
+ * `FORCE_COLOR` forces color even off a TTY, except for `0` and `false`, which
+ * mean "not forcing". Empty variables count as unset, matching
+ * `ConfigProvider.fromEnv`, so `FORCE_COLOR=` does not force color on.
+ * `canPrompt` requires both standard input and standard output to be
+ * terminals. A `ConfigProvider` fault is a defect, so the layer never fails.
+ *
+ * **Example** (NO_COLOR wins over FORCE_COLOR)
+ *
+ * ```ts import.meta.vitest
+ * import { ConfigProvider, Effect, Stdio } from "effect"
+ * import { TerminalCapabilities } from "effect/cli"
+ *
+ * const program = Effect.gen(function*() {
+ *   const caps = yield* TerminalCapabilities.TerminalCapabilities
+ *   return caps.canColor
+ * }).pipe(
+ *   Effect.provide(TerminalCapabilities.layer),
+ *   Effect.provide(Stdio.layerTest({ stdoutIsTerminal: Effect.succeed(true) })),
+ *   Effect.provideService(
+ *     ConfigProvider.ConfigProvider,
+ *     ConfigProvider.fromEnv({ env: { NO_COLOR: "1", FORCE_COLOR: "1" } })
+ *   )
+ * )
+ *
+ * Effect.runSync(program) // => false
+ * ```
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer: Layer.Layer<never, never, Stdio.Stdio> = Layer.effect(
+  TerminalCapabilities
+)(Effect.gen(function*() {
+  const stdio = yield* Stdio.Stdio
+  const env = yield* Effect.orDie(environment)
+  return detect({
+    noColor: Option.getOrUndefined(env.noColor),
+    forceColor: Option.getOrUndefined(env.forceColor),
+    term: Option.getOrUndefined(env.term),
+    stdinIsTerminal: yield* stdio.stdinIsTerminal,
+    stdoutIsTerminal: yield* stdio.stdoutIsTerminal
+  })
+}))

package/src/cli/index.ts

@@ -76,3 +76,9 @@ export * as Primitive from "./Primitive.ts"
  * @since 4.0.0
  */
 export * as Prompt from "./Prompt.ts"
+
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as TerminalCapabilities from "./TerminalCapabilities.ts"

package/src/cli/internal/command.ts

@@ -48,6 +48,7 @@ export interface CommandInternal<Name extends string, Input, E, R, ContextInput>
     commandPath: ReadonlyArray<string>
   ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
   readonly buildHelpDoc: (commandPath: ReadonlyArray<string>) => HelpDoc
+  readonly resolveExamples: (commandPath: ReadonlyArray<string>) => ReadonlyArray<Command.Example>
 }
 
 /* ========================================================================== */
@@ -99,7 +100,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   readonly shortDescription?: string | undefined
   readonly alias?: string | undefined
   readonly unlisted?: boolean | undefined
-  readonly examples?: ReadonlyArray<Command.Example> | undefined
+  readonly resolveExamples?: ((commandPath: ReadonlyArray<string>) => ReadonlyArray<Command.Example>) | undefined
   readonly subcommands?: ReadonlyArray<SubcommandGroup> | undefined
   readonly parse?: ((input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>) | undefined
   readonly parseContext?:
@@ -115,6 +116,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   const annotations = options.annotations ?? Context.empty()
   const globalFlags = options.globalFlags ?? []
   const subcommands = options.subcommands ?? []
+  const resolveExamples = options.resolveExamples ?? noExamples
 
   const handle = (
     input: Input,
@@ -188,7 +190,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
       })
     }
 
-    const examples: ReadonlyArray<ExampleDoc> = options.examples ?? []
+    const examples: ReadonlyArray<ExampleDoc> = resolveExamples(commandPath)
 
     return {
       description: options.description ?? "",
@@ -204,7 +206,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   return Object.assign(Object.create(Proto), {
     [TypeId]: TypeId,
     name: options.name,
-    examples: options.examples ?? [],
+    examples: resolveExamples([options.name]),
+    resolveExamples,
     annotations,
     globalFlags,
     subcommands,
@@ -232,6 +235,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 /* Helpers                                                                    */
 /* ========================================================================== */
 
+const noExamples = (): ReadonlyArray<Command.Example> => []
+
 /**
  * Converts a single flag param into a FlagDoc for help display.
  *