pantograph 0.1.0

data/pantograph_core/lib/pantograph_core/configuration/config_item.rb

@@ -0,0 +1,314 @@
+require_relative '../ui/ui'
+require_relative '../ui/errors/pantograph_error'
+require_relative '../helper'
+require_relative '../module'
+
+module PantographCore
+  class ConfigItem
+    # [Symbol] the key which is used as command parameters or key in the pantograph tools
+    attr_accessor :key
+
+    # [String] the name of the environment variable, which is only used if no other values were found
+    attr_accessor :env_name
+
+    # [String] A description shown to the user
+    attr_accessor :description
+
+    # [String] A string of length 1 which is used for the command parameters (e.g. -f)
+    attr_accessor :short_option
+
+    # the value which is used if there was no given values and no environment values
+    attr_accessor :default_value
+
+    # [Boolean] Set if the default value is generated dynamically
+    attr_accessor :default_value_dynamic
+
+    # 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
+    attr_accessor :code_gen_default_value
+
+    # 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")
+    attr_accessor :verify_block
+
+    # [Boolean] is false by default. If set to true, also string values will not be asked to the user
+    attr_accessor :optional
+
+    # [Boolean] is false by default. If set to true, type of the parameter will not be validated.
+    attr_accessor :skip_type_validation
+
+    # [Array] array of conflicting option keys(@param key). This allows to resolve conflicts intelligently
+    attr_accessor :conflicting_options
+
+    # An optional block which is called when options conflict happens
+    attr_accessor :conflict_block
+
+    # [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
+    attr_accessor :deprecated
+
+    # [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.
+    attr_accessor :sensitive
+
+    # [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[]
+    attr_accessor :code_gen_sensitive
+
+    # [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.
+    attr_accessor :allow_shell_conversion
+
+    # [Boolean] Set if the variable can be used from shell
+    attr_accessor :display_in_shell
+
+    # 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
+    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
+    # rubocop:enable Metrics/ParameterLists
+
+    # if code_gen_default_value is nil, use the default value if it isn't a `code_gen_sensitive` value
+    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
+
+    def verify!(value)
+      valid?(value)
+    end
+
+    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
+
+    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
+
+    # Make sure, the value is valid (based on the verify block)
+    # Raises an exception if the value is invalid
+    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
+
+    # Returns an updated value type (if necessary)
+    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
+    def data_type
+      if @data_type.kind_of?(Symbol)
+        nil
+      elsif @data_type
+        @data_type
+      else
+        (@is_string ? String : nil)
+      end
+    end
+
+    # Replaces the attr_accessor, but maintains the same interface
+    def string?
+      data_type == String
+    end
+
+    # it's preferred to use self.string? In most cases, except in commander_generator.rb, cause... reasons
+    def is_string
+      return @is_string
+    end
+
+    def to_s
+      [@key, @description].join(": ")
+    end
+
+    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
+
+    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
+
+    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
+  end
+end

data/pantograph_core/lib/pantograph_core/configuration/configuration.rb

