Class: Pindo::Options::OptionItem

Inherits:
Object
  • Object
show all
Defined in:
lib/pindo/options/core/option_item.rb

Overview

OptionItem 类定义单个参数的所有属性和行为（简化版）

Constant Summary collapse

Boolean =

Boolean 类型标记

:boolean

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key:, **options) ⇒ OptionItem

初始化方法

Parameters:

  • key (Symbol) —

    参数键名（必填）

  • options (Hash) —

    其他配置选项

Raises:

  • (ArgumentError) 


26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/pindo/options/core/option_item.rb', line 26

def initialize(key:, **options)
  raise ArgumentError, "key must be a Symbol" unless key.is_a?(Symbol)

  @key = key
  @name = options[:name]  # 显示名称，如果未设置则使用 key
  @description = options[:description] || options[:desc] || ""
  @type = options[:type] || String
  @env_name = options[:env_name]
  @aliases = options[:aliases] || []
  @default_value = options[:default_value] || options[:default]
  @optional = options.fetch(:optional, true)
  @cacheable = options.fetch(:cacheable, false)  # 默认不存入缓存
  @verify_block = options[:verify_block]
  @value_block = options[:value_block]
  @example = options[:example]

  validate_type!
end

Instance Attribute Details

#aliases ⇒ Object

Array<Symbol>: 参数别名



12
13
14
 
# File 'lib/pindo/options/core/option_item.rb', line 12

def aliases
  @aliases
end

#cacheable ⇒ Object

Boolean: 是否存入缓存（默认为 true）



15
16
17
 
# File 'lib/pindo/options/core/option_item.rb', line 15

def cacheable
  @cacheable
end

#default_value ⇒ Object

Any: 默认值



13
14
15
 
# File 'lib/pindo/options/core/option_item.rb', line 13

def default_value
  @default_value
end

#description ⇒ Object

String: 参数描述



9
10
11
 
# File 'lib/pindo/options/core/option_item.rb', line 9

def description
  @description
end

#env_name ⇒ Object

String: 环境变量名



11
12
13
 
# File 'lib/pindo/options/core/option_item.rb', line 11

def env_name
  @env_name
end

#example ⇒ Object

String: 使用示例



18
19
20
 
# File 'lib/pindo/options/core/option_item.rb', line 18

def example
  @example
end

#key ⇒ Object

核心属性



7
8
9
 
# File 'lib/pindo/options/core/option_item.rb', line 7

def key
  @key
end

#name ⇒ Object

String: 显示名称（用于缓存确认等场景）



8
9
10
 
# File 'lib/pindo/options/core/option_item.rb', line 8

def name
  @name
end

#optional ⇒ Object

Boolean: 是否可选（默认为 true）



14
15
16
 
# File 'lib/pindo/options/core/option_item.rb', line 14

def optional
  @optional
end

#type ⇒ Object

Class: 数据类型 (String/Integer/Boolean)



10
11
12
 
# File 'lib/pindo/options/core/option_item.rb', line 10

def type
  @type
end

#value_block ⇒ Object

Proc: 获取参数值的 block（交互式输入）



17
18
19
 
# File 'lib/pindo/options/core/option_item.rb', line 17

def value_block
  @value_block
end

#verify_block ⇒ Object

Proc: 自定义验证逻辑



16
17
18
 
# File 'lib/pindo/options/core/option_item.rb', line 16

def verify_block
  @verify_block
end

Instance Method Details

#auto_convert_value(value) ⇒ Any

自动类型转换

Parameters:

  • value (Any) —

    原始值

Returns:

  • (Any) —

    转换后的值



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/pindo/options/core/option_item.rb', line 71

def auto_convert_value(value)
  return nil if value.nil?

  case @type
  when Boolean, :boolean
    # Boolean 转换
    if value.is_a?(String)
      return true if value.downcase == 'true' || value == '1'
      return false if value.downcase == 'false' || value == '0'
    end
    !!value
  when Integer
    value.to_i
  else
    # String 或其他类型
    value.to_s
  end
rescue StandardError => e
  raise ArgumentError, "参数 '#{@key}' 类型转换失败: #{e.message}"
end

#boolean? ⇒ Boolean

判断是否是 Boolean 类型

Returns:



51
52
53
 
# File 'lib/pindo/options/core/option_item.rb', line 51

def boolean?
  @type == Boolean || @type == :boolean
end

#cacheable? ⇒ Boolean

判断是否需要存入缓存

Returns:



56
57
58
 
# File 'lib/pindo/options/core/option_item.rb', line 56

def cacheable?
  @cacheable
end

#display_name ⇒ Object

获取显示名称（优先使用 name，否则使用 key）



46
47
48
 
# File 'lib/pindo/options/core/option_item.rb', line 46

def display_name
  @name || @key.to_s
end

#fetch_env_value ⇒ String?

从环境变量读取值

Returns:

  • (String, nil) —

    环境变量的值



62
63
64
65
66
 
# File 'lib/pindo/options/core/option_item.rb', line 62

def fetch_env_value
  return nil unless @env_name
  value = ENV[@env_name]
  value if value && !value.empty?
end

#to_claide_option ⇒ Array

转换为 CLAide 选项格式（用于 –help 输出）

Returns:

  • (Array) —

    CLAide 选项格式 [option_string, description]



108
109
110
111
112
113
 
# File 'lib/pindo/options/core/option_item.rb', line 108

def to_claide_option
  option_string = build_option_string
  description_text = build_description_text

  [option_string, description_text]
end

#valid?(value) ⇒ Boolean

验证参数值

Parameters:

  • value (Any) —

    要验证的值

Returns:



95
96
97
98
99
100
101
102
103
104
 
# File 'lib/pindo/options/core/option_item.rb', line 95

def valid?(value)
  return true unless @verify_block

  begin
    @verify_block.call(value)
    true
  rescue StandardError => e
    raise ArgumentError, "参数 '#{@key}' 验证失败: #{e.message}"
  end
end

#with(**overrides) ⇒ OptionItem

复制当前 OptionItem 并覆盖指定属性

Examples:

UnityOptions.select(:skipconfig).first.with(default_value: true)

Parameters:

  • overrides (Hash) —

    要覆盖的属性

Returns:



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/pindo/options/core/option_item.rb', line 120

def with(**overrides)
  OptionItem.new(
    key: overrides[:key] || @key,
    name: overrides[:name] || @name,
    description: overrides[:description] || @description,
    type: overrides[:type] || @type,
    env_name: overrides[:env_name] || @env_name,
    aliases: overrides[:aliases] || @aliases,
    default_value: overrides.key?(:default_value) ? overrides[:default_value] : @default_value,
    optional: overrides.key?(:optional) ? overrides[:optional] : @optional,
    cacheable: overrides.key?(:cacheable) ? overrides[:cacheable] : @cacheable,
    verify_block: overrides[:verify_block] || @verify_block,
    value_block: overrides[:value_block] || @value_block,
    example: overrides[:example] || @example
  )
end