Class: FastlaneCore::ConfigItem

Inherits:
Object
  • Object
show all
Defined in:
fastlane_core/lib/fastlane_core/configuration/config_item.rb

Direct Known Subclasses

Precheck::Rule

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key: nil, env_name: nil, description: nil, short_option: nil, default_value: nil, default_value_dynamic: false, verify_block: nil, is_string: true, type: nil, skip_type_validation: false, optional: nil, conflicting_options: nil, conflict_block: nil, deprecated: nil, sensitive: nil, code_gen_sensitive: false, code_gen_default_value: nil, display_in_shell: true) ⇒ ConfigItem

Creates a new option rubocop:disable Metrics/ParameterLists

Parameters:

  • key (Symbol) (defaults to: nil) —

    the key which is used as command parameters or key in the fastlane tools

  • env_name (String) (defaults to: nil) —

    the name of the environment variable, which is only used if no other values were found

  • description (String) (defaults to: nil) —

    A description shown to the user

  • short_option (String) (defaults to: nil) —

    A string of length 1 which is used for the command parameters (e.g. -f)

  • default_value (defaults to: nil) —

    the value which is used if there was no given values and no environment values

  • default_value_dynamic (Boolean) (defaults to: false) —

    Set if the default value is generated dynamically

  • verify_block (defaults to: nil) —

    an optional block which is called when a new value is set. Check value is valid. This could be type checks or if a folder/file exists You have to raise a specific exception if something goes wrong. Append .red after the string

  • is_string (defaults to: true) —

    *DEPRECATED: Use ‘type` instead* (Boolean) is that parameter a string? Defaults to true. If it’s true, the type string will be verified.

  • type (Class) (defaults to: nil) —

    the data type of this config item. Takes precedence over ‘is_string`. Use `:shell_string` to allow types `String`, `Hash` and `Array` that will be converted to shell-escaped strings

  • skip_type_validation (Boolean) (defaults to: false) —

    is false by default. If set to true, type of the parameter will not be validated.

  • optional (Boolean) (defaults to: nil) —

    is false by default. If set to true, also string values will not be asked to the user

  • conflicting_options ([]) (defaults to: nil) —

    array of conflicting option keys(@param key). This allows to resolve conflicts intelligently

  • conflict_block (defaults to: nil) —

    an optional block which is called when options conflict happens

  • deprecated (Boolean|String) (defaults to: nil) —

    Set if the option is deprecated. A deprecated option should be optional and is made optional if the parameter isn’t set, and fails otherwise

  • sensitive (Boolean) (defaults to: nil) —

    Set if the variable is sensitive, such as a password or API token, to prevent echoing when prompted for the parameter

  • display_in_shell (Boolean) (defaults to: true) —

    Set if the variable can be used from shell



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 90

def initialize(key: nil,
               env_name: nil,
               description: nil,
               short_option: nil,
               default_value: nil,
               default_value_dynamic: false,
               verify_block: nil,
               is_string: true,
               type: nil,
               skip_type_validation: false,
               optional: nil,
               conflicting_options: nil,
               conflict_block: nil,
               deprecated: nil,
               sensitive: nil,
               code_gen_sensitive: false,
               code_gen_default_value: nil,
               display_in_shell: true)
  UI.user_error!("key must be a symbol") unless key.kind_of?(Symbol)
  UI.user_error!("env_name must be a String") unless (env_name || '').kind_of?(String)

  if short_option
    UI.user_error!("short_option for key :#{key} must of type String") unless short_option.kind_of?(String)
    UI.user_error!("short_option for key :#{key} must be a string of length 1") unless short_option.delete('-').length == 1
  end

  if description
    UI.user_error!("Do not let descriptions end with a '.', since it's used for user inputs as well for key :#{key}") if description[-1] == '.'
  end

  if conflicting_options
    conflicting_options.each do |conflicting_option_key|
      UI.user_error!("Conflicting option key must be a symbol") unless conflicting_option_key.kind_of?(Symbol)
    end
  end

  if deprecated
    # deprecated options are automatically optional
    optional = true if optional.nil?
    UI.crash!("Deprecated option must be optional") unless optional

    # deprecated options are marked deprecated in their description
    description = deprecated_description(description, deprecated)
  end

  optional = false if optional.nil?
  sensitive = false if sensitive.nil?

  @key = key
  @env_name = env_name
  @description = description
  @short_option = short_option
  @default_value = default_value
  @default_value_dynamic = default_value_dynamic
  @verify_block = verify_block
  @is_string = is_string
  @data_type = type
  @data_type = String if type == :shell_string
  @optional = optional
  @conflicting_options = conflicting_options
  @conflict_block = conflict_block
  @deprecated = deprecated
  @sensitive = sensitive
  @code_gen_sensitive = code_gen_sensitive || sensitive
  @allow_shell_conversion = (type == :shell_string)
  @display_in_shell = display_in_shell
  @skip_type_validation = skip_type_validation # sometimes we allow multiple types which causes type validation failures, e.g.: export_options in gym

  @code_gen_default_value = code_gen_default_value

  update_code_gen_default_value_if_able!