@@ -0,0 +1,332 @@
+require_relative '../helper'
+require_relative '../globals'
+require_relative 'config_item'
+require_relative 'commander_generator'
+require_relative 'configuration_file'
+
+module PantographCore
+  class Configuration
+    attr_accessor :available_options
+
+    attr_accessor :values
+
+    # @return [Array] An array of symbols which are all available keys
+    attr_reader :all_keys
+
+    # @return [String] The name of the configuration file (not the path). Optional!
+    attr_accessor :config_file_name
+
+    # @return [Hash] Options that were set from a config file using load_configuration_file. Optional!
+    attr_accessor :config_file_options
+
+    def self.create(available_options, values)
+      UI.user_error!("values parameter must be a hash") unless values.kind_of?(Hash)
+      v = values.dup
+      v.each do |key, val|
+        v[key] = val.dup if val.kind_of?(String) # this is necessary when fetching a value from an environment variable
+      end
+
+      if v.kind_of?(Hash) && available_options.kind_of?(Array) # we only want to deal with the new configuration system
+        # Now see if --verbose would be a valid input
+        # If not, it might be because it's an action and not a tool
+        unless available_options.find { |a| a.kind_of?(ConfigItem) && a.key == :verbose }
+          v.delete(:verbose) # as this is being processed by commander
+        end
+      end
+      Configuration.new(available_options, v)
+    end
+
+    #####################################################
+    # @!group Setting up the configuration
+    #####################################################
+
+    # collect sensitive strings
+    def self.sensitive_strings
+      @sensitive_strings ||= []
+    end
+
+    def initialize(available_options, values)
+      self.available_options = available_options || []
+      self.values = values || {}
+      self.config_file_options = {}
+
+      # used for pushing and popping values to provide nesting configuration contexts
+      @values_stack = []
+
+      # if we are in captured output mode - keep a array of sensitive option values
+      # those will be later - replaced by ####
+      if PantographCore::Globals.capture_output?
+        available_options.each do |element|
+          next unless element.sensitive
+          self.class.sensitive_strings << values[element.key]
+        end
+      end
+
+      verify_input_types
+      verify_value_exists
+      verify_no_duplicates
+      verify_conflicts
+      verify_default_value_matches_verify_block
+    end
+
+    def verify_input_types
+      UI.user_error!("available_options parameter must be an array of ConfigItems but is #{@available_options.class}") unless @available_options.kind_of?(Array)
+      @available_options.each do |item|
+        UI.user_error!("available_options parameter must be an array of ConfigItems. Found #{item.class}.") unless item.kind_of?(ConfigItem)
+      end
+      UI.user_error!("values parameter must be a hash") unless @values.kind_of?(Hash)
+    end
+
+    def verify_value_exists
+      # Make sure the given value keys exist
+      @values.each do |key, value|
+        next if key == :trace # special treatment
+        option = self.verify_options_key!(key)
+        @values[key] = option.auto_convert_value(value)
+        UI.deprecated("Using deprecated option: '--#{key}' (#{option.deprecated})") if option.deprecated
+        option.verify!(@values[key]) # Call the verify block for it too
+      end
+    end
+
+    def verify_no_duplicates
+      # Make sure a key was not used multiple times
+      @available_options.each do |current|
+        count = @available_options.count { |option| option.key == current.key }
+        UI.user_error!("Multiple entries for configuration key '#{current.key}' found!") if count > 1
+
+        unless current.short_option.to_s.empty?
+          count = @available_options.count { |option| option.short_option == current.short_option }
+          UI.user_error!("Multiple entries for short_option '#{current.short_option}' found!") if count > 1
+        end
+      end
+    end
+
+    def verify_conflicts
+      option_keys = @values.keys
+
+      option_keys.each do |current|
+        index = @available_options.find_index { |item| item.key == current }
+        current = @available_options[index]
+
+        # ignore conflicts because option value is nil
+        next if @values[current.key].nil?
+
+        next if current.conflicting_options.nil?
+
+        conflicts = current.conflicting_options & option_keys
+        next if conflicts.nil?
+
+        conflicts.each do |conflicting_option_key|
+          index = @available_options.find_index { |item| item.key == conflicting_option_key }
+          conflicting_option = @available_options[index]
+
+          # ignore conflicts because because value of conflict option is nil
+          next if @values[conflicting_option.key].nil?
+
+          if current.conflict_block
+            begin
+              current.conflict_block.call(conflicting_option)
+            rescue => ex
+              UI.error("Error resolving conflict between options: '#{current.key}' and '#{conflicting_option.key}'")
+              raise ex
+            end
+          else
+            UI.user_error!("Unresolved conflict between options: '#{current.key}' and '#{conflicting_option.key}'")
+          end
+        end
+      end
+    end
+
+    # Verifies the default value is also valid
+    def verify_default_value_matches_verify_block
+      @available_options.each do |item|
+        next unless item.verify_block && item.default_value
+
+        begin
+          unless @values[item.key] # this is important to not verify if there already is a value there
+            item.verify_block.call(item.default_value)
+          end
+        rescue => ex
+          UI.error(ex)
+          UI.user_error!("Invalid default value for #{item.key}, doesn't match verify_block")
+        end
+      end
+    end
+
+    # This method takes care of parsing and using the configuration file as values
+    # Call this once you know where the config file might be located
+    # Take a look at how `gym` uses this method
+    #
+    # @param config_file_name [String] The name of the configuration file to use (optional)
+    # @param block_for_missing [Block] A ruby block that is called when there is an unknown method
+    #   in the configuration file
+    def load_configuration_file(config_file_name = nil, block_for_missing = nil, skip_printing_values = false)
+      return unless config_file_name
+
+      self.config_file_name = config_file_name
+
+      path = PantographCore::Configuration.find_configuration_file_path(config_file_name: config_file_name)
+      return if path.nil?
+
+      begin
+        configuration_file = ConfigurationFile.new(self, path, block_for_missing, skip_printing_values)
+        options = configuration_file.options
+      rescue PantographCore::ConfigurationFile::ExceptionWhileParsingError => e
+        options = e.recovered_options
+        wrapped_exception = e.wrapped_exception
+      end
+
+      # Make sure all the values set in the config file pass verification
+      options.each do |key, val|
+        option = self.verify_options_key!(key)
+        option.verify!(val)
+      end
+
+      # Merge the new options into the old ones, keeping all previously set keys
+      self.config_file_options = options.merge(self.config_file_options)
+
+      verify_conflicts # important, since user can set conflicting options in configuration file
+
+      # Now that everything is verified, re-raise an exception that was raised in the config file
+      raise wrapped_exception unless wrapped_exception.nil?
+
+      configuration_file
+    end
+
+    def self.find_configuration_file_path(config_file_name: nil)
+      paths = []
+      paths += Dir["./pantograph/#{config_file_name}"]
+      paths += Dir["./.pantograph/#{config_file_name}"]
+      paths += Dir["./#{config_file_name}"]
+      paths += Dir["./pantograph_core/spec/fixtures/#{config_file_name}"] if Helper.test?
+      return nil if paths.count == 0
+      return paths.first
+    end
+
+    #####################################################
+    # @!group Actually using the class
+    #####################################################
+
+    # Returns the value for a certain key. pantograph_core tries to fetch the value from different sources
+    # if 'ask' is true and the value is not present, the user will be prompted to provide a value
+    # rubocop:disable Metrics/PerceivedComplexity
+    def fetch(key, ask: true)
+      UI.crash!("Key '#{key}' must be a symbol. Example :app_id.") unless key.kind_of?(Symbol)
+
+      option = verify_options_key!(key)
+
+      # Same order as https://docs.pantograph.tools/advanced/#priorities-of-parameters-and-options
+      value = if @values.key?(key) && !@values[key].nil?
+                @values[key]
+              elsif option.env_name && !ENV[option.env_name].nil?
+                # verify! before using (see https://github.com/pantograph/pantograph/issues/14449)
+                ENV[option.env_name].dup if option.verify!(option.auto_convert_value(ENV[option.env_name]))
+              elsif self.config_file_options.key?(key)
+                self.config_file_options[key]
+              else
+                option.default_value
+              end
+
+      value = option.auto_convert_value(value)
+      value = nil if value.nil? && !option.string? # by default boolean flags are false
+      return value unless value.nil? && !option.optional && ask
+
+      # fallback to asking
+      if Helper.test? || !UI.interactive?
+        # Since we don't want to be asked on tests, we'll just call the verify block with no value
+        # to raise the exception that is shown when the user passes an invalid value
+        set(key, '')
+        # If this didn't raise an exception, just raise a default one
+        UI.user_error!("No value found for '#{key}'")
+      end
+
+      while value.nil?
+        UI.important("To not be asked about this value, you can specify it using '#{option.key}'") if ENV["PANTOGRAPH_ONBOARDING_IN_PROCESS"].to_s.length == 0
+        value = option.sensitive ? UI.password("#{option.description}: ") : UI.input("#{option.description}: ")
+        # Also store this value to use it from now on
+        begin
+          set(key, value)
+        rescue => ex
+          puts(ex)
+          value = nil
+        end
+      end
+
+      # It's very, very important to use the self[:my_key] notation
+      # as this will make sure to use the `fetch` method
+      # that is responsible for auto converting the values into the right
+      # data type
+      # Found out via https://github.com/pantograph/pantograph/issues/11243
+      return self[key]
+    end
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    # Overwrites or sets a new value for a given key
+    # @param key [Symbol] Must be a symbol
+    def set(key, value)
+      UI.crash!("Key '#{key}' must be a symbol. Example :#{key}.") unless key.kind_of?(Symbol)
+      option = option_for_key(key)
+
+      unless option
+        UI.user_error!("Could not find option '#{key}' in the list of available options: #{@available_options.collect(&:key).join(', ')}")
+      end
+
+      option.verify!(value)
+
+      @values[key] = value
+      true
+    end
+
+    # see fetch
+    def values(ask: true)
+      # As the user accesses all values, we need to iterate through them to receive all the values
+      @available_options.each do |option|
+        @values[option.key] = fetch(option.key, ask: ask) unless @values[option.key]
+      end
+      @values
+    end
+
+    # Direct access to the values, without iterating through all items
+    def _values
+      @values
+    end
+
+    # Clears away any current configuration values by pushing them onto a stack.
+    # Values set after calling push_values! will be merged with the previous
+    # values after calling pop_values!
+    #
+    # see: pop_values!
+    def push_values!
+      @values_stack.push(@values)
+      @values = {}
+    end
+
+    # Restores a previous set of configuration values by merging any current
+    # values on top of them
+    #
+    # see: push_values!
+    def pop_values!
+      return if @values_stack.empty?
+      @values = @values_stack.pop.merge(@values)
+    end
+
+    def all_keys
+      @available_options.collect(&:key)
+    end
+
+    # Returns the config_item object for a given key
+    def option_for_key(key)
+      @available_options.find { |o| o.key == key }
+    end
+
+    # Aliases `[key]` to `fetch(key)` because Ruby can do it.
+    alias [] fetch
+    alias []= set
+
+    def verify_options_key!(key)
+      option = option_for_key(key)
+      UI.user_error!("Could not find option '#{key}' in the list of available options: #{@available_options.collect(&:key).join(', ')}") unless option
+      option
+    end
+  end
+end