vapir-common 1.7.2 → 1.8.0

data/History.txt

@@ -1,5 +0,0 @@
-=== 0.0.1 / 2008-08-28
-
-* Created
-
-

data/lib/vapir-common.rb

@@ -1,7 +1,19 @@
+require 'vapir-common/version'
+require 'vapir-common/external/core_extensions.rb'
+require 'vapir-common/browser'
+require 'vapir-common/exceptions'
+require 'vapir-common/config'
 module Vapir
-  module Common
-    VERSION = '1.7.2'
+  def self.require_winwindow
+    begin
+      require 'winwindow'
+    rescue LoadError
+      message = if RUBY_PLATFORM =~ /mswin|windows|mingw32|cygwin/i
+        "This may be resolved by installing the winwindow gem."
+      else
+        "You do not appear to be on Windows - this method is not likely to work."
+      end
+      raise LoadError, $!.message + "\n\n#{message}", $!.backtrace
+    end
   end
 end
-require 'vapir-common/browser'
-require 'vapir-common/exceptions'

data/lib/vapir-common/browser.rb

@@ -1,63 +1,17 @@
 # vapir-common/browser
-require 'vapir-common/options'
-module Vapir
-  
-=begin rdoc
-
-Watir is a family of open-source drivers for automating web browsers. You
-can use it to write tests that are easy to read and maintain. 
-
-Watir drives browsers the same way people do. It clicks links, fills in forms,
-presses buttons. Watir also checks results, such as whether expected text 
-appears on a page.
-
-The Watir family currently includes support for Internet Explorer (on Windows),
-Firefox (on Windows, Mac and Linux) and Safari (on Mac). 
-
-Project Homepage: http://wtr.rubyforge.org
-
-This Browser module provides a generic interface
-that tests can use to access any browser. The actual browser (and thus
-the actual Watir driver) is determined at runtime based on configuration
-settings.
-
-  require 'vapir'
-  browser = Watir::Browser.new
-  browser.goto 'http://google.com'
-  browser.text_field(:name, 'q').set 'pickaxe'
-  browser.button(:name, 'btnG').click
-  if browser.text.include? 'Programming Ruby'
-    puts 'Text was found'
-  else
-    puts 'Text was not found'
-  end
-
-A comprehensive summary of the Watir API can be found here
-http://wiki.openqa.org/display/WTR/Methods+supported+by+Element
-
-There are two ways to configure the browser that will be used by your tests.
-
-One is to set the +watir_browser+ environment variable to +ie+ or +firefox+. 
-(How you do this depends on your platform.)
-
-The other is to create a file that looks like this.
-
-  browser: ie
-
-And then to add this line to your script, after the require statement and 
-before you invoke Browser.new.
-
-  Watir.options_file = 'path/to/the/file/you/just/created'
+require 'vapir-common/options' # stub; this stuff is deprecated 
+require 'vapir-common/config'
+require 'vapir-common/version'
+require 'vapir-common/browsers'
 
-=end rdoc
-  
+module Vapir
+  # The common Browser class from which classes specific to Firefox or IE browsers inherit. 
+  # 
+  # Calls to this class are delegated to a browser inheriting from this, which is set using config.default_browser
   class Browser
-    @@browser_classes = {}
-    @@sub_options = {}
-    @@default = nil
     class << self
-      alias __new__ new
-      def inherited(subclass)
+      alias __new__ new # :nodoc:
+      def inherited(subclass) # :nodoc:
         class << subclass
           alias new __new__
         end
@@ -67,105 +21,61 @@ before you invoke Browser.new.
       # configuration settings. (Don't be fooled: this is not actually 
       # an instance of Browser class.)
       def new *args, &block
-        #set_sub_options
-        browser=klass.new *args, &block
-        #browser=klass.allocate
-        #browser.send :initialize, *args, &block
+        browser=browser_class.new *args, &block
         browser
       end
