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



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
162
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 91

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.



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

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



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

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[]



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

def code_gen_sensitive
  @code_gen_sensitive
end

#conflict_block ⇒ Object

An optional block which is called when options conflict happens



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

def conflict_block
  @conflict_block
end

#conflicting_options ⇒ Object

Array

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



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

def conflicting_options
  @conflicting_options
end

#default_value ⇒ Object

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



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

def default_value
  @default_value
end

#default_value_dynamic ⇒ Object

Boolean

Set if the default value is generated dynamically



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

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



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

def deprecated
  @deprecated
end

#description ⇒ Object

String

A description shown to the user



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

def description
  @description
end

#display_in_shell ⇒ Object

Boolean

Set if the variable can be used from shell



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

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



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

def env_name
  @env_name
end

#key ⇒ Object

Symbol

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



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

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



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

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.



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

def sensitive
  @sensitive
end

#short_option ⇒ Object

String

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



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

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.



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

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")



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

def verify_block
  @verify_block
end

Instance Method Details

#auto_convert_value(value) ⇒ Object

rubocop:disable Metrics/PerceivedComplexity Returns an updated value type (if necessary)



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 233

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 == Hash && value.kind_of?(String)
    begin
      parsed = JSON.parse(value)
      return parsed if parsed.kind_of?(Hash)
    rescue JSON::ParserError
    end
  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
  # rubocop:enable Metrics/PerceivedComplexity

  return value # fallback to not doing anything
end

#data_type ⇒ Object

Determines the defined data type of this ConfigItem



266
267
268
269
270
271
272
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 266

def data_type
  if @data_type
    @data_type
  else
    (@is_string ? String : nil)
  end
end

#deprecated_description(initial_description, deprecated) ⇒ Object 



288
289
290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 288

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 



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

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 



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

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 



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

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 



312
313
314
315
316
317
318
319
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 312

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



280
281
282
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 280

def is_string
  return @is_string
end

#string? ⇒ Boolean

Replaces the attr_accessor, but maintains the same interface

Returns:



275
276
277
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 275

def string?
  data_type == String
end

#to_s ⇒ Object 



284
285
286
 
# File 'fastlane_core/lib/fastlane_core/configuration/config_item.rb', line 284

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



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

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:



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

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 



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

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