.opencode/node_modules/effect/dist/unstable/cli/Primitive.d.ts

import * as Effect from "../../Effect.ts";
import * as FileSystem from "../../FileSystem.ts";
import * as Path from "../../Path.ts";
import * as Redacted from "../../Redacted.ts";
import * as Schema from "../../Schema.ts";
import type { Formatter } from "../../SchemaIssue.ts";
import type * as Struct from "../../Struct.ts";
import type { Covariant } from "../../Types.ts";
declare const TypeId = "~effect/cli/Primitive";
/**
 * Represents a primitive type that can parse string input into a typed value.
 *
 * **Example** (Parsing values with primitives)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * // Using built-in primitives
 * const parseString = Effect.gen(function*() {
 *   const stringResult = yield* Primitive.string.parse("hello")
 *   const numberResult = yield* Primitive.integer.parse("42")
 *   const boolResult = yield* Primitive.boolean.parse("true")
 *
 *   return { stringResult, numberResult, boolResult }
 * })
 *
 * // All primitives provide parsing functionality
 * const parseDate = Effect.gen(function*() {
 *   const dateResult = yield* Primitive.date.parse("2023-12-25")
 *   const pathResult = yield* Primitive.path("file", true).parse("./package.json")
 *   return { dateResult, pathResult }
 * })
 * ```
 *
 * @category models
 * @since 4.0.0
 */
export interface Primitive<out A> extends Primitive.Variance<A> {
    readonly _tag: string;
    readonly parse: (value: string) => Effect.Effect<A, string, FileSystem.FileSystem | Path.Path>;
}
/**
 * Namespace containing type-level helpers for `Primitive`.
 *
 * @since 4.0.0
 */
export declare namespace Primitive {
    /**
     * Type-level variance marker for the value parsed by a `Primitive`.
     *
     * @category models
     * @since 4.0.0
     */
    interface Variance<out A> {
        readonly [TypeId]: {
            readonly _A: Covariant<A>;
        };
    }
}
/**
 * Creates a primitive that parses boolean values from string input.
 *
 * **Details**
 *
 * Recognizes various forms of true/false values:
 * - True values: "true", "1", "y", "yes", "on"
 * - False values: "false", "0", "n", "no", "off"
 *
 * **Example** (Parsing boolean values)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const parseBoolean = Effect.gen(function*() {
 *   const result1 = yield* Primitive.boolean.parse("true")
 *   console.log(result1) // true
 *
 *   const result2 = yield* Primitive.boolean.parse("yes")
 *   console.log(result2) // true
 *
 *   const result3 = yield* Primitive.boolean.parse("false")
 *   console.log(result3) // false
 *
 *   const result4 = yield* Primitive.boolean.parse("0")
 *   console.log(result4) // false
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const boolean: Primitive<boolean>;
/**
 * Creates a primitive that parses floating-point numbers from string input.
 *
 * **Example** (Parsing floating-point numbers)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const parseFloat = Effect.gen(function*() {
 *   const result1 = yield* Primitive.float.parse("3.14")
 *   console.log(result1) // 3.14
 *
 *   const result2 = yield* Primitive.float.parse("-42.5")
 *   console.log(result2) // -42.5
 *
 *   const result3 = yield* Primitive.float.parse("0")
 *   console.log(result3) // 0
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const float: Primitive<number>;
/**
 * Creates a primitive that parses integer numbers from string input.
 *
 * **Example** (Parsing integer values)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const parseInteger = Effect.gen(function*() {
 *   const result1 = yield* Primitive.integer.parse("42")
 *   console.log(result1) // 42
 *
 *   const result2 = yield* Primitive.integer.parse("-123")
 *   console.log(result2) // -123
 *
 *   const result3 = yield* Primitive.integer.parse("0")
 *   console.log(result3) // 0
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const integer: Primitive<number>;
/**
 * Creates a primitive that parses Date objects from string input.
 *
 * **Example** (Parsing date values)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const parseDate = Effect.gen(function*() {
 *   const result1 = yield* Primitive.date.parse("2023-12-25")
 *   console.log(result1) // Date object for December 25, 2023
 *
 *   const result2 = yield* Primitive.date.parse("2023-12-25T10:30:00Z")
 *   console.log(result2) // Date object with time
 *
 *   const result3 = yield* Primitive.date.parse("Dec 25, 2023")
 *   console.log(result3) // Date object parsed from natural format
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const date: Primitive<Date>;
/**
 * Creates a primitive that accepts any string value without validation.
 *
 * **Example** (Parsing string values)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const parseString = Effect.gen(function*() {
 *   const result1 = yield* Primitive.string.parse("hello world")
 *   console.log(result1) // "hello world"
 *
 *   const result2 = yield* Primitive.string.parse("")
 *   console.log(result2) // ""
 *
 *   const result3 = yield* Primitive.string.parse("123")
 *   console.log(result3) // "123"
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const string: Primitive<string>;
/**
 * Creates a primitive that accepts only specific choice values mapped to custom types.
 *
 * **Example** (Parsing choices)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * type LogLevel = "debug" | "info" | "warn" | "error"
 *
 * const logLevelPrimitive = Primitive.choice<LogLevel>([
 *   ["debug", "debug"],
 *   ["info", "info"],
 *   ["warn", "warn"],
 *   ["error", "error"]
 * ])
 *
 * const parseLogLevel = Effect.gen(function*() {
 *   const result1 = yield* logLevelPrimitive.parse("info")
 *   console.log(result1) // "info"
 *
 *   const result2 = yield* logLevelPrimitive.parse("debug")
 *   console.log(result2) // "debug"
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const choice: <A>(choices: ReadonlyArray<readonly [string, A]>) => Primitive<A>;
/**
 * Specifies the type of path validation to perform.
 *
 * **Example** (Choosing path validation)
 *
 * ```ts
 * import { Primitive } from "effect/unstable/cli"
 *
 * // Only accept files
 * const filePath = Primitive.path("file", true)
 *
 * // Only accept directories
 * const dirPath = Primitive.path("directory", true)
 *
 * // Accept either files or directories
 * const anyPath = Primitive.path("either", false)
 * ```
 *
 * @category models
 * @since 4.0.0
 */