end

Instance Attribute Details

#allow_shell_conversion ⇒ Object

Boolean

Set if the variable is to be converted to a shell-escaped String when provided as a Hash or Array

Allows items expected to be strings used in shell arguments to be alternatively provided as a Hash or Array for better readability and auto-escaped for us.



65
66
67
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 65

def allow_shell_conversion
  @allow_shell_conversion
end

#code_gen_default_value ⇒ Object

the value which is used during Swift code generation

if the default_value reads from ENV or a file, or from local credentials, we need
to provide a different default or it might be included in our autogenerated Swift
as a built-in default for the fastlane gem. This is because when we generate the
Swift API at deployment time, it fetches the default_value from the config_items



31
32
33
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 31

def code_gen_default_value
  @code_gen_default_value
end

#code_gen_sensitive ⇒ Object

Boolean

Set if the default value should never be used during code generation for Swift

We generate the Swift API at deployment time, and if there is a value that should never be
included in the Fastlane.swift or other autogenerated classes, we need to strip it out.
This includes things like API keys that could be read from ENV[]



61
62
63
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 61

def code_gen_sensitive
  @code_gen_sensitive
end

#conflict_block ⇒ Object

An optional block which is called when options conflict happens



48
49
50
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 48

def conflict_block
  @conflict_block
end

#conflicting_options ⇒ Object

Array

array of conflicting option keys(@param key). This allows to resolve conflicts intelligently



45
46
47
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 45

def conflicting_options
  @conflicting_options
end

#default_value ⇒ Object

the value which is used if there was no given values and no environment values



21
22
23
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 21

def default_value
  @default_value
end

#default_value_dynamic ⇒ Object

Boolean

Set if the default value is generated dynamically



24
25
26
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 24

def default_value_dynamic
  @default_value_dynamic
end

#deprecated ⇒ Object

String

Set if the option is deprecated. A deprecated option should be optional and is made optional if the parameter isn’t set, and fails otherwise



51
52
53
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 51

def deprecated
  @deprecated
end

#description ⇒ Object

String

A description shown to the user



15
16
17
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 15

def description
  @description
end

#display_in_shell ⇒ Object

Boolean

Set if the variable can be used from shell



68
69
70
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 68

def display_in_shell
  @display_in_shell
end

#env_name ⇒ Object

String

the name of the environment variable, which is only used if no other values were found



12
13
14
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 12

def env_name
  @env_name
end

#key ⇒ Object

Symbol

the key which is used as command parameters or key in the fastlane tools



9
10
11
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 9

def key
  @key
end

#optional ⇒ Object

Boolean

is false by default. If set to true, also string values will not be asked to the user



39
40
41
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 39

def optional
  @optional
end

#sensitive ⇒ Object

Boolean

Set if the variable is sensitive, such as a password or API token, to prevent echoing when prompted for the parameter

If a default value exists, it won’t be used during code generation as default values can read from environment variables.



55
56
57
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 55

def sensitive
  @sensitive
end

#short_option ⇒ Object

String

A string of length 1 which is used for the command parameters (e.g. -f)



18
19
20
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 18

def short_option
  @short_option
end

#skip_type_validation ⇒ Object

Boolean

is false by default. If set to true, type of the parameter will not be validated.



42
43
44
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 42

def skip_type_validation
  @skip_type_validation
end

#verify_block ⇒ Object

An optional block which is called when a new value is set.

Check value is valid. This could be type checks or if a folder/file exists
You have to raise a specific exception if something goes wrong. Use `user_error!` for the message: UI.user_error!("your message")



36
37
38
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 36

def verify_block
  @verify_block
end

Instance Method Details

#auto_convert_value(value) ⇒ Object

