rcl 0.0.2

data/README

@@ -0,0 +1,107 @@
+== What
+Ramsey's Common Library version 0.0.3
+
+This is simply a collection of Ruby modules that perform useful tasks. There
+are methods that do simple things like check permissions on files and
+directories, create and manipulate timestamps and authentication tokens, and
+so on. There are a couple of interesting modules that do interesting things
+like RELAXNG schema validation of XML files and an interactive command shell
+with history (with big props to the GNU Readline library).
+
+Briefly, the modules and their respective methods are:
+
+Base#initialize
+Base#dump
+Base#create
+Base#modify
+Base#update_modify
+Base#access
+Base#update_access
+
+Perms#check_dir
+Perms#check_dir_r
+Perms#check_dir_w
+Perms#check_dir_rw
+Perms#check_file
+Perms#check_file_r
+Perms#check_file_w
+Perms#check_file_rw
+Perms#check_owned
+
+Shell#initialize
+Shell#register
+Shell#unregister
+Shell#run
+Shell#history
+
+Timestamp#new
+Timestamp#create
+Timestamp#modify
+Timestamp#access
+Timestamp#update_create
+Timestamp#update_modify
+Timestamp#update
+Timestamp#dump
+
+Token#initialize
+Token#authenticate
+
+URL#encode
+URL#decode
+URL#encoded?
+
+XML#preprocess
+XML#validate
+
+== How
+require 'rubygems'
+require 'rcl'
+
+== Examples
+When you run the example programs, do it like so:
+
+  ruby examples/shell.rb
+
+Use these example programs to see how you might use and otherwise integrate RCL
+functionality into your own programs.
+
+== Install
+I added a Rakefile and a gem spec. To build the gem, just type:
+
+  rake gem
+
+To install the gem, just type:
+
+  sudo gem install rcl-0.0.3.gem
+
+== Notes
+I haven't tested this code with YARV, so YMMV.
+
+A summary of the international standard date and time notation
+http://www.cl.cam.ac.uk/~mgk25/iso-time.html
+
+REXML support for RELAXNG document validation is incomplete and buggy. The
+XML::preprocess method solves a particularly thorny issue which causes
+REXML::RELAXNG to fail in the presence of whitespace due to formatting. Given
+a pathname, this function will remove leading and trailing whitespace from
+individual lines. The processed document will be returned to the caller for
+further processing.
+
+== External Code and Acknowledgements
+Occasionally I run across interesting snippets of Ruby code on the 'net that
+don't seem to have a reliable home. They could be orphaned projects or just a
+random post on a mailing list somewhere. If I find the code to be useful, I
+will add it to the lib/ext directory. Not wishing to steal anyone's thunder,
+here are acknowledgements for the current contents of the lib/ext directory:
+
+- ANSIColour 0.1 by Robert Ryan (rjr@rollmop.org)
+  http://raa.ruby-lang.org/project/term-ansicolour/
+
+- dir.rb by Ara T. Howard (ara.t.howard@noaa.gov)
+
+- YAML Helper by Xavier Shay
+  http://rhnh.net/projects/yaml+helper
+
+I do not claim copyright or ownership of these included bits of code. I am
+merely including them in one place because I use them all the time and wanted
+to make them more available to my own projects.

data/lib/rcl.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+# rcl.rb
+# yesmar@speakeasy.net
+
+module RCL
+  RCL::NAME = 'rcl'
+  RCL::VERSION = '0.0.2'
+  RCL::COPYRIGHT = 'Copyright (c) 2008 Ramsey Dow'
+  def self.copyright() RCL::COPYRIGHT end
+  def self.version() RCL::VERSION end
+  def self.libdir() File.expand_path(__FILE__).gsub(%r/\.rb$/, '') end
+end
+
+$LOAD_PATH.unshift(File.dirname(__FILE__)+'/rcl/ext')
+
+require 'ansicolour'
+require 'dir'
+require 'yaml_helper'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__)+'/rcl')
+
+require 'base'
+require 'perms'
+require 'shell'
+require 'timestamp'
+require 'token'
+require 'url'
+require 'xml'
+
+# TODO: need to fix any lingering inheritance issues
+# TODO: bad developer, no unit tests
+# TODO: need to finish developing example programs
+
+raise RuntimeError, 'This library is for require only' if $0 == __FILE__