export type PathType = "file" | "directory" | "either";
/**
 * Creates a primitive that validates and resolves file system paths.
 *
 * **Example** (Parsing file system paths)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const program = Effect.gen(function*() {
 *   // Parse a file path that must exist
 *   const filePrimitive = Primitive.path("file", true)
 *   const filePath = yield* filePrimitive.parse("./package.json")
 *   console.log(filePath) // Absolute path to package.json
 *
 *   // Parse a directory path
 *   const dirPrimitive = Primitive.path("directory", false)
 *   const dirPath = yield* dirPrimitive.parse("./src")
 *   console.log(dirPath) // Absolute path to src directory
 *
 *   // Parse any path type
 *   const anyPrimitive = Primitive.path("either", false)
 *   const anyPath = yield* anyPrimitive.parse("./some/path")
 *   console.log(anyPath) // Absolute path
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const path: (pathType: PathType, mustExist?: boolean) => Primitive<string>;
/**
 * Creates a primitive that wraps string input in `Redacted`.
 *
 * **Details**
 *
 * The wrapped value is hidden when formatted or inspected, while the original
 * string remains available through the `Redacted` API when explicitly needed.
 *
 * **Example** (Parsing redacted values)
 *
 * ```ts
 * import { Effect, Redacted } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const parseRedacted = Effect.gen(function*() {
 *   const result = yield* Primitive.redacted.parse("secret-password")
 *   console.log(Redacted.value(result)) // "secret-password"
 *   console.log(String(result)) // "<redacted>"
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const redacted: Primitive<Redacted.Redacted<string>>;
/**
 * Creates a primitive that reads and returns the contents of a file as a string.
 *
 * **Example** (Reading file text)
 *
 * ```ts
 * import { Effect, Schema } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const ConfigSchema = Schema.Struct({
 *   name: Schema.String,
 *   version: Schema.String,
 *   port: Schema.Number
 * })
 * const decodeConfig = Schema.decodeUnknownEffect(
 *   Schema.fromJsonString(ConfigSchema)
 * )
 *
 * const readConfigFile = Effect.gen(function*() {
 *   const content = yield* Primitive.fileText.parse("./config.json")
 *   console.log(content) // {"name":"my-app","version":"1.0.0","port":3000}
 *
 *   const config = yield* decodeConfig(content)
 *   console.log(config) // { name: "my-app", version: "1.0.0", port: 3000 }
 *   return config
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const fileText: Primitive<string>;
/**
 * Represents options which can be provided to methods that deal with parsing
 * file content.
 *
 * @category options
 * @since 4.0.0
 */