-      # makes sure that the class methods of Browser that call to the class methods of klass 
-      # are overridden so that Browser class methods aren't inherited causing infinite loop. 
-      def ensure_overridden
-        if self==klass
-          raise NotImplementedError, "This method must be overridden by #{self}!"
-        end
-      end
+      alias new_window new
 
-      # Create a new instance as with #new and start the browser on the
-      # specified url.
-      def start url
-        ensure_overridden
-        set_sub_options
-        klass.start url
-      end
-      # Attach to an existing browser.
-      def attach(how, what)
-        ensure_overridden
-        set_sub_options
-        klass.attach(how, what)
+      # Create a new browser instance, starting at the specified url.
+      # If no url is given, start at about:blank.
+      def start(url='about:blank', options={})
+        raise ArgumentError, "URL must be a string; got #{url.inspect}" unless url.is_a?(String)
+        new(options.merge(:goto => url))
       end
-      def set_options options
-        #ensure_overridden
-        unless self==klass
-          klass.set_options options
-        end
-      end
-      def options
-        self==klass ? {} : klass.options
+      alias start_window start
+
+      # Attach to an existing browser window. Returns an instance of the current default browser class. 
+      #
+      # the window to be attached to can be
+      # referenced by url, title, or window handle ('how' argument)
+      #
+      # The 'what' argument can be either a string or a regular expression, in the 
+      # case of of :url or :title. 
+      #
+      #  Vapir::Browser.attach(:url, 'http://www.google.com')
+      #  Vapir::Browser.attach(:title, 'Google')
+      #  Vapir::Browser.attach(:hwnd, 528140)
+      #
+      # see the implementing browser's +new+ method for more details on what may be passed. 
+      def attach(how, what, options={})
+        new(options.merge(:attach => [how, what]))
       end
+      alias find attach
 
-      def klass
-        key = Vapir.options[:browser]
-        #eval(@@browser_classes[key]) # this triggers the autoload
-        browser_class_name=@@browser_classes[key]
-        klass=browser_class_name.split('::').inject(Object) do |namespace, name_part|
-          namespace.const_get(name_part)
-        end
-      end
-      private :klass
-      # Add support for the browser option, using the specified class, 
-      # provided as a string. Optionally, additional options supported by
-      # the class can be specified as an array of symbols. Options specified
-      # by the user and included in this list will be passed (as a hash) to 
-      # the set_options class method (if defined) before creating an instance.
-      def support hash_args
-        option = hash_args[:name]
-        class_string = hash_args[:class]
-        additional_options = hash_args[:options]
-        library = hash_args[:library]
-        gem = hash_args[:gem] || library
-
-        @@browser_classes[option] = class_string
-        @@sub_options[option] = additional_options
-
-        autoload class_string, library
-        activate_gem gem, option
+      def browser_class
+        key = Vapir.config.default_browser
+        browser_class=SupportedBrowsers[key.to_sym][:class_name].split('::').inject(Object) do |namespace, name_part|
+          namespace.const_get(name_part) # this triggers autoload if it's not loaded 
+        end
       end
+      private :browser_class
       
       def default
-        @@default
+        # deprecate
+        Vapir.config.default_browser
       end
       # Specifies a default browser. Must be specified before options are parsed.
-      def default= option
-        @@default = option
-      end
-      # Returns the names of the browsers that are supported by this module.
-      # These are the options for 'watir_browser' (env var) or 'browser:' (yaml).
-      def browser_names
-        @@browser_classes.keys
-      end
-      
-      private
-      def autoload class_string, library
-        mod, klass = class_string.split('::')
-        eval "module ::#{mod}; autoload :#{klass}, '#{library}'; end"
-      end
-      # Activate the gem (if installed). The default browser will be set
-      # to the first gem that activates.
-      def activate_gem gem_name, option
-        begin
-          gem gem_name 
-          @@default ||= option
-        rescue Gem::LoadError
-        end
-      end
-      def set_sub_options
-        sub_options = @@sub_options[Vapir.options[:browser]]
-        return if sub_options.nil?
-        specified_options = Vapir.options.reject {|k, v| !sub_options.include? k}
-        self.set_options specified_options
+      def default= default_browser
+        # deprecate
+        Vapir.config.default_browser = default_browser
       end
     end