data/lib/rcl/base.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+# base.rb
+# yesmar@speakeasy.net
+
+module RCL
+  class Base
+    # initialize instance
+    def initialize
+      @timestamp = Timestamp.new
+
+      nil
+    end
+
+    # return creation time
+    def create
+      @timestamp.create
+    end
+
+    # return modification time
+    def modify
+      @timestamp.modify
+    end
+
+    # update modification time
+    def update_modify
+      @timestamp.update_modify
+    end
+
+    # return access time
+    def access
+      @timestamp.access
+    end
+
+    # update access time
+    def update_access
+      @timestamp.update_access
+    end
+
+    # dump instance state to specified output stream
+    def dump(indent=0, stream=STDOUT)
+      raise ArgumentError, 'nil indent' if indent.nil?
+      raise ArgumentError, 'invalid indent class' if indent.class != Fixnum
+      raise ArgumentError, 'indent range error' if indent < 0
+      raise ArgumentError, 'nil stream' if stream.nil?
+      raise ArgumentError, 'invalid stream class' if stream.class != IO
+
+      # instance
+      indent.times { stream << ' ' }
+      stream << "#{self.class}<#{self.object_id}> instance:\n"
+
+      indent += 2
+
+      # @timestamp
+      @timestamp.dump(indent, stream)
+
+      nil
+    end
+
+    private
+
+    @timestamp
+  end
+end

data/lib/rcl/perms.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+# perms.rb
+# yesmar@speakeasy.net
+
+module RCL
+  module Perms
+    # check that specified directory exists
+    def self.check_dir(pathname)
+      raise ArgumentError, 'nil pathname' if pathname.nil?
+      raise ArgumentError, 'invalid pathname class' if pathname.class != String
+      raise ArgumentError, 'empty pathname' if pathname.empty?
+      raise ArgumentError, "#{pathname} does not exist" \
+        if !File.exists?(pathname)
+      raise ArgumentError, "#{pathname} is not a directory" \
+        if !File.directory?(pathname)
+
+      true
+    end
+
+    # check that specified directory exists and is readable
+    def self.check_dir_r(pathname)
+      check_dir(pathname)
+      raise ArgumenError, "#{pathname} is not readable" \
+        if !File.readable?(pathname)
+
+      true
+    end
+
+    # check that specified directory exists and is writable
+    def self.check_dir_w(pathname)
+      check_dir(pathname)
+      raise ArgumentError, "#{pathname} is not writable" \
+        if !File.writable?(pathname)
+
+      true
+    end
+
+    # check that specified directory exists and is both readable and writable
+    def self.check_dir_rw(pathname)
+      check_dir(pathname)
+      check_dir_r(pathname)
+      check_dir_w(pathname)
+
+      true
+    end
+
+    # check that specified file exists
+    def self.check_file(pathname)
+      raise ArgumentError, 'nil pathname' if pathname.nil?
+      raise ArgumentError, 'invalid pathname class' if pathname.class != String
+      raise ArgumentError, 'empty pathname' if pathname.empty?
+      raise ArgumentError, "#{pathname} does not exist" \
+        if !File.exist?(pathname)
+      raise ArgumentError, "#{pathname} is not a directory" \
+        if !File.file?(pathname)
+
+      true
+    end
+
+    # check that specified file exists and is readable
+    def self.check_file_r(pathname)
+      check_file(pathname)
+      raise ArgumentError, "#{pathname} is not readable" \
+        if !File.readable?(pathname)
+
+      true
+    end
+
+    # check that specified file exists and is writable
+    def self.check_file_w(pathname)
+      check_file(pathname)
+      raise ArgumentError, "#{pathname} is not writable" \
+        if !File.writable?(pathname)
+
+      true
+    end
+
+    # check that specified file exists and is both readable and writable
+    def self.check_file_rw(pathname)
+      check_file(pathname)
+      check_file_r(pathname)
+      check_file_w(pathname)
+
+      true
+    end
+
+    # check file group and ownership
+    def self.check_owned(pathname)
+      raise ArgumentError, 'nil pathname' if pathname.nil?
+      raise ArgumentError, 'invalid pathname class' if pathname.class != String
+      raise ArgumentError, 'empty pathname' if pathname.empty?
+      raise ArgumentError, "#{pathname} does not have correct group" \
+        if !File.grpowned?(pathname)
+      raise ArgumentError, "#{pathname} does not have correct ownership" \
+        if !File.owned?(pathname)
+
+      true
+    end
+  end
+end
+
+raise RuntimeError, 'This library is for require only' if $0 == __FILE__

