lewt 0.5.12

data/lib/lewt.rb

@@ -0,0 +1,233 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'date'
+require 'yaml'
+require 'optparse'
+require_relative 'lewtopts.rb'
+require_relative 'extension.rb'
+require_relative 'lewt_book.rb'
+require_relative 'lewt_ledger.rb'
+
+
+# Author::    Jason Wijegooneratne  (mailto:code@jwije.com)
+# Copyright:: Copyright (c) 2014 Jason Wijegooneratne
+# License::   MIT. See LICENSE.md distributed with the source code for more information.
+
+# This module acts as a container for the LEWT namespace
+module LEWT
+  
+  VERSION = "0.5.12"
+
+  # The Lewt class contains the major functionality of this program.
+  # It handles loading all extensions, gathering the results and passing options ariound the place.
+  # It also works quite closely with the LewtExtension and LewtOpts classes.
+  class Lewt
+
+    # Can be used to split strings passed to lewt through CL optios ie: 
+    #  "acme,wayne_corp".split(CLIENT_SPLIT_REGEX) # get each argument for client mathching
+    OPTION_DELIMITER_REGEX = /[,+:]/
+
+    # This matches symbols passed thought command ie: -p meta-stat => meta_stat
+    OPTION_SYMBOL_REGEX = /\W/  
+    
+    def initialize( library_options = nil )
+      core_settings = YAML.load_file( File.expand_path( '../config/settings.yml', __FILE__) )
+      if File.exists? File.expand_path( '~/.lewt_settings', __FILE__)
+        core_settings.merge! YAML.load_file( File.expand_path( '~/.lewt_settings', __FILE__) )
+      end
+
+      @lewt_stash = core_settings['lewt_stash'] || File.expand_path('../', __FILE__) + "/config/"
+      @settings = YAML.load_file( @lewt_stash + 'settings.yml' )
+      
+      # Start by loading the local config files
+      @customers = YAML.load_file(@lewt_stash + "customers.yml")
+      @enterprise = YAML.load_file(@lewt_stash + "enterprise.yml")
+      
+      # Referenceall registered extension for later invocation
+      @extensions = LEWT::Extension.new.lewt_extensions
+
+
+      # Load core extensions
+      load_extensions( File.expand_path('../extensions', __FILE__) )
+
+      if core_settings.has_key?("lewt_stash")
+        # load user defined extesnions
+        load_extensions
+      end
+
+      # Stores default options returned from extensions
+      # and the LEWT defaults at large
+      options = {}
+      @command = ARGV[0]
+      
+      # argument supplied for `cmd' (if any). ignore option flags IE args that start with the `-' symbol
+      @argument = ARGV[1] == nil || ARGV[1].match(/\-/i) ? nil : ARGV[1]
+      
+      @options = LewtOpts.new( @extensions, library_options  )
+      
+      parse_internal_commands
+    end
+
+    # Runs extract, process, render hooks.
+    def run
+      extract = fire_hooks("extract", @options)
+      process = fire_hooks("process", @options, extract )
+      render = fire_hooks("render", @options, process )
+    end
+    
+
+    # fn returns the desired customer given there name or alias.
+    # A REGEXP query can be passed to this object i.e. "ACME|NovaCorp|..."
+    # to match multiple customers.
+    # query [String]:: The query to search against.
+    def get_client( query ) 
+      client = nil
+      @customers.each do |c|
+        buildQ = [ c["name"], c["alias"] ].join("|")
+        regex = Regexp.new(buildQ, Regexp::IGNORECASE)
+        if regex.match( query ) != nil
+          client = c
+        end
+      end
+      return client
+    end
+    
+    
+    # Fire the logic loop from the specified hook onwards. Used when piping data in from CL
+    # hook [Sting]:: extract, process, or render
+    # data:: The data to pass to fire_hooks
+    def hook_process (hook, data)
+      case hook
+      when "extract"
+        extracted_data = fire_hooks("extract",@options,data)
+        hook_process("process", extracted_data)
+      when "process"
+        processed_data = fire_hooks("process",@options,data)
+        hook_process("render",processed_data)
+      when "render"
+        render_data = fire_hooks("render",@options,data)
+      else
+        raise ArugmentError, "#{self.class.name}.hook_process requires the start hook to be either render or process"
+      end
+    end
+    
+    # Fire a hook with the given options and overloaded parameters.
+    # hook [String]:: Expected hooks are 'extract', 'process', 'render'.
+    # options [Hash]:: The options gathered from using LewtOpts
+    # data [Mixed]:: The data to pass to the extensions.
+    def fire_hooks( hook, options, *data )
+      algamation = Array.new
+      @extensions.each { |e|
+        ## filter hooks
+        filter_regex = /#{options[hook.to_sym].gsub(",","|")}/
+        if e.methods.include?(hook.to_sym) and e.command_name.match(filter_regex)
+          case hook
+          when "extract"
+            algamation.concat e.extract(options)
+          when "process"
+            processed = e.process(options, *data)
+            if processed.kind_of? Array 
+              algamation.concat processed
+            else
+              algamation.push processed
+            end
+          when "render"
+            algamation.concat e.render(options, *data)
+            # dump render output to console of option specified.
+            puts algamation if options[:dump_output] == true
+          end
+        end
+      }
+      return algamation;
+    end
+
+
+    protected 
+
+    # reads input from standard INPUT
+    def read_stdin
+      data = ""
+      while line = $stdin.gets
+        data += line
+      end
+      return data
+    end
+
+    # Parses lewsts intenral commands. If none have been invoked it simple returns.
+    def parse_internal_commands
+      return if @command == nil
+      # raise argument error if command invoked without argument
+      if @argument == nil and @command != nil
+        puts @command
+        raise ArgumentError, "Class #{self.class.name} requires an argument t be supplied with a command" 
+      end
+      
+      if @command.match(/pipe/)
+        # pipe stdin into fire_hook(@argument) event
+        data = Psych.load(read_stdin)
+        if data != nil
+          hook_process(@argument, data)
+        else
+          raise ArgumentError, "could not parse STDIN pipe as YAML data."
+        end
+        exit
+      end
+
+    end
+
+    # Loads all installed LEWT extensions by checking the ext_dir setting variable for available ruby files.
+    # directory [String]:: The path where to look for extensions as a string.
+    def load_extensions( directory = @lewt_stash + "extensions" )
+      raise Exception, "Directory does not exist: #{directory}" if !Dir.exists?(directory)
+
+      Dir.foreach( directory ) do |file|
+        next if (file =~ /\./) == 0
+        # Cannot match with File.directory?(file) due to how ruby performs
+        # this test internaly when script is called from another dir.
+        # Therefor some REGEX will be used to match the .rb file extension instead...
+        if file.match(/\.rb/) != nil
+          load(directory + "/" + file)
+          ext_object = initialize_extension( file )
+        else
+          # is a directory
+          # load file in dir named {dir_name}.rb
+          load "#{directory}/#{file}/#{file}.rb"
+          ext_object = initialize_extension(file)
+        end
+      end
+
+      # load extensions packaged as GEMS
+      if @settings['gem_loads'] != nil
+        @settings['gem_loads'].split(Lewt::OPTION_DELIMITER_REGEX).each do |g|
+          match = g.split("/")
+          ext_object = initialize_gem(match[0], match[1])
+        end
+      end
+      
+    end
+    
+    # This method initialised a gem as specifed in your settings file.
+    # gem_require [String]:: The gem require path as a string
+    # gem_class [String]:: The gem class name for initialisation
+    def initialize_gem( gem_require, gem_class )
+      require gem_require
+      extension = eval( gem_class + ".new")
+      return @extensions.last
+    end
+
+    # fn basically anticipates a class name given its file path and then call its registerHanders method.
+    # Class names are transformed into UC words. '-' are interpreted as spaces in this conversion, and are 
+    # striped afterwards to return something like 'invoice-renderer.rb' >>> 'InvoiceRenderer' ready for
+    # evaluation.
+    # file [String]:: The file name as a string
+    def initialize_extension ( file )
+      classConvention = file.gsub("-", " ").split.map(&:capitalize).join(' ').gsub(" ","").gsub(".rb","")
+      extInit = ("LEWT::" + classConvention + ".new").to_s
+      extension = eval( extInit )
+      # extension will be registered on init so just reference the last one
+      return @extensions.last
+    end
+    
+  end
+
+end

