# Af - an application framework

gem 'fiksu-af'

This application framework supports:

* an Application class with supporting infrastruction
* command line options integrated into instance (and class) variables
* logging via log4r with support for papertrail
* postgres advisory locking via pg_advisor_locker gem
* postgres database connection updates via pg_application_name gem
* threads and message passing
* application components adding loggers and command line options

## Application class

The class ::Af::Application provides a basic interface to the start-up
and management of Ruby on Rails scripts.

A simple example of an application which logs its startup and exits
is:

```
class MyApplication < ::Af::Application
  opt :word, "the word", :short => :w, :default => "bird"

  def work
    logger.info "Started up: #{@word} is the word"
    exit 0
  end
end
```

Class-method "opt" specifies command line parameter(s) whose arguments
are stored in instance variables.  MyApplication specifies a single
parameter "--word" with a short alias "-w" that accepts a string
argument (whose default is "bird", so we know it should be a string).
The parameters value will be stored in class instance variable: @word.
More information on command line option glue is provided in the
Command Line Options section.

The method "logger" is available to ::Af::Application to create and
fetch log4r loggers.  In this case, we use the basic application
logger (named "MyApplication") and logs an INFO level message.  More
information on the glue ::Af::Application provides with Log4r is
in the logging section below.

This application would be run from the command line as:

```
$ script/rails runner MyApplication.run --word grease
```

The class method #run provides start-up glue for applications, parsing
command line options, environment variables and configuration files.
The instance method #work is where application codes start their work.

## Command Line Options

a more interesting example of options from multiple classes

```
class AfSideComponent
  include Af::Application::Component

  opt_group :side_component_stuff, "options associated with this side component" do
    opt :a_side_component_option, :default => "foo"
  end

  opt :basic_option_from_component, "this is a switch from the side component, in the basic (default) group"

  create_proxy_logger :foo

  def do_something
    foo_logger.info "doing something @@a_side_component_option='#{@@a_side_component_option}'"
    foo_logger.info "did something @@basic_option_from_component=#{@@basic_option_from_component.inspect}"
  end
end
```

```
class AfScriptWithOptions < ::Af::Application
  opt_group :singles, "parameters whose types are a single value" do
    opt :a_switch, "a switch"
    opt :an_int, "an integer of some sort", :default => 1
    opt :a_float, "a float of some sort whose default is PI", :default => 3.14
    opt :a_string, "a string of some sort", :type => :string
    opt :a_uri, "some uri", :type => :uri
    opt :a_date, "a date", :type => :date
    opt :a_time, "a time", :type => :time
    opt :a_datetime, "a datetime", :type => :datetime
    opt :a_choice, "a choice", :argument_note => "COLOR", :choices => [:red, :blue, :green, :yellow, :white, :black, :orange]
  end

  # there is already an advanced option group -- it is set to hidden by default
  opt_group :advanced, "advanced parameters", :hidden => false do
    opt :a_small_integer, "another integer", :default => 10, :argument_note => "[1 >= INTEGER <= 10]" do |argument,option|
      argument = argument.to_i
      if (argument < 1 || argument > 10)
        opt_error "ERROR: #{option.long_name}: value must be between 1 and 10 (inclusive)"
      end
      argument
    end
    opt :a_constrained_number, "a number which is not an integer", :requirement => :required, :argument_note => "NON-INTEGER" do |argument,option|
      i_argument = argument.to_i
      f_argument = argument.to_f
      if (i_argument == f_argument)
        opt_error "ERROR: #{option.long_name}: value must not be an integer"
      end
      f_argument
    end
  end

  opt_group :collections, "parameters whose types are collections" do
    opt :a_hash, "a key value pair", :type => :hash
    opt :some_ints, "a list of integer", :type => :ints
    opt :some_integers, "a list of integer", :type => :integers
    opt :some_floats, "a list of floats", :type => :floats
    opt :some_numbers, "a list of numbers", :type => :numbers
    opt :some_strings, "a list of strings", :type => :strings
    opt :some_uris, "a list of uris", :type => :uris
    opt :some_dates, "a list of dates", :type => :dates
    opt :some_times, "a list of times", :type => :times
    opt :some_datetimes, "a list of datetimes", :type => :datetimes
    opt :some_choices, "a list of choices", :choices => [:foo, :bar, :baz, :beltch]
  end

  opt_group :blank, "a blank group that won't be seen"

  opt :word, "the word to print", :default => :foo, :choices => [:foo, :bar, :baz, :beltch]
  opt :words, "the words to print", :default => [:foo], :choices => [:foo, :bar, :baz, :beltch]
  opt :numbers, "the number lists", :default => [1,2,3]
  opt :switcher, "this is a switch"

  def af_opt_class_path
    [AfSideComponent] + super
  end

  def logger
    super('Process::T')
  end

  def work
    logger.info "switcher: #{switcher.inspect}"
    logger.info "WORK STARTED: #{@word}"
    logger.info @words.inspect
    logger.info "NUMBERS: #{@numbers.inspect}"

    AfSideComponent.new.do_something

    logger.info "WORK COMPLETED: #{@word}"
  end
end

```

## Logging with Log4r

Some changes to Log4r:

* root loggers are no longer null loggers -- you can add outputters to them
* the global logger is used to set a global log level (root is no longer used for this)
* yaml configurator has been updated to handle new root logger semantics
* yaml configurator has been updated to accept a set of files AND sections (default section: log4r_config)

What this really means is that you can set up one outputter in the root
logger to manage the default logging behavior.

## Thread Pool

*TODO*

## TCP Message Passing

*TODO*