data/lib/rcl/shell.rb

@@ -0,0 +1,167 @@
+#!/usr/bin/env ruby
+
+# shell.rb
+# yesmar@speakeasy.net
+
+require 'readline'
+
+module RCL
+  class Shell < Base
+    attr_accessor :prompt
+    attr_reader :history
+
+    Command = Struct.new('COMMAND', :command, :timestamp)
+
+    def initialize(processor, banner, prompt=DefaultPrompt)
+      raise ArgumentError, 'nil processor' if processor.nil?
+      raise ArgumentError, 'invalid processor class' \
+        if processor.class != Symbol
+      if !banner.nil?
+        raise ArgumentError, 'invalid banner class' if banner.class != Symbol
+      end
+      raise ArgumentError, 'nil prompt' if prompt.nil?
+      raise ArgumentError, 'invalid prompt class' if prompt.class != String
+
+      @banner = banner
+      @process = processor
+      @commands = {}
+      @prompt = (prompt[prompt.length-1].chr != ' ') ? "#{prompt} " : prompt
+      @history = []
+
+      nil
+    end
+
+    # TODO: Shell#register needs love
+    def register(command, *args)
+      raise ArgumentError, 'nil command' if command.nil?
+      raise ArgumentError, 'invalid command class' if command.class != String
+      raise ArgumentError, 'empty command' if command.empty?
+      if !args.nil?
+        raise ArgumentError, 'invalid args class' if args.class != Array
+        raise ArgumentError, 'empty args' if args.empty?
+        args.each do |arg|
+          raise ArgumentError, 'nil arg' if arg.nil?
+          raise ArgumentError, 'invalid arg class' if arg.class != String
+          raise ArgumentError, 'empty arg' if arg.empty?
+        end
+      end
+
+      @commands[command] = args
+
+      nil
+    end
+
+    # TODO: Shell#unregister needs love
+    def unregister(command)
+      raise ArgumentError, 'nil command' if command.nil?
+      raise ArgumentError, 'invalid command class' if command.class != String
+      raise ArgumentError, 'empty command' if command.empty?
+
+      if @commands.has_key?(command)
+        return @commands.delete(command)
+      end
+
+      nil
+    end
+
+    def run(*args)
+      if !@banner.nil?
+        send(@banner)
+        puts
+      end
+
+      loop do
+        buffer = Readline::readline(@prompt, true)
+        break if buffer.nil?
+        buffer.chomp!
+        next if buffer.nil?
+        buffer.strip!
+
+        # double bang repeatsw last command
+        if buffer =~ /^!!$/
+          if !@history.last.nil?
+            @history << Command.new(@history.last.command, Time.now)
+            exec(@history.last.command)
+          else
+            puts '!!: event not found'
+          end
+          next
+        end
+
+        # repeat specified command from history buffer
+        if buffer =~ /^!(\-)?(\d*)$/
+          if $1.nil?
+            # forward bang history
+            pos = $2.to_i-1
+            if pos < 0 || pos > @history.size-1
+              puts "#{buffer}: event not found"
+              next
+            else
+              if !@history[pos].command.nil?
+                @history << Command.new(@history[pos].command, Time.now)
+                exec(@history[pos].command)
+              end
+            end
+          else
+            # reverse bang history
+            pos = $2.to_i-1
+            if pos < 0 || pos > @history.size-1
+              puts "#{buffer}: event not found"
+              next
+            else
+              if !@history[pos].command.nil?
+                @history << Command.new(@history[-pos].command, Time.now)
+                exec(@history[-(pos+1)].command)
+              end
+            end
+          end
+          next
+        end
+
+        next if buffer.empty?
+
+        @history << Command.new(buffer, Time.now)
+        exec(buffer)
+      end
+
+      puts
+    end
+
+    def history
+      i = 1
+      @history.each do |cb|
+        printf("%4d: +%d %s\n", i, cb.timestamp.to_i, cb.command)
+        i += 1
+      end
+
+      nil
+    end
+
+    # TODO: need to add Shell#dump method
+
+    private
+
+    def exec(command)
+      raise ArgumentError, 'nil command' if command.nil?
+      raise ArgumentError, 'invalid command class' if command.class != String
+      raise ArgumentError, 'empty command' if command.empty?
+      
+      cmd_ary = command.split(/[ \t]/)
+        
+      cmd = cmd_ary[0]
+      args = cmd_ary[1..-1]
+      
+      send(@process, cmd, args)
+    end
+
+    DefaultPrompt = ':'
+
+    @banner
+    @process
+    @commands
+    @prompt
+    @history
+  end
+end
+
+raise RuntimeError, 'This library is for require only' if $0 == __FILE__