+
+    include Configurable
+    def configuration_parent
+      browser_class.config
+    end
+    
     # locate is used by stuff that uses container. this doesn't actually locate the browser
     # but checks if it (still) exists. 
     def locate(options={})
@@ -177,8 +87,143 @@ before you invoke Browser.new.
     def inspect
       "#<#{self.class}:0x#{(self.hash*2).to_s(16)} " + (exists? ? "url=#{url.inspect} title=#{title.inspect}" : "exists?=false") + '>'
     end
+    
+    # does the work of #screen_capture when the WinWindow library is being used for that. see #screen_capture documentation (browser-specific)
+    def screen_capture_win_window(filename, options = {})
+      options = handle_options(options, :dc => :window, :format => nil)
+      if options[:format] && !(options[:format].is_a?(String) && options[:format].downcase == 'bmp')
+        raise ArgumentError, ":format was specified as #{options[:format].inspect} but only 'bmp' is supported when :dc is #{options[:dc].inspect}"
+      end
+      if options[:dc] == :desktop
+        win_window.really_set_foreground!
+        screenshot_win=WinWindow.desktop_window
+        options[:dc] = :window
+      else
+        screenshot_win=win_window
+      end
+      screenshot_win.capture_to_bmp_file(filename, :dc => options[:dc])
+    end
+    private :screen_capture_win_window
   end
 
+  module WatirConfigCompatibility
+    if defined?($FAST_SPEED)
+      if config.warn_deprecated
+        Kernel.warn "WARNING: The $FAST_SPEED global is gone. Please use the new config framework, and unset that global to silence this warning."
+      end
+      Vapir.config.typing_interval=0
+      Vapir.config.type_keys=false
+    end
+    Speeds = {
+      :zippy => {
+        :typing_interval => 0,
+        :type_keys => false,
+      },
+      :fast => {
+        :typing_interval => 0,
+        :type_keys => true,
+      },
+      :slow => {
+        :typing_interval => 0.08,
+        :type_keys => true,
+      },
+    }.freeze
+    module WatirBrowserClassConfigCompatibility
+      OptionsKeys = [:speed, :attach_timeout, :visible]
+      def options
+        if self==Vapir::Browser
+          return browser_class.options
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #options is deprecated; please use the new config framework"
+        end
+        OptionsKeys.inject({}) do |hash, key|
+          respond_to?(key) ? hash.merge(key => self.send(key)) : hash
+        end.freeze
+      end
+      def set_options(options)
+        if self==Vapir::Browser
+          return browser_class.set_options(options)
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #set_options is deprecated; please use the new config framework"
+        end
+        
+        unless (unknown_options = options.keys - OptionsKeys.select{|key| respond_to?("#{key}=")}).empty?
+          raise ArgumentError, "unknown options: #{unknown_options.inspect}"
+        end
+        options.each do |key, value|
+          self.send("#{key}=", value)
+        end
+      end
+      def attach_timeout
+        if self==Vapir::Browser
+          return browser_class.attach_timeout
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #attach_timeout is deprecated; please use the new config framework with config.attach_timeout"
+        end
+        config.attach_timeout
+      end
+      def attach_timeout=(timeout)
+        if self==Vapir::Browser
+          return browser_class.attach_timeout=timeout
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #attach_timeout= is deprecated; please use the new config framework with config.attach_timeout="
+        end
+        config.attach_timeout = timeout
+      end
+    end
+    Vapir::Browser.send(:extend, WatirBrowserClassConfigCompatibility)
+    module Speed
+      def speed
+        if self==Vapir::Browser
+          return browser_class.speed
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #speed is deprecated; please use the new config framework with config.typing_interval and config.type_keys"
+        end
+        Speeds.keys.detect do |speed_key|
+          Speeds[speed_key].all? do |config_key, value|
+            config[config_key] == value
+          end
+        end || :other
+      end
+      def speed=(speed_key)
+        if self==Vapir::Browser
+          return browser_class.speed=speed_key
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #speed= is deprecated; please use the new config framework with config.typing_interval= and config.type_keys="
+        end
+        unless Speeds.key?(speed_key)
+          raise ArgumentError, "Invalid speed: #{speed_key}. expected #{Speeds.keys.map{|k| k.inspect }.join(', ')}"
+        end
+        Speeds[speed_key].each do |config_key, value|
+          config[config_key]=value
+        end
+      end
+      def set_slow_speed
+        if self==Vapir::Browser
+          return browser_class.set_slow_speed
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #set_slow_speed is deprecated; please use the new config framework with config.typing_interval= and config.type_keys="
+        end
+        self.speed= :slow
+      end
+      def set_fast_speed
+        if self==Vapir::Browser
+          return browser_class.set_fast_speed
+        end
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #set_fast_speed is deprecated; please use the new config framework with config.typing_interval= and config.type_keys="
+        end
+        self.speed= :fast
+      end
+    end
+    Vapir::Browser.send(:extend, Speed)
+    Vapir::Browser.send(:include, Speed)
+  end
 end
