#--
# Copyright (c) 2006 Jeff Barczewski and Deborah Lewis
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#++
#
# == MasterView Configuration and Initialization
# 
# The MasterView template engine supports a number of configuration settings
# which allow a client to easily customize its operation.
#
# A MasterView::Configuration specification is used to allow the application to 
# specify custom configuration options during application startup.  The configuration options
# are installed in MasterView when its Initializer is run, which handles
# loading and configuring MasterView for operation.
#  
#--
# This style of configuration specification + initializer follows the technique 
# used by Rails itself. A configuration specification can be customized by the 
# application in its startup and is used by the Initialzer to configure
# the MasterView template engine implementation at load time.
# [D. Lewis 31-May-2006]
#++
#
#--
# todo - change configuration to accomodate non-file based storage, use MIOTree objects
# [JJB 13-Jun-2006]
#++
#
module MasterView

  # A Configuration holds all the configuration settings used the 
  # MasterView::Initializer to configure the template engine.
  # 
  # Configuration provides defaults that suit most Rails applications. 
  # You can change the default settings in the configuration to customize 
  # MasterView with options suitable for your application.
  # 
  # In the most common usage pattern, a Configuration instance initialized 
  # with the standard default settings is created implicitly when the 
  # Initializer is run, which happens automatically
  # when Masterview is installed as a plugin in a Rails application.
  # Application-specific settings are then loaded from the application's
  # +config+ directory and used by the Initializer to configure
  # the MasterView template engine for operation.
  # 
  # When using MasterView in a standalone application (i.e., not within rails),
  # it is also possible to create the Configuration instance in advance and 
  # pass it in explicitly to the Initializer.  This technique can be useful
  # when it is necessary to establish the application root directory location
  # that MasterView uses during its operation or to specify to location of the
  # application's configuration files.
  #
  #   require 'masterview/initializer'
  #   config = MasterView::Configuration.new( :app_root_path => '/path/to/my/app' )
  #   config.template_src_dir_path = "masterview/templates"
  #   config.template_dst_dir_path = "masterview/output"
  #   #...set other config options...
  #   MasterView::Initializer.run( :process, config )
  #
  class Configuration

    # directory in which the MasterView plugin or gem is installed
    attr_reader :mv_installation_dir #:nodoc:

    # root directory of MasterView itself and the built-in directives
    # This is lib/masterview w/in the plugin or gem installation directory.
    attr_reader :mv_code_base_dir #:nodoc:

    # root directory when operating context is a rails app
    attr_reader :rails_root_path #:nodoc:

    # directory in a rails app for views (RAILS_ROOT/app/views)
    attr_reader :rails_views_dir_path #:nodoc:

    # RE spec for scripts which are used to launch rails
    attr_accessor :rails_runner_scripts_pattern #:nodoc:

    # is RAILS_ROOT defined?
    attr_reader :has_rails_context #:nodoc:

    # is the root a rails app?
    def rails_app? #:nodoc:
      @rails_root_path != nil
    end

    # Set to indicate that we're actually running the rails app (server or console...)
    attr_accessor :running_rails #:nodoc:

    # are we actually running rails when our root is a rails app?
    def on_rails? #:nodoc:
      @running_rails
    end

    # === General Options

    # Path to the root location for the application.
    # Used for resolving relative references.
    # 
    # For a rails application, this is +RAILS_ROOT+.
    # 
    attr_accessor :root_path

    # Path to the directory containing the application's MasterView 
    # configuration settings files (if any).  If no configuration
    # directory or settings files are defined, MasterView runs
    # with the standard default configuration options.
    # 
    # Specified as a relative path from the application's +root_path+.
    # 
    # Default: for a Rails application, this is <tt>RAILS_ROOT/config/masterview</tt>.
    # 
    attr_accessor :config_dir_path
    # Specify the directory where masterview templates are located 
    # as a relative path from the application's +root_path+.
    def config_dir_path= rel_path #:nodoc:
      # bolts down abs path, thanks to our firm roots
      @config_dir_path = rel_path.nil? ? nil : ( rel_path.empty? ? root_path : File.join( root_path, rel_path ))
    end

    # The current execution environment, if applicable 
    # (e.g., 'development', 'test', 'production').
    # 
    # Used for loading application settings from config directory, if available.
    # 
    # For a Rails application, this is +RAILS_ENV+.
    # 
    attr_accessor :environment

    # Paths of directories to load directives from.
    # 
    # The directory containing the built-in MasterView directives 
    # is installed by default. If the application provides
    # a <tt>masterview/directives</tt> directory in its +root_path+,
    # that directory is also automatically added to the directives
    # load path.
    # 
    # Append additional path(s) to load custom directives from specific
    # locations.
    attr_accessor :directive_paths

    # Relative path from +root_path+ of the temp directory used for creating 
    # backup files before rebuilding/updating a template file.
    # 
    # Set to nil to suppress backups.
    # 
    # Default: <tt>RAILS_ROOT/tmp/masterview/rebuild/backups</tt>
    #--
    # ISSUE: change this to use IOMgr mapping, how best to do this config??
    # Leave existing mechanism here, but drop out of documentation and examples
    # until resolved
    #++
    attr_accessor :rebuild_backups_tmp_dir_path #:nodoc: 

    # Logger which will be used to record debug, warning, and error messages.
    # 
    # Supported loggers:
    #   'log4r' - the Log4r logging library
    #   'logger' - Logger in the ruby standard class library
    # 
    # Default: uses <code>Log4r</code> if available, otherwise a standard ruby +Logger+.
    attr_accessor :logger

    # Logging severity threshold for the logger.
    # 
    # Specify the name of the logging level to use with the configured logger.
    # Standard logging levels in both Log4r and ruby Logger are
    # +DEBUG+, +INFO+, +WARN+, +ERROR+, +FATAL+.
    # Other level names depend on the configured logger.
    # 
    # Default: +INFO+ for development, +WARN+ otherwise
    attr_accessor :log_level

    # Sets a block which will be executed after MasterView has been fully initialized.
    # Useful for per-environment configuration which depends on the plugin being 
    # fully initialized.
    def after_initialize(&after_initialize_block)
      @after_initialize_block = after_initialize_block
    end
    
    # Returns the block set in Configuration#after_initialize
    def after_initialize_block
      @after_initialize_block
    end

    # === Template Source Options

    # Path to the directory where masterview templates are located.
    # 
    # Assign the value as a relative path from the application's +root_path+
    # or use the +template_src_dir_abs_path+ method to specify an absolute path.
    # 
    # Default: <tt>RAILS_ROOT/app/views</tt> for a rails application
    # or <tt>{root_path}/masterview/templates</tt> for a non-rails application.
    attr_accessor :template_src_dir_path
    # Specify the directory where masterview templates are located 
    # as a relative path from the application's +root_path+.
    def template_src_dir_path= rel_path  #:nodoc:
      # bolts down abs path, thanks to our firm roots
      @template_src_dir_path = rel_path.nil? ? nil : ( rel_path.empty? ? root_path : File.join( root_path, rel_path ))
    end
    # Specify the absolute path to the directory where masterview templates are located.
    def template_src_dir_abs_path(abs_path)
      @template_src_dir_path = abs_path
    end

    # Filename pattern for masterview template files
    # within the template source directory.
    # 
    # Default: <tt>'*.html'</tt>
    attr_accessor :template_filename_pattern

    # === Template Generation Options

    # Path to the directory where Masterview template output (rhtml)
    # will be generated.
    # 
    # Assign the value as a relative path from the application's +root_path+
    # or use the +template_dst_dir_abs_path+ method to specify an absolute path.
    # 
    # Default: <tt>RAILS_ROOT/app/views</tt>
    attr_accessor :template_dst_dir_path
    # Specify the directory where masterview template output is generated 
    # as a relative path from the application's +root_path+.
    def template_dst_dir_path= rel_path  #:nodoc:
      # bolts down abs path, thanks to our firm roots
      @template_dst_dir_path = rel_path.nil? ? nil : ( rel_path.empty? ? root_path : File.join( root_path, rel_path ))
    end
    # Specify the absolute path to the directory where masterview template output is generated.
    def template_dst_dir_abs_path(abs_path)
      @template_dst_dir_path = abs_path
    end

    # Filename extension to use for generated output files if not 
    # explicitly specified in the +mv:generate+ attribute value.
    # 
    # Default: <tt>'.rhtml'</tt>
    attr_accessor :output_filename_extension

    # Filename extension to use for generated files if not explicitly specified.
    # 
    # Default: <tt>'.rhtml'</tt>
    attr_accessor :generated_file_default_extension  #FIXME

    # Boolean which controls whether to include a comment in template
    # output files indicating that the file was generated by MasterView.
    # 
    # By default, a warning comment is generated in template output files
    # indicating that the file was generated by MasterView from a template
    # and should not be directly edited, as any changes would be lost when the
    # output file is regenerated.
    # 
    # Default: +true+
    attr_accessor :include_generated_file_comment

    # Text for generated-file comment inserted in rhtml template output files 
    # generated by MasterView.
    # 
    # Standard comment includes the name of the master template file which contains
    # the source to edit.
    # 
    # Variable substitution on the comment text will replace a reference
    # to <tt>{template_path}</tt> with the pathname of the source template file.
    # 
    attr_accessor :generated_file_comment

    # === Template Parsing Options

    # Specify whether MasterView should handle exceptions when 
    # parsing template files.
    # 
    # Exceptions that occur during template parsing are always 
    # recorded in the debug log.  These are generally problems
    # caused by invalid (x)html in the template.
    # 
    # Set to +true+ to have the template parser catch exceptions and
    # continue processing after logging a problem report.
    # 
    # Set to +false+ to have exceptions raised to the application.
    # 
    # Default: +true+
    # 
    attr_accessor :handle_parse_exceptions

    # Default option settings for template parsing (a hash)
    #   :tidy => false - run tidy before parsing (tidy_path must be set if enabled)
    #   :escape_erb => true - escapes <% %> before parsing
    attr_accessor :default_parser_options

    # Path on this system to tidy library if <tt>:tidy</tt> parser option is enabled
    # so that masterview templates will be run through tidy before being parsed.
    # Allows invalid xhmtl to be corrected before masterview template parsing is performed.
    attr_accessor :tidy_path

    # XML name space prefix for MasterView directive attributes in template html.
    # e.g. mv:generate="target.rhtml".
    # 
    # Default: <tt>'mv:'</tt>
    attr_accessor :namespace_prefix

    # Xhtml-safe substitution for '<%' in a masterview template
    # NOTE: you must also update inline_erb_substitution_regex if this is changed.
    # 
    # Default: <tt>'{{{'</tt>
    attr_accessor :inline_erb_start

    # Xhtml safe substitution for '%>'in a masterview template
    # NOTE: you must also update inline_erb_substitution_regex if this is changed.
    # 
    # Default: <tt>'}}}'</tt>
    attr_accessor :inline_erb_end

    # regex used to find escaped inline_erb markup.
    # Needs to match +inline_erb_start+ and +inline_erb_end+.
    attr_accessor :inline_erb_substitution_regex

    # === Rails Application Options

    # Boolean which specifies whether masterview templates are parsed 
    # during initial application startup loading.
    # 
    # Set to +false+ to disable all load-time parsing.
    # Template parsing must be manually triggered when the auto-parse option is disabled.
    # 
    # Default: +true+
    attr_accessor :parse_masterview_templates_at_startup

    # Boolean which determines whether masterview templates are automatically
    # reparsed if the template changes after initial application loading.
    # 
    # Set to +true+ to monitor masterview templates for file system changes
    # during Rails request dispatching.
    # 
    # Set to +false+ to disable changed-template monitoring.
    # Template parsing must be manually triggered when the auto-parse option is disabled.
    # 
    # This option is only supported when running as part of a Rails application.
    # It is enabled by default in the standard Rails development configuration
    # (+parse_masterview_templates_at_startup+ is enabled and
    # ActionController::Base.perform_caching is false so that changed classes 
    # are dynamically reloaded during request dispatching).
    # 
    # Automatic change-detection and reparsing of masterview templates is disabled
    # by default in the usual Rails configuration for production mode
    # (ActionController::Base.perform_caching is on to enable loaded class caching).
    # 
    # Default: +true+ if parse_masterview_templates_at_startup is enabled 
    # and ActionController is reloading changed classes (no caching)
    attr_accessor :reparse_changed_masterview_templates

    # Enable MasterView admin pages in the rails application.
    # 
    # Enables the masterview admin controller at <tt>http://yourappdomain/masterview</tt>.
    # 
    # Default: +false+
    attr_accessor :enable_admin_pages

    # Enable MasterView admin view rhtml feature
    # 
    # If MasterView admin pages are enabled, then you may set this feature to true and it 
    # will allow you to get to the generated rhtml from the MasterView admin page which is
    # especially useful for debugging or understanding how MasterView is interpretting the
    # your templates. When enabled you may click on any of the generated rhtml parts from 
    # the list view and it will show you the rhtml that is generated. For security purposes
    # you will probably want this to disable this feature in production (or even better 
    # disable admin pages itself). Alternatively there is a rake task called mv:view_rhtml
    # which allows you to see the rhtml from the command line (regardless of this setting).
    #
    # Default +false+
    attr_accessor :enable_view_rhtml

    # Generate rhtml files if true, rails will load them from there. Otherwise when this 
    # setting is false, enable rails app to read rhtml(erb) directly from MasterView cache 
    # bypassing the serialization to the file system.
    # Default: +false+
    attr_accessor :generate_rhtml_files

    # Create a new Configuration instance, initialized with the default
    # values.
    # 
    # Optional arguments to the constructor allow for initializing defaults
    # for a rails app when not actually running rails or for initializing
    # defaults for a standalone app with context anchored at some well-defined
    # point in space (other than where we're actually running).
    # 
    #   :app_root_path => path to the root directory of the application
    #   :rails_app_root_path => path to the root directory of a Rails app
    #   :environment => current environment for loading settings
    # 
    # The +app_root_path+ and +rails_app_root_path+ arguments are mutually exclusive.
    # Use +rails_app_root_path+ when operating on a Rails application which
    # isn't actually running; use +app_root_path+ for a non-rails application.
    # 
    def initialize( params={} )

      # unpack the supported keyword args
      app_root_path = params[:app_root_path]
      rails_app_root_path = params[:rails_app_root_path]
      env = params[:environment]

      program_root_path = File.expand_path( '.' )
      #assert program_root_path == Dir.pwd

      debug_TRACE_HACK = false  #temp dev debug tracking for rails vs. non-rails init

      @mv_code_base_dir = File.expand_path( File.dirname(__FILE__) )
      builtin_directives_path = File.join( mv_code_base_dir, 'directives')
      @mv_installation_dir = File.expand_path( "#{File.dirname(__FILE__)}/../.." )

      #ISSUE: should probably also detect std console or breakpointer launch scripts [DJL 10-Jun-2006]
      @rails_runner_scripts_pattern = /server|dispatch/

      @has_rails_context = (defined?(::RAILS_ROOT) != nil)
      decide_if_running_rails

      # only run if auto parsing and when launching server, check if need to update mv files
      # MasterView::ParseMasterViewTemplatesAtStartup
      #ISSUE: what about console and breakpointer scripts?

      if debug_TRACE_HACK
        STDOUT.puts "\n####Initializing MasterView config (default settings)"
        STDOUT.puts "...RAILS_ROOT=#{defined?(::RAILS_ROOT) ? ::RAILS_ROOT : '(undefined)'}"
        STDOUT.puts "...has_rails_context=#{has_rails_context.nil? ? 'nil' : has_rails_context}"
      end

      # establish the fundamental roots for anchoring relative references
      # Scenarios: running a rails app, operating on a rails app but not running it, standalone
      #assert at most one of the two args is supplied, they're mutually exclusive
      if has_rails_context
        @rails_root_path = File.expand_path( ::RAILS_ROOT )
      elsif rails_app_root_path
        @rails_root_path = File.expand_path( rails_app_root_path )
      elsif app_root_path.nil? && looks_like_rails_app?
        # if client hasn't specifically provided an app or rails root anchor parm
        # and we aren't actually launching rails, sniff around and make a good guess
        # at whether this app has the rails structure so we can set proper defaults
        # (e.g., running rake tasks on a rails app)
        # ISSUE: Is this just too clever?  Maybe the rakefile should establish this?
        # [DJL 15-Ajun-2006]
        @rails_root_path = program_root_path
      else
        @rails_root_path = nil
      end
      @rails_views_dir_path = rails_app? ? File.join( rails_root_path, 'app/views' ) : nil
      #if on_rails?
      #  #ISSUE: ActionController::Base.template_root vs. ActionController::Base.view_root???? significant diff??
      #  #assert rails_views_path ==ActionController::Base.template_root
      #end

      if debug_TRACE_HACK
        STDOUT.puts "...rails_app?=#{rails_app? ? 'yes' : 'nope'}"
        STDOUT.puts "...on_rails?=#{on_rails? ? 'yes' : 'nope'}"
      end
      if debug_TRACE_HACK and rails_app?
        STDOUT.puts "...rails_root_path=#{self.rails_root_path}"
        STDOUT.puts "...rails_views_dir_path=#{rails_views_dir_path}"
      end

      # general options - establish the roots to anchor MV in an operating context
      if rails_app?
        self.root_path = self.rails_root_path
      elsif app_root_path
        self.root_path = File.expand_path( app_root_path )
      else
        #ISSUE: add hook here to check for MASTERVIEW_ROOT_PATH or ENV[xxx]???
        self.root_path = program_root_path
      end
      # For a rails app, we have a point of view on where to find config files.
      # A standalone client needs to proactively tell us where to find their settings. 
      self.config_dir_path = rails_app? ? "config/masterview" : nil
      self.environment = on_rails? ? ::RAILS_ENV : env
      self.directive_paths = [ builtin_directives_path ]

      #TODO: if rails_app? && File.exist?( "#{rails_root_path}/app/masterview/directives" ) THEN append it as well
      self.rebuild_backups_tmp_dir_path = rails_app? ? File.join( rails_root_path, 'tmp/masterview/rebuild/backups') : nil 
      # use Log4r by default if available, otherwise Logger from standard ruby library
      # find out if Kernel#require will succeed if we try to load Log4R
      log4r_dir = $:.detect { |dir| File.exists?("#{dir}/log4r.rb") }  #? path_contains? predicate somewhere??
      self.logger = log4r_dir ? 'log4r' : 'logger'
      #self.log_level = nil  # use the default level of the logger
      self.log_level = (self.environment == 'development') ? 'INFO' : 'WARN'

      if debug_TRACE_HACK
        STDOUT.puts "...root_path=#{root_path}"
        STDOUT.puts "...config_dir_path=#{config_dir_path || 'nil'}"
        STDOUT.puts "...environment=#{environment || 'nil'}"
        STDOUT.puts "...directive_paths=[ #{directive_paths.join(', ')} ]"
      end

      # template source options
      self.template_src_dir_path = rails_app? ? 'app/views' : 'masterview/templates'  # bolts down abs ref
      self.template_filename_pattern = '*.html'

      STDOUT.puts "...template_src_dir_path=#{template_src_dir_path || 'nil'}" if debug_TRACE_HACK

      # template generation options
      self.template_dst_dir_path = rails_app? ? 'app/views' : 'masterview/output'  # bolts down abs ref
      self.output_filename_extension = '.rhtml'
      self.generated_file_default_extension = '.rhtml'
      self.include_generated_file_comment = true
      self.generated_file_comment = <<-END