data/lib/rcl/timestamp.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+
+# timestamp.rb
+# yesmar@speakeasy.net
+
+module RCL
+  class Timestamp
+    attr_reader :create, :modify, :access
+
+    def initialize
+      @create = Time.now
+      @modify = nil
+      @access = nil
+
+      nil
+    end
+
+    def update_modify
+      @modify = Time.now
+
+      nil
+    end
+
+    def update_access
+      @access = Time.now
+
+      nil
+    end
+
+    def update
+      update_modify
+      update_access
+
+      nil
+    end
+
+    def dump(indent=0, stream=STDOUT)
+      raise ArgumentError, 'nil indent' if indent.nil?
+      raise ArgumentError, 'invalid indent class' if indent.class != Fixnum
+      raise ArgumentError, 'indent range error' if indent < 0
+      raise ArgumentError, 'nil stream' if stream.nil?
+      raise ArgumentError, 'invalid stream class' if stream.class != IO
+
+      # instance
+      indent.times { stream << ' ' }
+      stream << "#{self.class}<#{self.object_id}> instance:\n"
+
+      indent += 2
+
+      # create
+      indent.times { stream << ' ' }
+      stream << "create: #{@create}\n"
+
+      # modify
+      indent.times { stream << ' ' }
+      stream << "modify: #{!@modify.nil? ? @modify : '<unset>'}\n"
+
+      # access
+      indent.times { stream << ' ' }
+      stream << "access: #{!@access.nil? ? @access : '<unset>'}\n"
+
+      nil
+    end
+
+    private
+
+    @create
+    @modify
+    @access
+  end
+
+  # convert milliseconds to hours, minutes, and seconds
+  def self.ms_to_s(ms)
+    raise ArgumentError, 'nil ms' if ms.nil?
+    raise ArgumentError, 'invalid ms class' if !ms.is_a?(Integer)
+
+    s = ms % 60
+    m = (ms / 60) % 60
+    h = (ms / 3600) % 24
+
+    str = []
+
+    str << h.to_s << 'h ' if h >= 1
+    str << m.to_s << 'm ' if m >= 1
+    str << s.to_s << 's ' if s > 0
+
+    return str.join
+    
+  end
+end
+
+raise RuntimeError, 'This library is for require only' if $0 == __FILE__

