class PantographCore::ConfigItem
Attributes
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 pantograph gem. This is because when we generate the Swift API at deployment time, it fetches the default_value from the config_items
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 Pantograph.swift or other autogenerated classes, we need to strip it out. This includes things like API keys that could be read from ENV[]
An optional block which is called when options conflict happens
Array
-
array of conflicting option keys(@param key). This allows to resolve conflicts intelligently
the value which is used if there was no given values and no environment values
Boolean
-
Set if the default value is generated dynamically
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
String
-
A description shown to the user
Boolean
-
Set if the variable can be used from shell
String
-
the name of the environment variable, which is only used if no other values were found
- Symbol
-
the key which is used as command parameters or key in the pantograph tools
Boolean
-
is false by default. If set to true, also string values will not be asked to the user
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.
String
-
A string of length 1 which is used for the command parameters (e.g. -f)
Boolean
-
is false by default. If set to true, type of the parameter will not be validated.
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")
Public Class Methods
Creates a new option @param key (Symbol) the key which is used as command parameters or key in the pantograph tools @param env_name
(String
) the name of the environment variable, which is only used if no other values were found @param description (String
) A description shown to the user @param short_option
(String
) A string of length 1 which is used for the command parameters (e.g. -f) @param default_value
the value which is used if there was no given values and no environment values @param default_value_dynamic
(Boolean
) Set if the default value is generated dynamically @param verify_block
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
@param is_string
*DEPRECATED: Use `type` instead* (Boolean
) is that parameter a string? Defaults to true. If it's true, the type string will be verified. @param type (Class) 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 @param skip_type_validation
(Boolean
) is false by default. If set to true, type of the parameter will not be validated. @param optional (Boolean
) is false by default. If set to true, also string values will not be asked to the user @param conflicting_options
([]) array of conflicting option keys(@param key). This allows to resolve conflicts intelligently @param conflict_block
an optional block which is called when options conflict happens @param deprecated (Boolean|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 @param sensitive (Boolean
) Set if the variable is sensitive, such as a password or API token, to prevent echoing when prompted for the parameter @param display_in_shell
(Boolean
) Set if the variable can be used from shell rubocop:disable Metrics/ParameterLists
# File pantograph_core/lib/pantograph_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
Public Instance Methods
Returns an updated value type (if necessary)
# File pantograph_core/lib/pantograph_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
Determines the defined data type of this ConfigItem
# File pantograph_core/lib/pantograph_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
# File pantograph_core/lib/pantograph_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
# File pantograph_core/lib/pantograph_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
# File pantograph_core/lib/pantograph_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 Pantograph::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
# File pantograph_core/lib/pantograph_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
# File pantograph_core/lib/pantograph_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
it's preferred to use self.string? In most cases, except in commander_generator.rb, cause⦠reasons
# File pantograph_core/lib/pantograph_core/configuration/config_item.rb, line 273 def is_string return @is_string end
Replaces the attr_accessor, but maintains the same interface
# File pantograph_core/lib/pantograph_core/configuration/config_item.rb, line 268 def string? data_type == String end
# File pantograph_core/lib/pantograph_core/configuration/config_item.rb, line 277 def to_s [@key, @description].join(": ") end
if code_gen_default_value
is nil, use the default value if it isn't a `code_gen_sensitive` value
# File pantograph_core/lib/pantograph_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
Make sure, the value is valid (based on the verify block) Raises an exception if the value is invalid
# File pantograph_core/lib/pantograph_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 == Pantograph::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::PantographError.new, ex.to_s end end true end
# File pantograph_core/lib/pantograph_core/configuration/config_item.rb, line 180 def verify!(value) valid?(value) end