-
-require 'vapir-common/browsers'

data/lib/vapir-common/browsers.rb

@@ -1,9 +1,21 @@
-# vapir-common/browsers
-# Define browsers supported by Vapir
-
-Vapir::Browser.support :name => 'ie', :class => 'Vapir::IE', 
-  :library => 'vapir-ie', :gem => 'vapir-ie', 
-  :options => [:speed, :visible]
-
-Vapir::Browser.support :name => 'firefox', :class => 'Vapir::Firefox',
-  :library => 'vapir-firefox'
+module Vapir
+  SupportedBrowsers = {
+    :ie => {:class_name => 'Vapir::IE', :require => 'vapir-ie', :gem => 'vapir-ie'},
+    :firefox => {:class_name => 'Vapir::Firefox', :require => 'vapir-firefox', :gem => 'vapir-firefox'},
+  }
+  SupportedBrowsers.each do |key, browser_hash|
+    # set up autoload
+    split_class = browser_hash[:class_name].split('::')
+    class_namespace = split_class[0..-2].inject(Object) do |namespace, name_part|
+      namespace.const_get(name_part)
+    end
+    class_namespace.autoload(split_class.last, browser_hash[:require])
+    
+    # activate the right gem + version
+    begin
+      require 'rubygems'
+      gem browser_hash[:gem], "=#{Vapir::Common::VERSION}"
+    rescue LoadError
+    end
+  end
+end

data/lib/vapir-common/config.rb