data/lib/rcl/token.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+# token.rb
+# yesmar@speakeasy.net
+
+require 'digest/sha2'
+
+module RCL
+  class Token
+    def initialize(key)
+      raise ArgumentError, 'nil key' if key.nil?
+      raise ArgumentError, 'invalid key class' if key.class != String
+      raise ArgumentError, 'empty key' if key.empty?
+
+      srand
+
+      @salt = [Array.new(6) { rand(256).chr }.join].pack("m").chomp
+      @hash = Digest::SHA256.hexdigest(@salt+key)
+
+      nil
+    end
+
+    def authenticate(key)
+      raise ArgumentError, 'nil key' if key.nil?
+      raise ArgumentError, 'invalid key class' if key.class != String
+      raise ArgumentError, 'empty key' if key.empty?
+
+      Digest::SHA256.hexdigest(@salt+key) == @hash
+    end
+
+    private
+
+    @salt
+    @hash
+  end
+end

data/lib/rcl/url.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+# url.rb
+# yesmar@speakeasy.net
+
+require 'uri'
+
+module RCL
+  module URL
+    def self.encode(url)
+      raise ArgumentError, 'nil url' if url.nil?
+      raise ArgumentError, 'invalid url' if url.class != String
+      raise ArgumentError, 'empty url' if url.empty?
+
+      URI::escape(url, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
+    end
+
+    def self.decode(url)
+      raise ArgumentError, 'nil url' if url.nil?
+      raise ArgumentError, 'invalid url' if url.class != String
+      raise ArgumentError, 'empty url' if url.empty?
+
+      URI::unescape(url)
+    end
+
+    def self.encoded?(url)
+      raise ArgumentError, 'nil url' if url.nil?
+      raise ArgumentError, 'invalid url' if url.class != String
+      raise ArgumentError, 'empty url' if url.empty?
+
+      return (url =~ /%/) ? true : false
+    end
+  end
+end
+
+raise RuntimeError, 'This library is for require only' if $0 == __FILE__

data/lib/rcl/xml.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+# xml.rb
+# yesmar@speakeasy.net
+
+require 'rexml/document'
+require 'rexml/validation/relaxng'
+
+require 'perms'
+
+module RCL
+  module XML
+    # remove leading and trailing whitespace from elements
+    def self.preprocess(pathname)
+      Perms::check_file_r(pathname)
+
+      doc = IO.readlines(pathname)
+
+      doc.each do |line|
+        line.gsub!(/\s+</, '<')
+        line.gsub!(/\s+$/, '')
+      end
+
+      doc.join
+    end
+
+    # validate XML document against specified RELAXNG schema
+    def self.validate(pathname, schema_pathname=nil)
+      Perms::check_file_r(pathname)
+
+      if schema_pathname.nil?
+        schema_pathname = \
+          "#{File.basename(pathname, File.extname(pathname))}.xsd"
+      end
+
+      Perms::check_file_r(schema_pathname)
+
+      begin
+        schema = File.new(schema_pathname)
+        validator = REXML::Validation::RelaxNG.new(schema)
+        parser = REXML::Parsers::TreeParser.new(preprocess(pathname))
+        parser.add_listener(validator.reset)
+        parser.parse
+      rescue REXML::Validation::ValidationException => e
+        raise "#{e}"
+      rescue Exception => e
+        raise "#{e}"
+      end
+
+      true
+    end
+  end
+end
+
+raise RuntimeError, 'This library is for require only' if $0 == __FILE__

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: rcl
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Ramsey Dow
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-02-27 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: 
+email: yesmar @nospam@ speakeasy.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/rcl.rb
+- lib/rcl/base.rb
+- lib/rcl/perms.rb
+- lib/rcl/shell.rb
+- lib/rcl/timestamp.rb
+- lib/rcl/token.rb
+- lib/rcl/url.rb
+- lib/rcl/xml.rb
+- README
+has_rdoc: true
+homepage: http://rcl.rubyforge.org/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: http://rubyforge.org/projects/rcl/
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Ramsey's Common Library
+test_files: []
+