requestflag

package
v1.52.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 11, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const InputModeEnv = "OPENAI_CLI_INPUT_MODE"

Variables

This section is empty.

Functions

func AddStructuredFlags added in v1.52.0 

func AddStructuredFlags(root *cli.Command)

AddStructuredFlags adds companions only for schema-declared text unions. Shared aliases receive the same companion object and one help annotation.

func ApplyStdinDataToFlags 

func ApplyStdinDataToFlags(cmd *cli.Command, data map[string]any) error

ApplyStdinDataToFlags sets flag values from a parsed stdin data map for flags that have not already been set via the command line. This allows piped YAML/JSON data to satisfy path, query, and header parameters. Body parameters are excluded because they are merged separately. Request locations and inner flags are matched by their canonical names or configured data aliases.

func ApplyStdinDataToFlagsWithProvenance added in v1.9.0 

func ApplyStdinDataToFlagsWithProvenance(cmd *cli.Command, data map[string]any, onSet func(cli.Flag)) error

ApplyStdinDataToFlagsWithProvenance reports every flag populated from stdin. Inner flags are reported directly so callers can distinguish an untrusted nested field from other, explicitly supplied fields on its outer flag.

func CheckInnerFlags 

func CheckInnerFlags(cmd cli.Command) error

Helper function to verify that all inner flags have an outer flag set and follow the --foo.baz prefix format

func ConfigureInputMode added in v1.52.0 

func ConfigureInputMode(root *cli.Command, mode string) error

ConfigureInputMode captures one process's policy before argument parsing. It never changes the environment or shares mutable process-global state.

func ConfigureUnannotatedCommands added in v1.52.0 

func ConfigureUnannotatedCommands(root *cli.Command, textUnionFields map[string][]string)

ConfigureUnannotatedCommands supports older generated command snapshots. Call it on canonical resources before adding handwritten commands or aliases. If the producer supplied any policies, it owns the entire snapshot and ConfigureInputMode will diagnose omissions instead of filling them in.

func GetMissingRequiredFlags 

func GetMissingRequiredFlags(cmd *cli.Command, body any) []cli.Flag

func ProtectPipedInnerValue added in v1.52.0 

func ProtectPipedInnerValue(inner HasOuterFlag, protect func(any) any)

ProtectPipedInnerValue marks only the field that just came from stdin, so explicit siblings retain their own source handling.

func Ptr 

func Ptr[T any](v T) *T

Ptr returns a pointer to its argument. It is used to initialize `Default` on pointer-typed Flag values, since Go does not allow taking the address of a composite literal's element or of an untyped constant.

func UnmarshalRequestObject added in v1.48.0 

func UnmarshalRequestObject(data []byte) (map[string]any, error)

UnmarshalRequestObject requires exactly one object for an explicit request file. Parser errors can quote private data from the input document.

func UnmarshalYAMLOrJSON added in v1.16.0 

func UnmarshalYAMLOrJSON(data []byte, v any) error

UnmarshalYAMLOrJSON decodes YAML or JSON input into v.