Returns an updated value type (if necessary)



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 231

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

  if data_type == Array
    return value.split(',') if value.kind_of?(String)
  elsif data_type == Integer
    return value.to_i if value.to_i.to_s == value.to_s
  elsif data_type == Float
    return value.to_f if value.to_f.to_s == value.to_s
  elsif allow_shell_conversion
    return value.shelljoin if value.kind_of?(Array)
    return value.map { |k, v| "#{k.to_s.shellescape}=#{v.shellescape}" }.join(' ') if value.kind_of?(Hash)
  elsif data_type != String
    # Special treatment if the user specified true, false or YES, NO
    # There is no boolean type, so we just do it here
    if %w(YES yes true TRUE).include?(value)
      return true
    elsif %w(NO no false FALSE).include?(value)
      return false
    end
  end

  return value # fallback to not doing anything
end

#data_type ⇒ Object

Determines the defined data type of this ConfigItem



257
258
259
260
261
262
263
264
265
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 257

def data_type
  if @data_type.kind_of?(Symbol)
    nil
  elsif @data_type
    @data_type
  else
    (@is_string ? String : nil)
  end
end

#deprecated_description(initial_description, deprecated) ⇒ Object 



281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 281

def deprecated_description(initial_description, deprecated)
  has_description = !initial_description.to_s.empty?

  description = "**DEPRECATED!**"

  if deprecated.kind_of?(String)
    description << " #{deprecated}"
    description << " -" if has_description
  end

  description << " #{initial_description}" if has_description

  description
end

#doc_default_value ⇒ Object 



296
297
298
299
300
301
302
303
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 296

def doc_default_value
  return "[*](#parameters-legend-dynamic)" if self.default_value_dynamic
  return "" if self.default_value.nil?
  return "`''`" if self.default_value.instance_of?(String) && self.default_value.empty?
  return "`:#{self.default_value}`" if self.default_value.instance_of?(Symbol)

  "`#{self.default_value}`"
end

#ensure_boolean_type_passes_validation(value) ⇒ Object 



194
195
196
197
198
199
200
201
202
203
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 194

def ensure_boolean_type_passes_validation(value)
  if @skip_type_validation
    return
  end

  # We need to explicitly test against Fastlane::Boolean, TrueClass/FalseClass
  if value.class != FalseClass && value.class != TrueClass
    UI.user_error!("'#{self.key}' value must be either `true` or `false`! Found #{value.class} instead.")
  end
end

#ensure_generic_type_passes_validation(value) ⇒ Object 



184
185
186
187
188
189
190
191
192
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 184

def ensure_generic_type_passes_validation(value)
  if @skip_type_validation
    return
  end

  if data_type != :string_callback && data_type && !value.kind_of?(data_type)
    UI.user_error!("'#{self.key}' value must be a #{data_type}! Found #{value.class} instead.")
  end
end

#help_default_value ⇒ Object 



305
306
307
308
309
310
311
312
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 305

def help_default_value
  return "#{self.default_value} *".strip if self.default_value_dynamic
  return "" if self.default_value.nil?
  return "''" if self.default_value.instance_of?(String) && self.default_value.empty?
  return ":#{self.default_value}" if self.default_value.instance_of?(Symbol)

  self.default_value
end

#is_string ⇒ Object

it’s preferred to use self.string? In most cases, except in commander_generator.rb, cause… reasons



273
274
275
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 273

def is_string
  return @is_string
end

#string? ⇒ Boolean

Replaces the attr_accessor, but maintains the same interface

Returns:



268
269
270
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 268

def string?
  data_type == String
end

#to_s ⇒ Object 



277
278
279
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 277

def to_s
  [@key, @description].join(": ")
end

#update_code_gen_default_value_if_able! ⇒ Object

if code_gen_default_value is nil, use the default value if it isn’t a ‘code_gen_sensitive` value



165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 165

def update_code_gen_default_value_if_able!
  # we don't support default values for procs
  if @data_type == :string_callback
    @code_gen_default_value = nil
    return
  end

  if @code_gen_default_value.nil?
    unless @code_gen_sensitive

      @code_gen_default_value = @default_value
    end
  end
end

#valid?(value) ⇒ Boolean

Make sure, the value is valid (based on the verify block) Raises an exception if the value is invalid

Returns:



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 207

def valid?(value)
  # we also allow nil values, which do not have to be verified.
  return true if value.nil?

  # Verify that value is the type that we're expecting, if we are expecting a type
  if data_type == Fastlane::Boolean
    ensure_boolean_type_passes_validation(value)
  else
    ensure_generic_type_passes_validation(value)
  end

  if @verify_block
    begin
      @verify_block.call(value)
    rescue => ex
      UI.error("Error setting value '#{value}' for option '#{@key}'")
      raise Interface::FastlaneError.new, ex.to_s
    end
  end

  true
end

#verify!(value) ⇒ Object 



180
181
182
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 180

def verify!(value)
  valid?(value)
end