module Vedeu

  module Config

    # The Configuration::API class parses client application configuration into
    # options used by Vedeu to affect certain behaviours.
    #
    class API

      include Vedeu::Common

      # @param (see #initialize)
      def self.configure(&block)
        new(&block).configuration
      end

      # Returns a new instance of Vedeu::Config::API.
      #
      # Configure Vedeu via a simple configuration API DSL. Options set here
      # override the default Vedeu configuration set in
      # {Vedeu::Configuration#defaults}.
      #
      #   Vedeu.configure do
      #     # ...
      #   end
      #
      # @param block [Proc]
      # @return [Vedeu::Configuration::API]
      def initialize(&block)
        instance_eval(&block) if block_given?
      end

      # Returns the configuration options set up by the API DSL.
      #
      # @return [Hash<Symbol => Boolean, Fixnum, String>]
      def configuration
        Vedeu::Config.log(Esc.green { '[api]' }, options)
      end

      # Sets boolean to allow user input. The default behaviour of Vedeu is to
      # be interactive.
      #
      #   Vedeu.configure do
      #     interactive! # => same as `interactive true` or `standalone false`
      #     # ...
      #   end
      #
      #   Vedeu.configure do
      #     interactive true # => Allow user input.
      #     # ...
      #   end
      #
      #   Vedeu.configure do
      #     interactive false # => Disallow user input.
      #     # ...
      #   end
      #
      # @param value [Boolean]
      # @return [Boolean]
      def interactive!(value = true)
        options[:interactive] = value
      end
      alias_method :interactive, :interactive!

      # Sets boolean to prevent user intervention. This is the same as setting
      # {include:Vedeu::Config::API#interactive!} to false.
      #
      #   Vedeu.configure do
      #     standalone! # => same as `standalone true` or `interactive false`
      #     # ...
      #   end
      #
      #   Vedeu.configure do
      #     standalone true # => Disallow user input.
      #     # ...
      #   end
      #
      #   Vedeu.configure do
      #     standalone false # => Allow user input.
      #     # ...
      #   end
      #
      # @param value [Boolean]
      # @return [Boolean]
      def standalone!(value = true)
        options[:interactive] = !value
      end
      alias_method :standalone, :standalone!

      # Sets boolean to run the Vedeu main application loop once. In effect,
      # using `run_once!` or setting `run_once` to true will allow Vedeu to
      # initialize, run any client application code, cleanup, then terminate.
      #
      #   Vedeu.configure do
      #     run_once!
      #     # ...
      #   end
      #
      # @param value [Boolean]
      # @return [Boolean]
      def run_once!(value = true)
        options[:once] = value
      end
      alias_method :run_once, :run_once!

      # Sets boolean to run a DRb server.
      #
      #   Vedeu.configure do
      #     drb!
      #     # ...
      #   end
      #
      # @param value [Boolean]
      # @return [Boolean]
      def drb!(value = true)
        options[:drb] = value
      end
      alias_method :drb, :drb!

      # Sets the hostname or IP address of the DRb server.
      #
      #   Vedeu.configure do
      #     drb_host 'localhost'
      #     # ...
      #   end
      #
      # @param hostname [String]
      # @return [String]
      def drb_host(hostname = '')
        options[:drb_host] = hostname
      end

      # Sets the port of the DRb server.
      #
      #   Vedeu.configure do
      #     drb_port 12345
      #     # ...
      #   end
      #
      # @param port [Fixnum|String]
      # @return [String]
      def drb_port(port = '')
        options[:drb_port] = port
      end

      # Sets the height of the fake terminal in the DRb server.
      #
      #   Vedeu.configure do
      #     drb_height 25
      #     # ...
      #   end
      #
      # @param height [Fixnum]
      # @return [Fixnum]
      def drb_height(height = 25)
        options[:drb_height] = height
      end

      # Sets the width of the fake terminal in the DRb server.
      #
      #   Vedeu.configure do
      #     drb_width 80
      #     # ...
      #   end
      #
      # @param width [Fixnum]
      # @return [Fixnum]
      def drb_width(width = 80)
        options[:drb_width] = width
      end

      # Sets the terminal mode to `cooked`. Default terminal mode is `raw`.
      # Also, see {Vedeu::Config::API#raw!}
      #
      #   Vedeu.configure do
      #     cooked!
      #     # ...
      #   end
      #
      # @return [Boolean]
      def cooked!
        options[:terminal_mode] = :cooked
      end
      alias_method :cooked, :cooked!

      # Sets the terminal mode to `fake`. Default terminal mode is `raw`.
      #
      # @example
      #   Vedeu.configure do
      #     fake!
      #     # ...
      #   end
      #
      # @return [Boolean]
      def fake!
        options[:terminal_mode] = :fake
      end
      alias_method :fake, :fake!

      # Sets the terminal mode to `raw`. Default terminal mode is `raw`.
      # Also, see {Vedeu::Config::API#cooked!}
      #
      #   Vedeu.configure do
      #     raw!
      #     # ...
      #   end
      #
      # @return [Boolean]
      def raw!
        options[:terminal_mode] = :raw
      end
      alias_method :raw, :raw!

      # Sets boolean to enable/disable debugging. Vedeu's default setting is
      # for debugging to be disabled. Using `debug!` or setting `debug` to true
      # will enable debugging.
      #
      # @note
      #   Be aware that running an application with debugging enabled will
      #   affect performance.
      #
      #   Vedeu.configure do
      #     debug!
      #     # ...
      #   end
      #
      #   Vedeu.configure do
      #     debug false
      #     # ...
      #   end
      #
      # @param value [Boolean]
      # @return [Boolean]
      def debug!(value = true)
        options[:debug] = value
      end
      alias_method :debug, :debug!

      # Sets the colour mode of the terminal.
      #
      #   Vedeu.configure do
      #     colour_mode 256
      #     # ...
      #   end
      #
      # @note
      #   iTerm 2 on Mac OSX will handle the true colour setting (16777216),
      #   whereas Terminator on Linux will not display colours correctly. For
      #   compatibility across platforms, it is recommended to either not set
      #   the colour mode at all and allow it to be detected, or use 256 here.
      #
      # @param value [Fixnum]
      # @raise [Vedeu::Error::InvalidSyntax] When the value parameter is not one
      #   of +8+, +16+, +256+ or +16777216+.
      # @return [Boolean]
      def colour_mode(value = nil)
        unless valid_colour_mode?(value)
          fail Vedeu::Error::InvalidSyntax,
               '`colour_mode` must be `8`, `16`, `256`, `16777216`.'
        end

        options[:colour_mode] = value
      end

      # Sets the location of the log file.
      #
      #   Vedeu.configure do
      #     log '/var/log/vedeu.log'
      #     # ...
      #   end
      #
      # @param filename [String]
      # @return [String]
      def log(filename = '')
        options[:log] = filename
      end

      # Only log specific message types. A complete list of message types can
      # be found at {Vedeu::Log.message_types}.
      #
      #   Vedeu.configure do
      #     log_only :debug, :event
      #     # ...
      #   end
      #
      # @param types [Array<Symbol>] The message types which should be logged.
      # @return [Array<Symbol>]
      def log_only(*types)
        options[:log_only] = types
      end

      # Sets the renderers for Vedeu. Each renderer added must have the class
      # method '.render' defined as this will be called when rendering content.
      #
      #   Vedeu.configure do
      #     renderer MyRenderer
      #     # ...
      #   end
      #
      #   Vedeu.configure do
      #     renderers MyRenderer, MyOtherRenderer
      #     # ...
      #   end
      #
      # @param renderer [Array<Class>|Class]
      # @return [Array<Class>]
      def renderer(*renderer)
        options[:renderers] = Vedeu::Configuration.renderers + renderer
      end
      alias_method :renderers, :renderer

      # Override the base path for the application (for locating templates and
      # other resources). By default the base path is just cwd but this will
      # not work for many applications.
      #
      #   Vedeu.configure do
      #     base_path '/path/to/application'
      #     # ...
      #   end
      #
      # @param path [String]
      # @return [String]
      def base_path(path = nil)
        options[:base_path] = path
      end

      # Sets the root of the client application. Vedeu will execute this
      # controller with action and optional arguments first.
      #
      #   Vedeu.configure do
      #     root :controller, :action, args
      #     # ...
      #   end
      #
      # @param args [Array<Symbol|void>]
      # @return [Class]
      def root(*args)
        options[:root] = args
      end

      # Sets the value of STDIN.
      #
      #   Vedeu.configure do
      #     stdin IO.console
      #     # ...
      #   end
      #
      # @param io [File|IO]
      # @return [File|IO]
      def stdin(io)
        options[:stdin] = io
      end

      # Sets the value of STDOUT.
      #
      #   Vedeu.configure do
      #     stdout IO.console
      #     # ...
      #   end
      #
      # @param io [File|IO]
      # @return [File|IO]
      def stdout(io)
        options[:stdout] = io
      end

      # Sets the value of STDERR.
      #
      #   Vedeu.configure do
      #     stderr IO.console
      #     # ...
      #   end
      #
      # @param io [File|IO]
      # @return [File|IO]
      def stderr(io)
        options[:stderr] = io
      end

      # Compression reduces the number of escape sequences being sent to the
      # terminal which improves redraw/render/refresh rate. By default it is
      # enabled.
      #
      # Sets boolean to enable/disable compression. Vedeu's default setting is
      # for compression to be enabled. Setting `compression` to false will
      # disable compression.
      #
      #   Vedeu.configure do
      #     compression! # enabled (default)
      #     # ...
      #   end
      #
      #   Vedeu.configure do
      #     compression false
      #     # ...
      #   end
      #
      # @note
      # - Be aware that running an application without compression will
      #   affect performance.
      # - Compression cannot yet be configured using a CLI option flag.
      #
      # @param value [Boolean]
      # @return [Boolean]
      def compression(value = true)
        options[:compression] = value
      end
      alias_method :compression!, :compression

      # Sets the terminal mode. Valid values can be either ':cooked', ':fake' or
      # :raw'.
      #
      #   Vedeu.configure do
      #     terminal_mode :cooked
      #
      #     # or...
      #
      #     terminal_mode :fake
      #
      #     # or...
      #
      #     terminal_mode :raw
      #
      #     # ... some code
      #   end
      #
      # @param mode [Symbol] Either ':cooked', ':fake' or ':raw'.
      # @raise [Vedeu::Error::InvalidSyntax] When the mode is not ':cooked',
      #   ':fake' or ':raw'.
      # @return [Symbol]
      # @see Vedeu::Config::API#cooked!
      # @see Vedeu::Config::API#fake!
      # @see Vedeu::Config::API#raw!
      def terminal_mode(mode)
        if [:cooked, :fake, :raw].include?(mode)
          options[:terminal_mode] = mode

        else
          fail Vedeu::Error::InvalidSyntax,
               'Terminal mode can be set to either :cooked, :fake or :raw'

        end
      end

      private

      # Returns the options set via the configuration API DSL or an empty Hash
      # when none were set.
      #
      # @return [Hash]
      def options
        @options ||= {}
      end

      # Checks that the value provided to {#colour_mode} is valid.
      #
      # @param value [Fixnum]
      # @return [Boolean]
      def valid_colour_mode?(value)
        value.is_a?(Fixnum) && [8, 16, 256, 16_777_216].include?(value)
      end

    end # API

  end # Config

end # Vedeu