@@ -0,0 +1,341 @@
+require 'vapir-common/handle_options'
+module Vapir
+  # represents a entry in a heirarchy of configuration options 
+  class Configuration
+    class Error < StandardError; end
+    class BadKeyError < Error; end
+    class NoValueError < Error; end
+    
+    # represents a valid option on a Configuration. consists of a key and criteria
+    # for which a value is valid for that key. 
+    class Option
+      attr_reader :key, :validator
+      # creates a new option. the options hash (last argument) may specify a 
+      # :validator key which will be used to validate any values attempted to be
+      # assigned to the key this option represents. 
+      def initialize(key, options={})
+        @key = key
+        options = handle_options(options, {}, [:validator])
+        @validator = options[:validator]
+      end
+      # takes a value and checks that it is valid, if a validator is specified for 
+      # this option. the validator may map the value to something different, so the
+      # result of this function call should replace the value being used. 
+      def validate!(value)
+        case @validator
+        when nil
+          value
+        when Proc
+          @validator.call value
+        when :boolean
+          case value
+          when 'true', true
+            true
+          when 'false', false
+            false
+          else
+            raise ArgumentError, "value should look like a boolean for key #{key}; instead got #{value.inspect}"
+          end
+        when :numeric
+          case value
+          when Numeric
+            value
+          when String
+            begin
+              Float(value)
+            rescue ArgumentError
+              raise ArgumentError, "value should look like a number for key #{key}; instead got #{value.inspect}"
+            end
+          else
+            raise ArgumentError, "value should look like a number for key #{key}; instead got #{value.inspect}"
+          end
+        else
+          raise ArgumentError, "invalid validator given: #{@validotor.inspect}\nvalidator should be nil for unspecified, a Proc, or a symbol indicating a known validator type"
+        end
+      end
+    end
+    
+    # the parent Configuration in the heirarchy. may be nil if there is no parent. 
+    attr_reader :parent
+    # creates a new Configuration with the given parent. if a block is given, this
+    # Configuration object will be yielded to it. 
+    def initialize(parent, &block)
+      unless parent==nil || parent.is_a?(Configuration)
+        raise TypeError, "expected parent to be a Configuration; got #{parent.inspect}"
+      end
+      @parent=parent
+      @config_hash = {}
+      @recognized_options = {}
+      yield(self) if block_given?
+    end
+    # if the method invoked looks like assignment (ends with an =), calls to #update with 
+    # the given method as the key and its argument as the value. otherwise calls #read with 
+    # the method as the key. 
+    def method_missing(method, *args)
+      method=method.to_s
+      if method =~ /\A([a-z_][a-z0-9_]*)([=?!])?\z/i
+        method = $1
+        special = $2
+      else # don't deal with any special character crap 
+        return super
+      end
+      case special
+      when nil
+        raise ArgumentError, "wrong number of arguments retrieving #{method} (#{args.size} for 0)" unless args.size==0
+        read(method)
+      when '='
+        raise ArgumentError, "wrong number of arguments setting #{method} (#{args.size} for 1)" unless args.size==1
+        update(method, *args)
+      #when '?' # no defined behavior for ? or ! at the moment
+      #when '!'
+      else
+        return super
+      end
+    end
+    # alias for #read
+    def [](key)
+      read(key)
+    end
+    # alias for #update 
+    def []=(key, value)
+      update(key, value)
+    end
+    # returns an array of 
+    def recognized_keys
+      ((@parent ? @parent.recognized_keys : [])+@recognized_options.keys).uniq
+    end
+    # returns true if the given key is recognized; false otherwise. may raise BadKeyError
+    # if the given key isn't even a valid format for a key. 
+    def recognized_key?(key)
+      key = validate_key_format!(key)
+      recognized_keys.include?(key)
+    end
+    # assert that the given key must be recognized; if it is not recognized, an error 
+    # should be raised. 
+    def recognize_key!(key)
+      key = validate_key_format!(key)
+      unless recognized_key?(key)
+        raise BadKeyError, "Unrecognized key: #{key}"
+      end
+      key
+    end
+    # returns true if the given key is defined on this Configuration; returns false if not - 
+    # note that this returns false if the given key is defined on an ancestor Configuration. 
+    def locally_defined_key?(key)
+      key = validate_key_format!(key)
+      @config_hash.key?(key)
+    end
+    # returns true if the given key is defined on this Configuration or any of its ancestors. 
+    def defined_key?(key)
+      locally_defined_key?(key) || (parent && parent.defined_key?(key))
+    end
+    # raises an error if the given key is not in an acceptable format. the key should be a string
+    # or symbol consisting of alphanumerics and underscorse, beginning with an alpha or underscore. 
+    def validate_key_format!(key)
+      unless key.is_a?(String) || key.is_a?(Symbol)
+        raise BadKeyError, "key should be a String or Symbol; got #{key.inspect} (#{key.class})"
+      end
+      key=key.to_s.downcase
+      unless key =~ /\A([a-z_][a-z0-9_]*)\z/
+        raise BadKeyError, "key should be all alphanumeric/underscores, not starting with a number"
+      end
+      key
+    end
+    protected
+    # returns a hash of recognized options with the keys being recognized keys and values 
+    # being Option instances. 
+    def recognized_options
+      (@parent ? @parent.recognized_options : {}).merge(@recognized_options)
+    end
+    public
+    # creates a new key. options are passed to Option.new; see its documentation. 
+    def create(key, options={})
+      key=validate_key_format!(key)
+      if recognized_key?(key)
+        raise "already created key #{key}"
+      end
+      @recognized_options[key]= Option.new(key, options)
+    end
+    # reads the value for the given key. if on value is defined, raises NoValueError. 
+    def read(key)
+      key = recognize_key! key
+      if @config_hash.key?(key)
+        @config_hash[key]
+      elsif @parent
+        @parent.read(key)
+      else
+        raise NoValueError, "There is no value defined for key #{key}"
+      end
+    end
+    # updates the given key with the given value. 
+    def update(key, value)
+      key = recognize_key! key
+      value = recognized_options[key].validate! value
+      @config_hash[key]=value
+    end
+    # creates a new key and updates it with the given value. options are passed to Option.new. 
+    def create_update(key, value, options={})
+      create(key, options)
+      update(key, value)
+    end
+    # takes a hash of key/value pairs and calls #update on each pair. 
+    def update_hash(hash)
+      hash.each do |k,v|
+        update(k,v)
+      end
+    end
+    # deletes the given value from the hash. this does not affect any ancestor Configurations. 
+    def delete(key)
+      key = check_key key
+      @config_hash.delete(key)
+    end
+    
+    # temporarily set the given keys of this configuration to the given values, yield to the block, 
+    # and restore to the original configuration before returning. 
+    def with_config(hash, &block)
+      begin
+        orig_config_hash = @config_hash.dup
+        update_hash hash
+        return yield
+      ensure
+        @config_hash = orig_config_hash
+      end
+    end
+  end
+  # module to be included in anything that should have a #config method representing a Configuration. 
+  module Configurable
+    # the parent for the Configuration returned from #config 
+    attr_accessor :configuration_parent
+    # returns a Configuration object 
+    def config
+      @configuration ||= Configuration.new(configuration_parent)
+    end
+    # see Configuration#with_config
+    def with_config(hash, &block)
+      @configuration.with_config(hash, &block)
+    end
+    private
+    # takes a hash of given options, a map of config keys, and a list of other allowed keys. 
+    #
+    # the keymap is keyed with keys of the options hash and its values are keys of the Configuration
+    # returned from #config. 
+    #
+    # other allowed keys limit what keys are recognized in the given options hash, and ArgumentError
+    # is raised if unrecognized keys are present (this is done by #handle_options; see that method's
+    # documentation). 
+    # 
+    # returns a hash in which any defined config keys in the keymap which are not already 
+    # defined in the given options are set to their config value. 
+    def options_from_config(given_options, keymap, other_allowed_keys = [])
+      config_options = (keymap.keys - given_options.keys).inject({}) do |opts, key|
+        if given_options.key?(key)
+          opts
+        elsif config.defined_key?(keymap[key])
+          opts.merge(key => config[keymap[key]])
+        else
+          opts
+        end
+      end
+      handle_options(given_options, config_options, other_allowed_keys + keymap.keys)
+    end
+  end
+  
+  class HashConfigurationWithOtherStuff < Configuration
+    attr_accessor :key_prefix
+    def unprefixed_recognized_key(prefixed_key)
+      key_prefix=self.key_prefix || ''
+      if prefixed_key.is_a?(String) || prefixed_key.is_a?(Symbol)
+        prefixed_key=prefixed_key.to_s
+        if prefixed_key[0...key_prefix.length].downcase==key_prefix.downcase
+          key=prefixed_key[key_prefix.length..-1]
+          if recognized_key?(key)
+            return key
+          end
+        end
+      end
+      return nil
+    end
+    def update_from_source
+      config_hash.each do |hash_key, value|
+        if key=unprefixed_recognized_key(hash_key)
+          update(key, value)
+        end
+      end
+    end
+  end
+  class YamlConfiguration < HashConfigurationWithOtherStuff
+    attr_reader :yaml_file
+    def initialize(parent, yaml_file)
+      super(parent)
+      @yaml_file=yaml_file
+      update_from_source
+    end
+    def config_hash
+      if yaml_file && File.exists?(yaml_file)
+        require 'yaml'
+        @loaded_yaml ||= YAML.load_file(yaml_file) # don't want to reload this every time #update_from_source is called 
+        if @loaded_yaml.is_a?(Hash)
+          @loaded_yaml
+        elsif @loaded_yaml == false || @loaded_yaml == nil
+          {}
+        else
+          raise ArgumentError, "Attempted to load Vapir configuration from the YAML file at #{yaml_file.inspect}, but its contents parsed as a #{@loaded_yaml.class}; expected a hash.\nYAML.load_file(#{yaml_file.inspect}) = #{@loaded_yaml.inspect}"
+        end
+      else
+        {}
+      end
+    end
+  end
+
+  @configurations = []
+  def (@configurations).update_from_source
+    self.each do |c|
+      if c.respond_to?(:update_from_source)
+        c.update_from_source 
+      end
+    end
+  end
+
+  @configurations.push(@base_configuration=Configuration.new(nil) do |config|
+    config.create_update(:attach_timeout, 30, :validator => :numeric)
+    config.create(:default_browser, :validator => proc do |val|
+      require 'vapir-common/browsers'
+      unless (val.is_a?(String) || val.is_a?(Symbol)) && (real_key = Vapir::SupportedBrowsers.keys.detect{|key| key.to_s==val.to_s })
+        raise ArgumentError, "default_browser should be a string or symbol matching a supported browser - one of: #{Vapir::SupportedBrowsers.keys.join(', ')}. instead got #{value.inspect}"
+      end
+      real_key
+    end)
+    config.create_update(:highlight_color, 'yellow')
+    config.create_update(:wait, true, :validator => :boolean)
+    config.create_update(:type_keys, false, :validator => :boolean)
+    config.create_update(:typing_interval, 0, :validator => :numeric)
+    config.create_update(:warn_deprecated, true, :validator => :boolean)
+  end)
+  
+  # adapted from rubygems.rb
+  home_dir = ENV['HOME'] || ENV['USERPROFILE'] || (ENV['HOMEDRIVE'] && ENV['HOMEPATH'] && "#{ENV['HOMEDRIVE']}:#{ENV['HOMEPATH']}") || begin
+    File.expand_path("~")
+  rescue
+    if File::ALT_SEPARATOR
+      "C:/"
+    else
+      "/"
+    end
+  end
+  
+  @configurations.push(@home_yaml_configuration = YamlConfiguration.new(@configurations.last, File.join(home_dir, '.vapir_config.yaml')))
+  @configurations.push(@pwd_yaml_configuration = YamlConfiguration.new(@configurations.last, File.join(Dir.pwd, 'vapir_config.yaml')))
+  
+  env_config_yaml = (env_yaml_key = ENV.keys.detect{|key| key.downcase == 'vapir_config_yaml' }) && ENV[env_yaml_key]
+  env_config_yaml_file = env_config_yaml && (File.directory?(env_config_yaml) ? File.join(env_config_yaml, 'vapir_config.yaml') : env_config_yaml)
+  @configurations.push(@env_yaml_configuration = YamlConfiguration.new(@configurations.last, env_config_yaml_file))
+  @configurations.push(@env_configuration = HashConfigurationWithOtherStuff.new(@configurations.last))
+  @env_configuration.key_prefix='vapir_'
+  def (@env_configuration).config_hash
+    ENV
+  end
+  @env_configuration.update_from_source
+  
+  @configuration_parent = @configurations.last
+  extend Configurable # makes Vapir.config which is the in-process user-configurable one, overriding base, yaml, and env 
+end