data/lib/lewt_book.rb

@@ -0,0 +1,29 @@
+# Author::    Jason Wijegooneratne  (mailto:code@jwije.com)
+# Copyright:: Copyright (c) 2014 Jason Wijegooneratne
+# License::   MIT. See LICENSE.md distributed with the source code for more information.
+
+module LEWT
+
+
+  # The LEWTBook is used by extractors as a generic data structure to adhere to when
+  # returning there results.
+  # It follows a basic *general ledger* format without the double-entry book keeping.
+  #
+  # ===Usage:
+  #
+  # lewtbook = LEWTBook.new()
+  # lewtbook.add_row( LEWTLedger.new( params, ... ) )
+  #
+  class LEWTBook < Array
+    # adds a row to this element as per array.push. only accespts LEWTLedger objects as entries.
+    # element [LEWTLedger]:: An initialised LEWTLedger object containing your data.  
+    def push ( element )
+      if element.kind_of?(LEWT::LEWTLedger)
+        self.class.superclass.instance_method(:push).bind(self).call element
+      else
+        raise TypeError, "Class #{self.class.name} only accepts LEWT::LEWTLedger objects as its contents"
+      end
+    end
+  end
+
+end

data/lib/lewt_ledger.rb

@@ -0,0 +1,149 @@
+
+
+module LEWT
+
+  # LEWTLedger is a pre-formated hash structure that conforms somewhat to a standard general ledger entry.
+  #
+  # ===Keys
+  #  date_start:: Start date the entry occured on
+  #  date_end:: End date the entry occured on
+  #  category:: Some sort of general category for this entry i.e: 'Hourly Income', 'Operating Expenses' etc.
+  #  entity:: The entiry with whom this transaction occured with
+  #  description:: A description of the entry
+  #  quantity:: How many units
+  #  unit_cost:: The cost per unit
+  #  sub_total (optional):: A total or defaults to quantity * unit_cost
+  #  gst (optional):: The GST (VAT) amount to be added for this entry. Defaults to 0.
+  #  total (optional):: The total, including tax, for this entry. Defaults to sub_total + gst
+  #
+  # ===Usage
+  #  ledger = LEWTLedger.new(params, ...)
+  #
+  # Furthermore LEWTLedger provides some methods to work with metatags. Metatags can be embedded inside your extraction sources.
+  # I like to put mine in my 'description' fields, it works well with Calender Extractor. The meta data is basically a hash tag, you
+  # can do stuff like this:
+  #
+  #  '#happiness=10/10'
+  #  '#ignore-cost'
+  # 
+  # meta tags that do not assign a value [ie: =something] will evaluate to a boolean true flag. If you assign a value it must 
+  # be a fraction, this will be evaluated as a ruby Rational type. Your extensions can respond to these tags however they like.
+  # The metatags can be accessed with the <tt>metatags</tt> reader attribute:
+  #   ledger_data.metatags
+  #
+
+  class LEWTLedger < Hash
+
+    attr_reader :metatags
+    
+    # This is a general matching regex for metatags.
+    MATCH_SINGLE_META_REGEX = /[#](\S*)/
+    MATCH_MULTIPLE_META_REGEX = /#\S*/
+
+    def  initialize (args)
+      raise ArgumentError, "#{self.class.name} was not instantized with valid parameters" if valid?(args) == false
+      self[:date_start] = args[:date_start]
+      self[:date_end] = args[:date_end]
+      self[:category] = args[:category]
+      self[:entity] = args[:entity]
+      self[:description] = args[:description]
+      self[:quantity] = args[:quantity]
+      self[:unit_cost] = args[:unit_cost]
+      self[:sub_total] = self[:sub_total] || self[:quantity] * self[:unit_cost]
+      self[:gst] = args[:gst] || 0
+      self[:total] = args[:total] || ( self[:sub_total] + self[:gst] )
+      @metatags = parse_meta_tags(:description)
+      strip_readable_meta if @metatags != nil
+    end
+    
+    # parses a field on this object for meta data. Meta data can be embedded inside the ledger fields
+    # as a string by prefixing it with the '#' symbol. If you assign a value to the meta field with the '='
+    # symbol, its value will be interpreted as a number.
+    # ie: 
+    #  #good-pay // true
+    #  #happiness=6/10 // Rational(6,10)
+    # field_key [Symbol]:: the ledger key you wish to parse as a symbol.
+    def parse_meta_tags ( field_key )
+      value = self[field_key]
+      tags = parse_tags value
+      return tags
+    end
+    
+    protected
+    
+    # strips the meta data from a field so that it is no longer readable. leaves the metatags property on the object intact however
+    # field:: A Symbol corresponding to the field on this object to strip. Defaults to the description field.
+    def strip_readable_meta ( field = :description )
+      self[field].scan(LEWTLedger::MATCH_MULTIPLE_META_REGEX).each do |m|
+        self[field].slice!(m).strip!
+      end
+    end
+
+    # this function extracts all tags/values from a given string.
+    # string [String]:: a string to search for meta tags in.
+    def parse_tags (string)
+      tags = nil
+      string.scan(LEWTLedger::MATCH_SINGLE_META_REGEX) { |t|
+        if tags == nil
+          tags = Hash.new
+        end
+        tag_value = parse_tag_value t[0]
+        tag_name = parse_tag_name t[0]
+        tags[tag_name.gsub(/\W/,"_").to_sym] = tag_value
+      }
+      return tags
+    end
+
+    # parses the name of a tag and returns it as a symbol to be used as a hash key
+    # tag [string] a string containing the a singular meta tag.
+    def parse_tag_name( tag )
+      match_name = /[^=]*/
+      m = tag.match(match_name)
+      return m[0]
+    end
+    
+    # parses the value of a meta tag string. if just the string is given (ie: no = xx/xx) then the tag will have
+    # a value of true returned for it.
+    # tag [String]:: a meta tag string
+    def parse_tag_value ( tag )
+      match_value = /[=]\d*\/\d*/
+      match = tag.match match_value
+      # if no value found then this must be a boolean switch (because a tag was parsed from the field!) so set value to true
+      value = match != nil ? extract_fraction(match[0]) : true
+      return value
+    end
+    
+    # extracts a mathematical expression from a single tag
+    # format: Num +-/* Num
+    # string:: the string to extract the fraction from
+    def extract_fraction ( string )
+      match_fraction = /(\d{1,})([\/\+])(\d{1,})+/
+      #    m = string.match(match_fraction)[0]
+      m = string.match(match_fraction)
+      value = nil
+      if m != nil
+        value = Rational m[0]
+      end
+      return value
+    end    
+    
+    # validates the arguments this object is initialised with.
+    # args [Hash]:: The argument hash passed to this class on initialize
+    def valid?(args)
+      raise TypeError, "#{self.class.name} must be initialised with a hash" if not args.kind_of?(Hash)
+      args.each { |k,v|
+        case k
+        when :date_start, :date_end
+          raise TypeError, "Expected Time type" unless v.kind_of? Time
+        when :category, :entity, :description
+          raise TypeError, "Expected a string" unless v.kind_of? String
+        when :quantity, :unit_cost, :sub_total, :gst, :total
+          raise TypeError, "Expected a number" unless v.kind_of? Numeric
+        end
+      }
+      return true
+    end
+
+  end
+
+end

data/lib/lewtopts.rb

@@ -0,0 +1,170 @@
+# Author::    Jason Wijegooneratne  (mailto:code@jwije.com)
+# Copyright:: Copyright (c) 2014 Jason Wijegooneratne
+# License::   MIT. See LICENSE.md distributed with the source code for more information.
+
+
+module LEWT
+
+  # This is the options handling class for LEWT extensions. It handles translating extension options for usage in the command line
+  # & library run-times and acts as a sort of wrapper class for this functionality.
+  #
+  # ===LEWT's reserved option flags
+  #
+  # -x --extract:: what extractor[s] to use
+  # -p --process:: what processor[s] to use
+  # -o --render:: what renderer[s] to use
+  # -t --target:: target
+  # -s --start:: start target date
+  # -e --end:: end target date
+  #
+  # The user defined values for these options are readable by extensions at runtime.
+
+
+  class LewtOpts < Hash
+    
+    attr_reader :options, :defaults
+
+    # Sets up this extension.
+    def initialize ( extensions, library_options = nil )
+      default_options  = {
+        :start => {
+          :definition => "Start time for LEWT snapshot",
+          :default => DateTime.now - 8,
+          :type => DateTime,
+          :short_flag => "-s"
+        },
+        :end => {
+          :definition => "End time for LEWT snapshot",
+          :default => DateTime.now,
+          :type => DateTime,
+          :short_flag => "-e"
+        },
+        :target => {
+          :definition => "The target to filter data with. In the case of most extensions this will be the target customers but other alternatives are possible",
+          :short_flag => "-t",
+          :type => String
+        },
+        :extract => {
+          :definition => "The extraction extension(s) LEWT should use to pull data with. This can be a comma separated list for multiple sources",
+          :default => "calendar",
+          :type => String,
+          :short_flag => "-x"
+        },
+        :process => {
+          :definition => "The processor extensions LEWT should use to process the data with.",
+          :default => "invoice",
+          :type => String,
+          :short_flag => "-p"
+        },
+        :render => {
+          :definition => "The render(s) LEWT should use to output the data with. This can be a comma separate list for multiple outputs.",
+          :default => "liquid_render",
+          :type => String,
+          :short_flag => "-o"
+        },
+        :dump_output => {
+          :definition => "Toggle dumping output to console or log",
+          :default => true,
+          :short_flag => "-d"
+        }
+      }
+      
+      # gather extension options & merge into LEWTs defaults
+      extensions.each do |e|
+        if e.options != nil
+          default_options.merge!( e.options )
+        end
+      end
+
+      @defaults = default_options
+
+      # determine if using LEWT from command line (CL) or as a drop in library and parse options accordingly
+      if File.basename($0).match(/\.rb/) != nil
+        parse_library_options( default_options, library_options )
+      else
+        parse_command_line_options( default_options )
+      end
+
+    end
+    
+    # handles parsing & translating options in command line mode
+    # sets the value of the instantized object equal to the parsed options hash
+    # default_options [Hash]:: The default options gathered from all extension & Lewt itself to use in case user supplied values aren't given.
+    def parse_command_line_options( default_options )
+      options = self
+      
+      # Parse internal commands before extension commands & options to avoid any conflicts & to avoid extension invocation
+      # in case a internal command is called.
+      OptionParser.new do |opts|
+
+        default_options.each do | name, details |
+          # translate options default value if defined
+          if details.key?(:default) == true
+            options[name] = details[:default]
+          end
+
+          cl_type = details[:type].to_s == "DateTime" ? String : details[:type]
+          cl_sub = details[:type].to_s == "DateTime" ? "Date" : details[:type]
+
+          cl_option = "--#{name.to_s.gsub("_","-")} [#{cl_sub}]"
+
+          if details.key?(:short_flag) == true && details.key?(:type) == true
+            opts.on( details[:short_flag], cl_option, cl_type, details[:definition] ) do |o|
+              options[ name ] = prepare_input( details, o )
+            end 
+          elsif details.key?(:short_flag) == true && details.key?(:type) == false
+            opts.on( details[:short_flag], "--#{name.to_s.gsub("_","-")}", details[:definition] ) do |o|
+              options[ name ] = prepare_input( details, o )
+            end  
+          elsif details.key?(:short_flag) == false 
+            opts.on( cl_option, cl_type, details[:definition] ) do |o|
+              options[ name ] = prepare_input( details, o )
+            end
+          end
+
+        end
+        
+        opts.banner = "Usage: lewt -x EXTRACTOR -p PROCESSOR -o RENDERER"
+        opts.version = LEWT::VERSION
+        
+      end.parse!(ARGV)
+      
+      return options
+    end
+    
+    # handles parsing & translating options in library mode
+    # sets the value of the instantized object equal to the parsed options hash
+    # default_options [Hash]:: The default options gathered from all extension & Lewt itself to use in case user supplied values aren't given.
+    # library_options [Hash]:: Some options translated for use in lib mode
+    def parse_library_options ( default_options, library_options )
+      options = Hash.new
+
+      default_options.each do | name, details |
+        # translate options default value if defined
+        if details.key?(:default) == true
+          options[name] = details[:default]
+        end
+      end
+
+      # merge library options with options array
+      options.merge!(library_options)
+      
+      # assign options to self
+      options.each do |k,v|
+        self[k] = v
+      end
+    end
+    
+    # this function basically exists to get around the limited variable initialization functionality of
+    # Ruby standard option parser class.
+    def prepare_input ( details, value )
+      type = details[:type]
+      if type == DateTime
+        initialized_value = DateTime.parse(value)
+      else
+        initialized_value = value
+      end
+      return initialized_value
+    end
+  end
+end