JSON is valid YAML, but go-yaml only decodes a number as a float when it has a decimal point. A JSON number with an exponent and no fraction would otherwise decode as a string (https://github.com/goccy/go-yaml/issues/916). Python, JavaScript, and Go all emit that form for small floats, such as 1e-05 or 1e-7.

func WithInnerFlags 

func WithInnerFlags(cmd cli.Command, innerFlagMap map[string][]HasOuterFlag) cli.Command

WithInnerFlags takes a command and a map of flag names to inner flags, and returns a modified command with the appropriate inner flags set.

Types

type DateTimeValue 

type DateTimeValue string

func (*DateTimeValue) Parse 

func (d *DateTimeValue) Parse(s string) error

func (DateTimeValue) String 

func (d DateTimeValue) String() string

type DateValue 

type DateValue string

Time-related value types

func (*DateValue) Parse 

func (d *DateValue) Parse(s string) error

Parse methods for time-related types

func (DateValue) String 

func (d DateValue) String() string

String methods for time-related types

type Flag 

type Flag[
	T []any | []map[string]any | []DateTimeValue | []DateValue | []TimeValue | []string |
		[]float64 | []int64 | []bool | any | map[string]any | DateTimeValue | DateValue | TimeValue |
		string | float64 | int64 | bool |
		*string | *float64 | *int64 | *bool | *DateTimeValue | *DateValue | *TimeValue,
] struct {
	InputPolicy InputPolicy          // schema policy for one flag operand
	Name        string               // name of the flag
	Category    string               // category of the flag, if any
	DefaultText string               // default text of the flag for usage purposes
	HideDefault bool                 // whether to hide the default value in output
	Usage       string               // usage string for help output
	Sources     cli.ValueSourceChain // sources to load flag value from
	Required    bool                 // whether the flag is required or not
	Hidden      bool                 // whether to hide the flag in help output
	Default     T                    // default value for this flag if not set by from any source
	Aliases     []string             // aliases that are allowed for this flag
	Validator   func(T) error        // custom function to validate this flag value

	QueryPath  string // location in the request query string to put this flag's value
	HeaderPath string // location in the request header to put this flag's value
	BodyPath   string // location in the request body to put this flag's value
	BodyRoot   bool   // if true, then use this value as the entire request body
	PathParam  string // name of the URL path parameter this flag's value maps to

	// Const, when true, marks this flag as a constant. The flag's Default value is used as the fixed value
	// and always included in the request (IsSet returns true). The user can still see and override the flag,
	// but isn't required to provide it. This is used for single-value enums and `x-stainless-const`
	// parameters.
	Const bool

	// FileInput, when true, indicates that the flag value is always treated as a file path. The file is read
	// automatically without requiring the "@" prefix. This is used for parameters with `type: string, format:
	// binary` in the OpenAPI spec.
	FileInput bool

	// DataAliases is a list of alternate names for this parameter recognized when parsing piped YAML/JSON
	// input. Values keyed by any alias are translated to the canonical API name before being sent.
	DataAliases []string
	// contains filtered or unexported fields
}

Flag [T] is a generic flag base which can be used to implement the most common interfaces used by urfave/cli. Additionally, it allows specifying where in an HTTP request the flag values should be placed (e.g. query, body, etc.).

Pointer-to-primitive type parameters (e.g. *string) are used for flags whose underlying schema is nullable. They give flags a tri-state: unset (excluded from the request), set to the literal "null" (nil pointer → JSON null), or set to a value (*v → JSON value).

func (*Flag[T]) Count 

func (f *Flag[T]) Count() int

func (*Flag[T]) Get 

func (f *Flag[T]) Get() any

func (Flag[T]) GetBodyPath 

func (f Flag[T]) GetBodyPath() string

func (*Flag[T]) GetCategory 

func (f *Flag[T]) GetCategory() string

func (Flag[T]) GetDataAliases 

func (f Flag[T]) GetDataAliases() []string

func (*Flag[T]) GetDefaultText 

func (f *Flag[T]) GetDefaultText() string

func (*Flag[T]) GetEnvVars 

func (f *Flag[T]) GetEnvVars() []string

GetEnvVars returns the env vars for this flag

func (Flag[T]) GetHeaderPath 

func (f Flag[T]) GetHeaderPath() string

func (Flag[T]) GetPathParam 

func (f Flag[T]) GetPathParam() string

func (Flag[T]) GetQueryPath 

func (f Flag[T]) GetQueryPath() string

func (*Flag[T]) GetUsage 

func (f *Flag[T]) GetUsage() string

func (*Flag[T]) GetValue 

func (f *Flag[T]) GetValue() string

func (Flag[T]) IsBodyRoot 

func (f Flag[T]) IsBodyRoot() bool

func (*Flag[T]) IsBoolFlag 

func (f *Flag[T]) IsBoolFlag() bool

func (*Flag[T]) IsDefaultVisible 

func (f *Flag[T]) IsDefaultVisible() bool

func (Flag[T]) IsFileInput 

func (f Flag[T]) IsFileInput() bool

func (Flag[T]) IsLocal 

func (f Flag[T]) IsLocal() bool

func (*Flag[T]) IsMultiValueFlag 

func (f *Flag[T]) IsMultiValueFlag() bool

func (*Flag[T]) IsRequired 

func (f *Flag[T]) IsRequired() bool

func (*Flag[T]) IsRequiredAsFlagOrStdin 

func (f *Flag[T]) IsRequiredAsFlagOrStdin() bool

func (*Flag[T]) IsSet 

func (f *Flag[T]) IsSet() bool

func (*Flag[T]) IsVisible 

func (f *Flag[T]) IsVisible() bool

func (*Flag[T]) Names 

func (f *Flag[T]) Names() []string

func (*Flag[T]) PostParse 

func (f *Flag[T]) PostParse() error

func (*Flag[T]) PreParse 

func (f *Flag[T]) PreParse() error

func (*Flag[T]) SeedInnerCollection 

func (f *Flag[T]) SeedInnerCollection(isArrayOfObjects bool)

SeedInnerCollection initializes a Flag[any]'s underlying value as an empty map[string]any or []map[string]any so subsequent SetInnerField calls have a dispatchable reflect.Kind. For typed Flag[T] this is a no-op: the type assertion fails and the existing reflect.Kind on the typed-nil zero value already routes correctly.

func (*Flag[T]) Set 

func (f *Flag[T]) Set(name string, val string) error

func (*Flag[T]) SetCategory 

func (f *Flag[T]) SetCategory(c string)

func (*Flag[T]) SetInnerField 

func (f *Flag[T]) SetInnerField(field string, val any)

func (*Flag[T]) String 

func (f *Flag[T]) String() string

func (*Flag[T]) TakesValue 

func (f *Flag[T]) TakesValue() bool

func (*Flag[T]) TypeName 

func (f *Flag[T]) TypeName() string

type HasOuterFlag 

type HasOuterFlag interface {
	cli.Flag
	SetOuterFlag(cli.Flag)
	GetOuterFlag() cli.Flag
	GetInnerField() string
	GetDataAliases() []string
}

type InRequest 

type InRequest interface {
	GetQueryPath() string
	GetHeaderPath() string
	GetBodyPath() string
	GetPathParam() string
	IsBodyRoot() bool
	IsFileInput() bool
	GetDataAliases() []string
}

InRequest interface for flags that should be included in HTTP requests

type InnerFieldSeeder 

type InnerFieldSeeder interface {
	SeedInnerCollection(isArrayOfObjects bool)
}

InnerFieldSeeder lets an InnerFlag prepare its outer flag's underlying value before dispatching SetInnerField. This is only meaningful for Flag[any] — the codegen output for nullable complex schemas — whose untyped-nil zero value would otherwise have no reflect.Kind for the inner-field switch to dispatch on.

type InnerFlag 

type InnerFlag[
	T []any | []map[string]any | []DateTimeValue | []DateValue | []TimeValue | []string |
		[]float64 | []int64 | []bool | any | map[string]any | DateTimeValue | DateValue | TimeValue |
		string | float64 | int64 | bool |
		*string | *float64 | *int64 | *bool | *DateTimeValue | *DateValue | *TimeValue,
] struct {
	InputPolicy InputPolicy   // schema policy for one flag operand
	Name        string        // name of the flag
	DefaultText string        // default text of the flag for usage purposes
	Usage       string        // usage string for help output
	Aliases     []string      // aliases that are allowed for this flag
	Validator   func(T) error // custom function to validate this flag value

	OuterFlag   cli.Flag // The flag on which this inner flag will set values
	InnerField  string   // The inner field which this flag will set
	DataAliases []string // alternate names recognized in YAML values passed as the outer flag

	// OuterIsArrayOfObjects tells an untyped outer flag (Flag[any], used for nullable
	// complex schemas) to seed its underlying value as []map[string]any rather than
	// map[string]any before SetInnerField runs. The hint is ignored for typed outer
	// flags whose zero value already carries a dispatchable reflect.Kind.
	OuterIsArrayOfObjects bool
	// contains filtered or unexported fields
}

InnerFlag[T] represents a CLI flag for the urfave/cli package that allows setting nested fields within other flags. For example, using `--foo.baz` will set the "baz" field on a parent flag named `--foo`.

func (*InnerFlag[T]) Get 

func (f *InnerFlag[T]) Get() any

func (*InnerFlag[T]) GetDataAliases 

func (f *InnerFlag[T]) GetDataAliases() []string

GetDataAliases returns the aliases recognized when parsing inner field keys from piped or flag YAML.

func (*InnerFlag[T]) GetDefaultText 

func (f *InnerFlag[T]) GetDefaultText() string

func (*InnerFlag[T]) GetEnvVars 

func (f *InnerFlag[T]) GetEnvVars() []string

func (*InnerFlag[T]) GetInnerField 

func (f *InnerFlag[T]) GetInnerField() string

GetInnerField returns the API field name that this inner flag sets on its outer flag's value. For example, the flag --parent.foo targeting a parameter whose OpenAPI property name is "foo" would return "foo". This is distinct from the flag's CLI name and from any DataAliases entries.

func (*InnerFlag[T]) GetOuterFlag 

func (f *InnerFlag[T]) GetOuterFlag() cli.Flag

func (*InnerFlag[T]) GetUsage 

func (f *InnerFlag[T]) GetUsage() string

func (*InnerFlag[T]) GetValue 

func (f *InnerFlag[T]) GetValue() string

func (*InnerFlag[T]) IsBoolFlag 

func (f *InnerFlag[T]) IsBoolFlag() bool

func (*InnerFlag[T]) IsDefaultVisible 

func (f *InnerFlag[T]) IsDefaultVisible() bool

func (*InnerFlag[T]) IsMultiValueFlag 

func (f *InnerFlag[T]) IsMultiValueFlag() bool

func (*InnerFlag[T]) IsSet 

func (f *InnerFlag[T]) IsSet() bool

func (*InnerFlag[T]) Names 

func (f *InnerFlag[T]) Names() []string

func (*InnerFlag[T]) PostParse 

func (f *InnerFlag[T]) PostParse() error

func (*InnerFlag[T]) PreParse 

func (f *InnerFlag[T]) PreParse() error

func (*InnerFlag[T]) Set 

func (f *InnerFlag[T]) Set(name string, rawVal string) error

func (*InnerFlag[T]) SetOuterFlag 

func (f *InnerFlag[T]) SetOuterFlag(flag cli.Flag)

func (*InnerFlag[T]) String 

func (f *InnerFlag[T]) String() string

func (*InnerFlag[T]) TakesValue 

func (f *InnerFlag[T]) TakesValue() bool

func (*InnerFlag[T]) TypeName 

func (f *InnerFlag[T]) TypeName() string

type InputPolicy added in v1.52.0 

type InputPolicy uint8

InputPolicy describes the schema of the value consumed by one flag occurrence. Generated declarations supply it; Go's any type cannot establish this policy. 

const (
	InputPolicyUnknown InputPolicy = iota
	InputPolicyTyped
	InputPolicyText
	InputPolicyTextStructured
)

type InputPolicyError added in v1.52.0 

type InputPolicyError struct {
	// contains filtered or unexported fields
}

InputPolicyError contains only policy names and declared flag names.

func (*InputPolicyError) Error added in v1.52.0 

func (e *InputPolicyError) Error() string

type InputValue added in v1.52.0 

type InputValue struct {
	// contains filtered or unexported fields
}

InputValue holds a flag's validated value and any occurrences that still need a file or stdin. Replaced scalar operands never enter the pending sequence.

func (InputValue) CountSources added in v1.52.0 

func (input InputValue) CountSources(count func(value any, expandSources bool) int) int

CountSources visits the effective values without decoding or reading any source. Only explicitly supplied sources and ordinary nested flags can consume stdin; decoded containers can still contain such nested flags.

func (InputValue) Option added in v1.52.0 

func (input InputValue) Option() string

Option names the flag responsible for a source error.

func (InputValue) ProtectStdin added in v1.52.0 

func (input InputValue) ProtectStdin(protect func(any) any) InputValue

ProtectStdin marks the materialized tree, including nested flag values, with the request's stdin provenance. Deferred sources came from explicit CLI flags.

func (InputValue) Resolve added in v1.52.0 

func (input InputValue) Resolve(readText func(string) (string, error), prepare func(any, bool) (any, error)) (any, error)

Resolve evaluates effective operands in command-line order. readText expands explicit structured sources as text. prepare walks values to resolve nested flags; strings in decoded data stay protected. A nil prepare leaves values as parsed. readText is required only when a source is present.

type RequestContents 

type RequestContents struct {
	Queries map[string]any
	Headers map[string]any
	Body    any
}

The values that will be sent in different parts of a request.

func ExtractRequestContents 

func ExtractRequestContents(cmd *cli.Command) RequestContents

type RequiredFlagOrStdin 

type RequiredFlagOrStdin interface {
	IsRequiredAsFlagOrStdin() bool
}

type SettableInnerField 

type SettableInnerField interface {
	SetInnerField(string, any)
}

Allow setting inner fields on other flags (e.g. --foo.baz can set the "baz" field on the --foo flag)

type StdinValueError added in v1.39.0 

type StdinValueError struct {
	// contains filtered or unexported fields
}

StdinValueError identifies the declaration that rejected piped input. Error and Unwrap preserve the existing diagnostic and its original causes.

func (*StdinValueError) Error added in v1.39.0 

func (e *StdinValueError) Error() string

func (*StdinValueError) FlagName added in v1.39.0 

func (e *StdinValueError) FlagName() string

func (*StdinValueError) Unwrap added in v1.39.0 

func (e *StdinValueError) Unwrap() error

type StructuredInputError added in v1.52.0 

type StructuredInputError struct {
	// contains filtered or unexported fields
}

StructuredInputError omits rejected values and source contents.

func (*StructuredInputError) Error added in v1.52.0 

func (e *StructuredInputError) Error() string

type TimeValue 

type TimeValue string

func (*TimeValue) Parse 

func (t *TimeValue) Parse(s string) error

func (TimeValue) String 

func (t TimeValue) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.