export type FileParseOptions = {
    readonly format?: "ini" | "json" | "toml" | "yaml";
};
/**
 * Creates a primitive that reads a file and parses its content as structured
 * data.
 *
 * **Details**
 *
 * The parser is selected from `options.format` when provided, otherwise from
 * the file extension. Supported formats include INI, JSON, TOML, YAML, and YML.
 *
 * **Example** (Parsing file content)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const tomlFilePrimitive = Primitive.fileParse({ format: "toml" })
 *
 * const loadConfig = Effect.gen(function*() {
 *   const config = yield* tomlFilePrimitive.parse("./config.toml")
 *   console.log(config) // { name: "my-app", version: "1.0.0", port: 3000 }
 *   return config
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const fileParse: (options?: FileParseOptions) => Primitive<unknown>;
/**
 * Represents options which can be provided to methods that deal with parsing
 * file content and decoding the file content with a `Schema`.
 *
 * @category options
 * @since 4.0.0
 */
export type FileSchemaOptions = Struct.Simplify<FileParseOptions & {
    readonly errorFormatter?: Formatter<string> | undefined;
}>;
/**
 * Reads and parses file content using the specified schema.
 *
 * **Example** (Parsing file content with a schema)
 *
 * ```ts
 * import { Effect, Schema } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const ConfigSchema = Schema.Struct({
 *   name: Schema.String,
 *   version: Schema.String,
 *   port: Schema.Number
 * })
 *
 * const jsonConfigPrimitive = Primitive.fileSchema(ConfigSchema, {
 *   format: "json"
 * })
 *
 * const loadConfig = Effect.gen(function*() {
 *   const config = yield* jsonConfigPrimitive.parse("./config.json")
 *   console.log(config) // { name: "my-app", version: "1.0.0", port: 3000 }
 *   return config
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const fileSchema: <A>(schema: Schema.Decoder<A>, options?: FileSchemaOptions | undefined) => Primitive<A>;
/**
 * Parses a single `key=value` pair into a record object.
 *
 * **Example** (Parsing key-value pairs)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const parseKeyValue = Effect.gen(function*() {
 *   const result1 = yield* Primitive.keyValuePair.parse("name=john")
 *   console.log(result1) // { name: "john" }
 *
 *   const result2 = yield* Primitive.keyValuePair.parse("port=3000")
 *   console.log(result2) // { port: "3000" }
 *
 *   const result3 = yield* Primitive.keyValuePair.parse("debug=true")
 *   console.log(result3) // { debug: "true" }
 * })
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const keyValuePair: Primitive<Record<string, string>>;
/**
 * Creates a sentinel primitive that always fails to parse a value.
 *
 * **When to use**
 *
 * Use when you need a CLI primitive for flags that do not accept values.
 *
 * **Example** (Rejecting option values)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { Primitive } from "effect/unstable/cli"
 *
 * const program = Effect.gen(function*() {
 *   // This will always fail - useful for boolean flags
 *   return yield* Primitive.none.parse("any-value")
 * })
 *
 * // The above effect will fail with "This option does not accept values"
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const none: Primitive<never>;
/**
 * Gets a human-readable type name for a primitive.
 *
 * **When to use**
 *
 * Use when you need the display type name for a `Primitive`, such as when
 * generating CLI help documentation.
 *
 * **Example** (Getting primitive type names)
 *
 * ```ts
 * import { Primitive } from "effect/unstable/cli"
 *
 * console.log(Primitive.getTypeName(Primitive.string)) // "string"
 * console.log(Primitive.getTypeName(Primitive.integer)) // "integer"
 * console.log(Primitive.getTypeName(Primitive.boolean)) // "boolean"
 * console.log(Primitive.getTypeName(Primitive.date)) // "date"
 * console.log(Primitive.getTypeName(Primitive.keyValuePair)) // "key=value"
 *
 * const logLevelChoice = Primitive.choice([
 *   ["debug", "debug"],
 *   ["info", "info"]
 * ])
 * console.log(Primitive.getTypeName(logLevelChoice)) // "choice"
 * ```
 *
 * @category getters
 * @since 4.0.0
 */
export declare const getTypeName: <A>(primitive: Primitive<A>) => string;
export {};
//# sourceMappingURL=Primitive.d.ts.map