#    WARNING - This is a generated file created by MasterView. 
#    Do not edit - changes will be lost when this file is re-generated.
# 
#    To make changes, edit the MasterView source file located at: 
  END
      self.generated_file_comment << '#    #{template_path}'  # carefully avoid premature subst eval

      STDOUT.puts "...template_dst_dir_path=#{template_dst_dir_path || 'nil'}" if debug_TRACE_HACK

      # template parsing options
      self.handle_parse_exceptions = true
      self.default_parser_options = { :tidy => false, :escape_erb => true }
      # default locations where tidy likely to be found; assume on user's PATH if on Windows
      self.tidy_path = RUBY_PLATFORM =~ /mswin32/ ? 'tidy.exe' : '/usr/lib/libtidy.so'
      self.namespace_prefix = 'mv:'
      self.inline_erb_start = '{{{'
      self.inline_erb_end = '}}}'
      self.inline_erb_substitution_regex = /\{\{\{(([^}]|\}[^}]|\}\}[^}])*)\}\}\}/

      # Rails application options
      self.parse_masterview_templates_at_startup = true
      self.reparse_changed_masterview_templates = on_rails? ? (not ActionController::Base.perform_caching) : false
      self.enable_admin_pages = false
      self.enable_view_rhtml = false
      self.generate_rhtml_files = false
 
      STDOUT.puts "...mv config initialized with default settings\n" if debug_TRACE_HACK

    end

    def decide_if_running_rails #:nodoc:
      @running_rails = has_rails_context && ($PROGRAM_NAME =~ rails_runner_scripts_pattern) != nil
    end

    # see if this app has the std file structure that indicates a rails application
    def looks_like_rails_app? #:nodoc:
      std_rails_directories = [ 'app', 'config', 'public' ]  
      std_rails_directories.each { | dir_path |
        return if ! File.directory?(dir_path)
      }
      true
    end

    # The path to the application's config settings file.
    # By default the file is at <tt>config/masterview/settings.rb</tt>.
    def app_settings_path
      config_dir_path ? "#{config_dir_path}/settings.rb" : nil
    end

    # The path to the current environment's settings file (development.rb, etc.). 
    # By default the file is at <tt>config/masterview/environments/{environment}.rb</tt>.
    def environment_settings_path
      (config_dir_path && environment) ? "#{config_dir_path}/environments/#{environment}.rb" : nil
    end

  end

  # The Initializer is responsible for processing the MasterView configuration.
  # 
  # In a Rails application using the MasterView facilities,
  # the Initializer is run automatically during rails startup
  # when the plugin is loaded.  No special action is required
  # by the application.
  #
  # To customize the MasterView configuration, provide config settings files
  # in your application's config directory, setting standard settings
  # in <tt>config/masterview/settings.rb</tt> and optionally setting
  # environment-specific values in <tt>config/masterview/environments/{environment}.rb</tt>.
  # The settings files are executed with the +config+ variable initialized to
  # the current configuration.  This is the standard technique for a Rails application.
  # 
  # An application using the MasterView facilities outside the Rails context 
  # must run the MasterView::Initializer during its application startup.
  # 
  # It can be run as a simple command that uses the default configuration:
  #
  #   require 'masterview/initializer'
  #   MasterView::Initializer.run
  #
  # or more simply just load MasterView:
  # 
  #   require 'masterview'
  #
  # In order to customize the MasterView configuration outside the Rails context, 
  # you must explicitly provide a basic Configuration to the Initializer
  # which specifies the root location of the application and the paths
  # to the template directories if the default locations are not appropriate.
  # Configuration settings can be set directly or provided through config
  # settings file by specifying the +config_dir_path+ to the application's
  # setttings files.
  #
  #   require 'masterview/initializer'
  #   config = MasterView::Configuration( :app_root_path = '/path/to/my/app' )
  #   config.environment = 'production'
  #   config.config_dir_path = 'masterview/config'
  #   #... additional settings will be loaded from the config dir...
  #   Masterview::Initializer( :process, config )
  #
  class Initializer

    # The Configuration instance used by this Initializer instance.
    attr_reader :configuration

    # Runs the initializer. By default, this will invoke the #process method,
    # which simply executes all of the initialization routines. Alternately,
    # you can specify explicitly which initialization routine you want:
    #
    #   MasterView::Initializer.run(:initialize_configuration)
    #
    # This is useful if you only want the config settings initialized, without
    # incurring the overhead of completely loading the entire component. 
    #
    def self.run(command = :process, configuration = Configuration.new)
      if block_given?
        yield configuration
      end
      initializer = new(configuration)
      initializer.send(command)
      initializer
    end
    
    # Create a new Initializer instance that references the given Configuration
    # instance.
    def initialize(configuration) #:nodoc:
      @configuration = configuration
    end

    # Load the MasterView configuration settings
    # and initialize the template engine.
    def process
      initialize_configuration
      load_plugin
      complete_plugin_installation
    end

    # Load the Masterview configuration settings.
    # Does *not* load and configure the template engine.
    # 
    # Intended for use in testing.
    def initialize_configuration
      #?? return if MasterView.const_defined?(:ConfigSettings) ??
      load_config_settings
      ensure_valid_settings
      discover_standard_directive_path_additions
      install_config_settings
      # make a final check for running_rails? (in case config settings changed scripts spec)
      configuration.decide_if_running_rails
      # keep a permananent record of how we got started
      configuration.freeze
      configuration.directive_paths.freeze
      MasterView.const_set('ConfigSettings', configuration)
    end

    # Load configuration settings from <tt>{config.config_dir_path}/settings.rb</tt> 
    # and <tt>{config.config_dir_path}/environments/{config.environment}.rb</tt>.
    def load_config_settings #:nodoc:
      load_app_settings
      load_environment_settings
    end

    # Loads application config settings.
    def load_app_settings #:nodoc:
      load_settings_file(configuration.app_settings_path)
    end

    # Loads config settings for the environment specified by 
    # Configuration#environment_path, which
    # is typically one of development, testing, or production.
    def load_environment_settings #:nodoc:
      load_settings_file(configuration.environment_settings_path)
    end

    # Loads MasterView config settings from the specified config file.
    def load_settings_file(config_file_path) #:nodoc:
      return if not (config_file_path && File.file?(config_file_path))
      config = configuration  # define config var in the binding context of the settings eval
      eval(IO.read(config_file_path), binding)
    end

    def discover_standard_directive_path_additions #:nodoc:
      #TODO: check for config/masterview/directives and automatically
      # append to the configuration.directive_paths if found.
      # We have to wait until all the config settings are loaded so that
      # all references to root locations and client's own prefs for
      # locating directives.
      # [DJL 01-Jun-2006]
      #... something like:
      #return if not config_dir_path
      #config_directives_path = File.join(configuration.config_dir_path, 'directives')
      #if File.directory?(config_directives_path)
      # configuration.directivePaths << File.expand_path(config_directives_path unless it's already there
      #end
    end

    # ensure that the requested configuration settings are consistent and valid
    # before we actually install anything.  Normalize representations as needed.
    def ensure_valid_settings #:nodoc:

      config = configuration

      #??config.root_path = File.expand_path(config.root_path) if config.root_path  #?? ensure bolted down firmly?


      ####if config.directive_paths.length > 1 then expand_path on user-appended entries??

      # template source and generation options
      if config.on_rails?
        #TODO: ensure that the config.template_dst_dir_path is
        # in the RAILS_ROOT/app/views directory
        # (ActionController::Base.view_root)
        # Otherwise all the fine rails view template stuff doesn't work
      end

      # Rails application options
      if config.on_rails?
        # ensure we don't activate runtime reparsing if we didn't autoparse at startup 
        # (?overzealous?  But this what we're currently asserting as the intended behavior in the docs)
        if not config.parse_masterview_templates_at_startup
          config.reparse_changed_masterview_templates = false
        end
      #else
      #  self.reparse_changed_masterview_templates = false  # not supported
      end

    end

    # Install the configuration settings
    def install_config_settings #:nodoc:
      set_module_constants
    end

    def set_module_constants #:nodoc:

      config = configuration

      # we don't record root_path or config_dir_path - their purpose is satisfied
      # by the time we're done processing this installation configuration

      MasterView.const_set('DefaultDirectiveLoadPaths', config.directive_paths.clone)  # clone before freezing

      # template source options
      MasterView.const_set('TemplateFilenamePattern', config.template_filename_pattern)

      # template generation options
      MasterView.const_set('OutputExtension', config.output_filename_extension)  ###??IS THIS NEEDED???
      MasterView.const_set('OmitGeneratedComments', (not config.include_generated_file_comment))
      MasterView.const_set('GeneratedCommentText', config.generated_file_comment)

      # template parsing options
      MasterView.const_set('RescueExceptions', config.handle_parse_exceptions)
      MasterView.const_set('DefaultParserOptions', config.default_parser_options)
      MasterView.const_set('TidyPath', config.tidy_path)
      MasterView.const_set('NamespacePrefix', config.namespace_prefix)
      MasterView.const_set('InlineErbStart', config.inline_erb_start)
      MasterView.const_set('InlineErbEnd', config.inline_erb_end)
      MasterView.const_set('InlineErbSubstitutionRegex', config.inline_erb_substitution_regex)

      # Rails application options
      MasterView.const_set('ParseMasterViewTemplatesAtStartup', config.parse_masterview_templates_at_startup)
      MasterView.const_set('ReparseChangedMasterViewTemplates', config.reparse_changed_masterview_templates)
      MasterView.const_set('EnableMasterViewAdminPages', config.enable_admin_pages)
      MasterView.const_set('EnableMasterViewAdminViewRHTML', config.enable_view_rhtml)

      # convenience constants for MV attributes involving output generation and imports
      MasterView.const_set('GenerateAttribute', config.namespace_prefix + 'generate')
      MasterView.const_set('ImportAttribute', config.namespace_prefix + 'import')
      MasterView.const_set('GenRenderAttribute', config.namespace_prefix + 'gen_partial')
      MasterView.const_set('ImportRenderAttribute', config.namespace_prefix + 'import_render')

    end

    # Load the masterview code
    def load_plugin #:nodoc:
      require 'masterview' #:nodoc:
    end

    # Complete installation of masterview after its code has been loaded
    def complete_plugin_installation #:nodoc:
      #?? return if MasterView.const_defined?(:Initialized) ??
      initialize_mio
      initialize_logger
      install_in_rails
      # mark the module as fully loaded and configured
      MasterView.const_set('Initialized', true)
      after_initialize  # callback to client's afer_initialize block
    end

    # Initialize the MasterView I/O subsystem
    def initialize_mio
      config = configuration
      MasterView.const_set('DefaultSerializer', MIOSerializer)
      # all root_path directory anchor points for I/O are expanded absolute paths
      io_mgr = MIOTrees.new
      template_extension = File.extname( config.template_filename_pattern )
      io_mgr.template = FileMIOTree.new( config.template_src_dir_path, template_extension, 
                          :escape_erb => config.default_parser_options[:escape_erb], 
                          :tidy => config.default_parser_options[:tidy], 
                          #TODO: expose the following in Configuration.default_parser_options and document
                          :caching => false, 
                          :logging => true )
      if config.generate_rhtml_files
        io_mgr.erb = FileMIOTree.new( config.template_dst_dir_path, config.generated_file_default_extension, :logging => true)
      else
        io_mgr.erb = RailsErbCacheMIOTree.new( config.generated_file_default_extension, :logging => true)
      end
      io_mgr.backup = FileMIOTree.new( config.rebuild_backups_tmp_dir_path ) if config.rebuild_backups_tmp_dir_path
      MasterView.const_set('IOMgr', io_mgr)
    end

    # Initialize MasterView::Log with a logger which emits to std output, default DEBUG level
    def initialize_logger #:nodoc:
      #?return if defined?(Log)
      require 'masterview/extras/init_logger'
    end

    def install_in_rails #:nodoc:
      return if ! configuration.on_rails?
      enable_mv_admin_pages
      parse_templates_at_startup
      enable_reparse_changed_templates
      enable_rails_erb_direct
    end

    # install the MasterviewController to support masterview admin pages in the site
    def enable_mv_admin_pages #:nodoc:
      return if ! configuration.enable_admin_pages  #MasterView::EnableMasterViewAdminPages
      MasterView::Log.info{ 'MasterView Admin pages enabled' }

      # verify that stylesheets we use are available and if not copy them to public/stylesheets
      mv_generator_templates_dir = "#{configuration.mv_installation_dir}/generators/masterview/templates"
      unless File.exist?(mv_generator_templates_dir) 
        # we are in a gem so things are in different directories
        MasterView::Log.debug{ 'MasterView appears to be installed as a gem...' }
        mv_generator_dir = configuration.mv_installation_dir.gsub('\\','/').gsub( %r{/masterview-([^/]+)$}, '/masterview_generator-\1' )
        mv_generator_templates_dir = "#{mv_generator_dir}/templates"
      end
      MasterView::Log.debug{ 'MasterView gem admin stylesheet src dir='+mv_generator_templates_dir }

      if File.directory?(mv_generator_templates_dir)
        rails_app_stylesheets_dir = Pathname.for_path(RAILS_ROOT) + 'public/stylesheets/masterview'  
        stylesheet_specs = [
            # from/to spec: [ <src filename in templates dir>, <target filename in app stylesheets dir> ]
            [ 'style.css', 'style.css' ],
            [ 'sidebox.css', 'sidebox.css' ],
            [ 'color-scheme.css', 'color-scheme.css' ]
            ]
        src_dir_accessor = MasterView::FileMIOTree.new( mv_generator_templates_dir )
        dst_dir_accessor = MasterView::FileMIOTree.new( rails_app_stylesheets_dir, '.css', :logging => true)
        stylesheet_specs.each { | from, to |
          src_file = src_dir_accessor.path(from)
          dst_file = dst_dir_accessor.path(to)
          dst_file.write( src_file.read ) unless dst_file.exist?
        }
      end
      # add our app directories with the masterview_controller to the load path
      mv_controller_code_dirs = Dir[File.join(configuration.mv_code_base_dir, '/extras/app/**/*')].select { |dir| 
        File.directory?(dir) }
      mv_controller_code_dirs.each { |dir| $LOAD_PATH.push dir }
    end

    def parse_templates_at_startup #:nodoc:
      if configuration.parse_masterview_templates_at_startup
        require 'masterview/extras/watcher'
        MasterView::Log.debug { 'Parsing MasterView templates...' }
        MasterView::IOMgr.template.find(:pattern => MasterView::TemplateFilenamePattern) do |mio|
          MasterView::Parser.parse_mio(mio, MasterView::IOMgr.erb)
        end
      end
    end

    def enable_reparse_changed_templates  #:nodoc:
      if configuration.reparse_changed_masterview_templates #MasterView::ReparseChangedMasterViewTemplates
        # if not caching then check for masterview updates on every request
        # assert not ActionController::Base.perform_caching
        require 'masterview/extras/watcher' #:nodoc:
        require 'masterview/extras/init_rails_reparse_checking'
      end
    end

    def enable_rails_erb_direct #:nodoc:
      unless configuration.generate_rhtml_files
        # if not generating rhtml the read erb directly from masterview
        require 'masterview/extras/init_rails_erb_mv_direct'
      end
    end

    # Fires the user-supplied after_initialize block (Configuration#after_initialize) 
    def after_initialize #:nodoc:
      configuration.after_initialize_block.call if configuration.after_initialize_block
    end

  end

end