bijou 0.1.0

data/lib/bijou/processor.rb

@@ -0,0 +1,404 @@
+#
+# Copyright (c) 2007-2008 Todd Lucas. All rights reserved.
+#
+# processor.rb - The Bijou component loader and runtime dispatcher
+#
+require 'fileutils'
+require 'digest/sha1'
+require 'bijou/common'
+require 'bijou/exception'
+require 'bijou/config'
+require 'bijou/parser'
+require 'bijou/context'
+require 'bijou/exception'
+require 'bijou/errorformatter'
+
+module Bijou
+  #
+  # The processor encapsulates the loading and parsing of a component class and
+  # any referenced containers or components.
+  #
+  class Processor
+    ComponentPrefix = 'Component_'
+    CacheSuffix = '_cache'
+    CacheSubdir = 'cache'
+    PathSepRE = /\/|\\/
+
+    def initialize()
+      @trace = false
+    end
+
+    # Returns true if the file is cached and the cache is fresh.
+    def cache_check(config, filename, cachename)
+      if !config.cache
+        # Don't cache anything
+        trace "don't cache"
+        return false
+      end
+      
+      return !Processor.is_cache_stale(filename, cachename)
+    end
+
+    def trace(msg)
+      puts msg if @trace
+    end
+
+    # Returns a cache directory based on the configuration.
+    def get_cache_root(config)
+      if config.cache_root
+        # Store in the cache subdirectory of the cache root. We do this is
+        # in case we need to store additional files.
+        cache_root = File.expand_path('cache', config.cache_root)
+      elsif config.cache_ext
+        # Use the specified extension and store in the document root.
+        cache_root = config.document_root
+      else
+        # Neither specified; create a cache root parallel to the doc root.
+
+        # Strip the trailing slash.
+        cache_root = File.expand_path('', config.document_root)
+
+        # Give it a different path name, parallel to the document root.
+        cache_root << CacheSuffix
+
+        # Store in the cache subdirectory of the cache root. We do this is
+        # in case we need to store additional files.
+        cache_root = File.expand_path('cache', cache_root)
+      end
+
+      return cache_root
+    end
+
+    # Returns true if the file is cached and the cache is fresh.
+    def get_cache_path(config, path)
+      cache_root = get_cache_root(config)
+
+      cache_path = File.expand_path(path, cache_root)
+      if config.cache_ext
+        cache_path << config.cache_ext
+      end
+
+      return cache_path
+    end
+
+    def create_class_object(class_name, context)
+      component_class = eval(class_name)
+      return component_class.new(context)
+    end
+
+    # Handles loading of containers. The context invokes this callback when
+    # a component is loaded and the component has an associated container. The 
+    # context class is environment agnostic and thus doesn't know how to load 
+    # a container. Instead, it delegates the mechanics to the context owner.
+    def load_container_callback(context, path)
+      trace "container_callback #{path}"
+
+      load_component(context, path)
+    end
+
+    # When a component is requested, either directly, by context.invoke, or 
+    # indirectly, using the <& ... &> syntax, the context delegates the loading
+    # of the component to the owner of the context (if the component_callback
+    # was registered).
+    def load_component_callback(context, path, args)
+      trace "component_callback #{path}"
+
+      subcontext = context.clone
+
+      load_component(subcontext, path)
+
+      subcontext.render(args)
+      return subcontext.output
+    end
+
+    # This is the workhorse of the processor. It utilizes several classes,
+    # including the parser, to load and parse a component in preparation for
+    # rendering. The return value is a Context object that may be used to
+    # render the component one or more times, each with a different set of 
+    # arguments.
+    #
+    # The cfg argument may be either a Bijou::Config or a Bijou::Context.
+    #
+    def load(path, cfg=nil)
+      context = nil
+      config = nil
+
+      # Initialize the context and config.
+      if cfg
+        if cfg.kind_of?(Bijou::Config)
+          config = cfg
+        elsif cfg.kind_of?(Bijou::Context)
+          context = cfg
+          config = context.config
+        else
+          raise "If specified, cfg must be a Context or Config object"
+        end
+      else
+        # Provide a default.
+        config = Bijou::Config.new
+      end
+
+      if !context
+        # Create the top-level context.
+        context = Bijou::Context.new(config)
+      end
+
+      if config.document_root
+        if !File.directory?(config.document_root)
+          raise "The documet_root is not a valid directory."
+        end
+      else
+        # NOTE: This modifies the configuration.
+        config.document_root = Dir.getwd
+      end
+
+      # We want the processor to handle container and component creation.
+      context.container_callback = method(:load_container_callback)
+      context.component_callback = method(:load_component_callback)
+
+      # Load the top-level component as a normal component.
+      load_component(context, path)
+    end
+
+    def load_component(context, path)
+      config = context.config
+
+      if !config.document_root
+        raise "A document_root must be specified"
+      end
+
+      path = path.strip
+
+      # TODO: Consolidate tracing to a single path.
+      trace "load_component #{path}"
+      context.trace(Bijou::Log::Info, "load_component(#{path})")
+
+      # The caller should strip the slash, but we do it here as a safeguard.
+      if path[0,1] =~ PathSepRE
+        path = path[1..-1]
+      end
+
+      filename = File.expand_path(path, config.document_root)
+      trace "filename #{filename}"
+
+      if !File.exists?(filename)
+        raise Bijou::FileNotFound.new(filename), "File not found: #{filename}"
+      end
+
+      classname = Processor.class_from_filename(ComponentPrefix, filename)
+      trace "classname #{classname}"
+
+      # context.trace(Bijou::Log::Info, "get_cache_path #{config.cache_root || ''}");
+      cachename = get_cache_path(config, path)
+      trace "cachename #{cachename}"
+
+      component_class = nil
+
+      if !cache_check(config, filename, cachename)
+        context.trace(Bijou::Log::Info, "parse and load into cache #{cachename}");
+        Processor.ensure_directory_exists_for_file cachename
+
+        parser = Bijou::Parser.new
+
+        trace "parse #{classname}"
+        source_file = File.new(filename)
+        parser.parse_file(classname, source_file, path)
+        source_file.close
+
+        class_text = parser.render(classname, filename, cachename, 
+                                   config.component_base, config.require_list)
+        
+        # Write the new class text to the cache file.
+        if parser.diagnostics.errors.length == 0 && class_text
+          object_file = File.open(cachename, "w")
+          object_file.write(class_text)
+          object_file.close
+        else
+          File.delete(cachename) if File.exist?(cachename)
+          
+          raise Bijou::ParseError.new(filename, parser.diagnostics), 
+          "Parse error for file '#{path}'"
+        end
+      else
+        begin
+          #
+          # If the class is already in memory, avoid hitting the disk.
+          #
+          trace "try read from memory #{classname}"
+          component_object = create_class_object(classname, context)
+
+          context.add_component(component_object)
+        rescue NameError
+          trace "not in memory"
+        end
+
+        if component_object
+          context.trace(Bijou::Log::Info, "  create from memory #{cachename}");
+        else
+          context.trace(Bijou::Log::Info, "  create from cache #{cachename}");
+
+          #
+          # Otherewise, read the class text from the cache.
+          #
+          trace "read from cache #{cachename}"
+
+          object_file = File.open(cachename, "r")
+          class_text = object_file.read
+          object_file.close
+        end
+      end
+
+      if !component_object
+        #
+        # Create component using class text, while putting the definition 
+        # into memory.
+        #
+        trace "create_component"
+        begin
+          component_object = Processor.create_component(context, 
+                                                        class_text, 
+                                                        classname)
+        rescue SyntaxError
+          raise Bijou::EvalError.new(filename, cachename, $!.message),
+          "Syntax error in file '#{path}'"
+        end
+      end
+
+      trace "load finished #{path}"
+
+      # Caller will need to call context.render(args)
+      return context
+    end
+
+    def self.create_component(context, class_text, class_name)
+      #
+      # If the class is already in memory, we'll need to undefine it. 
+      # Otherwise, the new definition would be appended to the old one.
+      #
+      module_name = "Object" # REVIEW: This is the default right now.
+      if Object.const_defined? module_name
+        module_ref = Object.const_get(module_name)
+
+        if module_ref.const_defined? class_name
+          module_ref.remove_const(class_name)
+        end
+      end
+
+      # REVIEW: If we can scope eval, we can use a random name.
+      eval(class_text)
+      component_class = eval(class_name)
+
+      component_object = component_class.new(context)
+      context.add_component(component_object)
+
+      return component_object
+    end
+
+    # A convenience function that parses and renders a class. It will not load
+    # or cache component documents, like load_component, nor will containers or 
+    # components be automatically handled. The caller must set callbacks to 
+    # properly handle these load events.
+    def self.execute(context, class_text, class_name, args={})
+      component_object = self.create_component(context, class_text, class_name)
+
+      context.render(args)
+
+      return context.output
+    end
+
+    # This helper method can be used with certain web server adapters to 
+    # simplify the process of serving normal content types. Many web servers
+    # will delegate specific requests to the Bijou adapter, based on the 
+    # request. Some servers do not delegate based on file name patterns and
+    # thus the adapter must disambiguate and serve such requests.
+    def self.handle_other(config, path_info)
+      content_types = 
+        [
+         [ 'txt',  'text/plain' ],
+         [ 'htm',  'text/html'  ],
+         [ 'html', 'text/html'  ],
+         [ 'css',  'text/css'   ],
+         [ 'gif',  'image/gif'  ],
+         [ 'jpg',  'image/jpeg' ],
+         [ 'jpeg', 'image/jpeg' ],
+         [ 'png',  'image/png'  ],
+         [ 'tif',  'image/tiff' ],
+         [ 'tiff', 'image/tiff' ],
+         [ 'bmp',  'image/x-ms-bmp' ],
+        ]
+
+      path = File.expand_path(path_info, config.document_root)
+
+      content_type = 'text/plain'
+      content_types.each {|type|
+        ext = type[0]
+
+        if path_info =~ /\.#{ext}$/
+          content_type = type[1]
+          break
+        end
+      }
+
+      if File.exists?(path)
+        file = File.new(path, "r")
+        response = {
+          'status' => 200,
+          'type' => content_type,
+          'body' => file.read
+        }
+        file.close
+      else
+        response = {
+          'status' => 404,
+          'type' => content_type,
+          'body' => ''
+        }
+      end
+
+      return response
+    end
+
+    def self.class_from_filename(prefix, filename)
+      return prefix + Digest::SHA1.hexdigest(filename.downcase).downcase
+    end
+
+    def self.is_cache_stale(filename, cachename)
+      parsefile = true
+
+      if !File.exists?(cachename)
+        return true # The file hasn't been cached yet.
+      end
+
+      cachemod = File.stat(cachename).mtime
+
+      if !File.exists?(filename)
+        raise "Source file not found"
+      end
+
+      sourcemod = File.stat(filename).mtime
+
+      if sourcemod <= cachemod
+        # The file has been cached and the source hasn't been touched.
+        return false
+      end
+
+      # The cached file is older than the source.
+      return true
+    end
+
+    def self.ensure_directory_exists_for_file filename
+      if filename !~ PathSepRE
+        raise "Invalid filename"
+      end
+
+      n = filename.rindex(PathSepRE)
+      path = filename[0, n]
+
+      if !File.directory?(path)
+        # NOTE: mkdir_p works with or without a / terminator.
+        FileUtils.mkdir_p(path)
+      end
+    end
+
+  end
+end

data/lib/bijou/prstringio.rb

@@ -0,0 +1,400 @@
+#
+# This file is is not part of Bijou, but is included as a helper for Ruby
+# installations without stringio.
+#
+# Reference: http://rubyforge.org/projects/prstringio/
+#
+# Original comment:
+#
+# To load this in emergency situations when loading StringIO fails then use the following:
+#       begin
+#           require 'stringio'
+#       rescue LoadError
+#           require 'purerubystringio'      #or just put this entire file in your code at this point.
+#       end
+# If you need stringio and you know for sure it isn't going to be available then you can easily fake it 
+# without changing your existing code. Just add the following before the rest of your code starts.
+# class StringIO < PureSybyStringIO
+# end
+# Any code that uses StringIO.new will now work. So will any subclass definitions. If you are only subclassing
+# StringIO and you are willing to make small changes to you code you can change your class definitions to:
+#       class MyClass < Object.const_defined?(:StringIO) ? StringIO : PureRubyStringIO
+#              ...
+#       end
+# That will automatically select which ever is avaialable at the time. Savy coders, by now, will have begin
+# to consider the delegator mixin. I'll leave that exercise for you to finish. ;)
+class PureRubyStringIO # :nodoc:
+
+	include Enumerable
+
+	SEEK_CUR = IO::SEEK_CUR
+	SEEK_END = IO::SEEK_END
+	SEEK_SET = IO::SEEK_SET
+
+	@@relayMethods = [:<<, :all?, :any?, :binmode, :close, :close_read, :close_write, :closed?, :closed_read?,
+	                  :closed_write?, :collect, :detect, :each, :each_byte, :each_line, :each_with_index,
+	                  :entries, :eof, :eof?, :fcntl, :fileno, :find, :find_all, :flush, :fsync, :getc, :gets,
+	                  :grep, :include?, :inject, :isatty, :length, :lineno, :lineno=, :map, :max, :member?,
+	                  :min, :partition, :path, :pid, :pos, :pos=, :print, :printf, :putc, :puts, :read,
+	                  :readchar, :readline, :readlines, :reject, :rewind, :seek, :select, :size, :sort,
+	                  :sort_by, :string, :string=, :sync, :sync=, :sysread, :syswrite, :tell, :truncate, :tty?,
+	                  :ungetc, :write, :zip]
+
+	def self.open(string="", mode="r+")
+		if block_given? then
+			sio = new(string, mode)
+			rc = yield(sio)
+			sio.close
+			rc
+		else
+			new(string, mode)
+		end
+	end
+
+	def <<(obj)
+		requireWritable
+		write obj
+		self
+	end
+
+	def binmode
+		self
+	end
+
+	def close
+		requireOpen
+		@sio_closed_read = true
+		@sio_closed_write = true
+		self
+	end
+
+	def close_read
+		raise IOError, "closing non-duplex IO for reading", caller if closed_read?
+		@sio_closed_read = true
+		self
+	end
+
+	def close_write
+		raise IOError, "closing non-duplex IO for writing", caller if closed_write?
+		@sio_closed_read = true
+		self
+	end
+
+	def closed?
+		closed_read? && closed_write?
+	end
+
+	def closed_read?
+		@sio_closed_read
+	end
+
+	def closed_write?
+		@sio_closed_write
+	end
+
+	def each(sep_string=$/, &block)
+		requireReadable
+		@sio_string.each(sep_string, &block)
+		@sio_pos = @sio_string.length
+	end
+
+	def each_byte(&block)
+		requireReadable
+		@sio_string.each_byte(&block)
+		@sio_pos = @sio_string.length
+	end
+
+	def eof
+		requireReadable { @sio_pos >= @sio_string.length }
+	end
+
+	def fcntl(integer_cmd, arg)
+		raise NotImplementedError, "The fcntl() function is unimplemented on this machine", caller
+	end
+
+	def fileno
+		nil
+	end
+
+	def flush
+		self
+	end
+
+	def fsync
+		0
+	end
+
+	def getc
+		requireReadable
+		char = @sio_string[@sio_pos]
+		@sio_pos +=  1 unless char.nil?
+		char
+	end
+
+	def gets(sep_string=$/)
+		requireReadable
+		@sio_lineno += 1
+		pstart = @sio_pos
+		@sio_pos = @sio_string.index(sep_string, @sio_pos) || [@sio_string.length, @sio_pos].max
+		@sio_string[pstart..@sio_pos]
+	end
+
+	def initialize(string="", mode="r+")
+		@sio_string = string.to_s
+		@sio_lineno = 0
+		@mode = mode
+		@relay = nil
+		case mode.delete("b")
+		when "r"
+			@sio_closed_read = false
+			@sio_closed_write = true
+			@sio_pos = 0
+		when "r+"
+			@sio_closed_read = false
+			@sio_closed_write = false
+			@sio_pos = 0
+		when "w"
+			@sio_closed_read = true
+			@sio_closed_write = false
+			@sio_pos = 0
+			@sio_string.replace("")
+		when "w+"
+			@sio_closed_read = false
+			@sio_closed_write = false
+			@sio_pos = 0
+			@sio_string.replace("")
+		when "a"
+			@sio_closed_read = true
+			@sio_closed_write = false
+			@sio_pos = @sio_string.length
+		when "a+"
+			@sio_closed_read = false
+			@sio_closed_write = false
+			@sio_pos = @sio_string.length
+		else
+			raise ArgumentError, "illegal access mode #{mode}", caller
+		end
+	end
+
+	def isatty
+		flase
+	end
+
+	def length
+		@sio_string.length
+	end
+
+	def lineno
+		@sio_lineno
+	end
+
+	def lineno=(integer)
+		@sio_lineno = integer
+	end
+
+	def path
+		nil
+	end
+
+	def pid
+		nil
+	end
+
+	def pos
+		@sio_pos
+	end
+
+	def pos=(integer)
+		raise Errno::EINVAL, "Invalid argument", caller if integer < 0
+		@sio_pos = integer
+	end
+
+	def print(*args)
+		requireWritable
+		args.unshift($_) if args.empty
+		args.each { |obj| write(obj) }
+		write($\) unless $\.nil?
+		nil
+	end
+
+	def printf(format_string, *args)
+		requireWritable
+		write format(format_string, *args)
+		nil
+	end
+
+	def putc(obj)
+		requireWritable
+		write(obj.is_a?(Numeric) ? sprintf("%c", obj) : obj.to_s[0..0])
+		obj
+	end
+
+	def puts(*args)
+		requireWritable
+		args.unshift("") if args.empty?
+		args.each { |obj|
+			write obj
+			write $/
+		}
+		nil
+	end
+
+	def read(length=nil, buffer=nil)
+		requireReadable
+		len = length || [@sio_string.length - @sio_pos, 0].max
+		raise ArgumentError, "negative length #{len} given", caller if len < 0
+		buffer ||= ""
+		pstart = @sio_pos
+		@sio_pos += len
+		buffer.replace(@sio_string[pstart..@sio_pos])
+		buffer.empty? && !length.nil? ? nil : buffer
+	end
+
+	def readchar
+		requireReadable
+		raise EOFError, "End of file reached", caller if eof?
+		getc
+	end
+
+	def readline
+		requireReadable
+		raise EOFError, "End of file reached", caller if eof?
+		gets
+	end
+
+	def readlines(sep_string=$/)
+		requireReadable
+		raise EOFError, "End of file reached", caller if eof?
+		rc = []
+		until eof
+			rc << gets(sep_string)
+		end
+		rc
+	end
+
+	def reopen(string, mode=nil)
+		if string.is_a?(self.class) then
+			raise ArgumentError, "wrong number of arguments (2 for 1)", caller if !mode.nil?
+			@relay = string
+			instance_eval(%Q{
+				class << self
+					@@relayMethods.each { |name|
+						define_method(name, ObjectSpace._id2ref(#{@relay.object_id}).method(("original_" + name.to_s).to_sym).to_proc)
+					}
+				end
+			})
+		else
+			raise ArgumentError, "wrong number of arguments (1 for 2)", caller if mode.nil?
+			class << self
+				@@relayMethods.each { |name|
+					alias_method(name, "original_#{name}".to_sym)
+					public name
+				}
+				@relay = nil
+			end unless @relay.nil?
+			@sio_string = string.to_s
+			@mode = mode
+		end
+	end
+
+	def rewind
+		@sio_pos = 0
+		@sio_lineno = 0
+	end
+
+	def seek(amount, whence=SEEK_SET)
+		if whence == SEEK_CUR then
+			offset += @sio_pos
+		elsif whence == SEEK_END then
+			offset += size
+		end
+		@sio_pos = offset
+	end
+
+	def string
+		@sio_string
+	end
+	
+	def string=(newstring)
+		@sio_string = newstring
+	end
+
+	def sync
+		true
+	end
+
+	def sync=(boolean)
+		boolean
+	end
+
+	def sysread(length=nil, buffer=nil)
+		requireReadable
+		raise EOFError, "End of file reached", caller if eof?
+		read(length, buffer)
+	end
+
+	def syswrite(string)
+		requireWritable
+		addition = "\000" * (@sio_string.length - @sio_pos) + string.to_s
+		@sio_string[@sio_pos..(addition.length - 1)] = addition
+		@sio_pos +=  addition.size
+		addition.size
+	end
+
+	#In ruby 1.8.4 truncate differs from the docs in two ways.
+	#First, if an integer greater that the length is given then the string is expanded to the new integer
+	#length. As this expansion seems to contain junk characters instead of nulls I suspect this may be a
+	#flaw in the C code which could cause a core dump if abused/used.
+	#Second, the documentation states that  truncate returns 0. It returns the integer instead.
+	#This implementation follows the documentation in the first instance as I suspect this will be fixed
+	#in the C code. In the second instance, it follows the actions of the C code instead of the docs.
+	#This was decided as it causes no immedeate harm and this ruby implentation is to be as compatable
+	#as possible with the C version. Should the C version change to match the docs the ruby version
+	#will be simple to update as well. 
+	def truncate(integer)
+		requireWritable
+		raise Errno::EINVAL, "Invalid argument - negative length", caller if integer < 0
+		@sio_string[[integer, @sio_string.length].max..-1] = ""
+		integer
+	end
+
+	def ungetc(integer)
+		requireWritable
+		if @sio_pos > 0 then
+			@sio_pos -= 1
+# BUGBUG: This wreaks havok with the existing string.
+#			putc(integer)
+#			@sio_pos -= 1
+# We use this as a simple workaround since we're not modifying the stream.
+            @sio_string[@sio_pos] = integer
+		end
+	end
+
+	alias :each_line :each
+	alias :eof? :eof
+	alias :size :length
+	alias :tty? :isatty
+	alias :tell :pos
+	alias :write :syswrite
+
+	protected
+	@@relayMethods.each { |name|
+		alias_method("original_#{name}".to_sym, name)
+		protected "original_#{name}".to_sym
+	}
+
+	private
+
+	def requireReadable
+		raise IOError, "not opened for reading", caller[1..-1] if @sio_closed_read
+	end
+
+	def requireWritable
+		raise IOError, "not opened for writing", caller[1..-1] if @sio_closed_write
+	end
+
+	def requireOpen
+		raise IOError, "closed stream", caller[1..-1] if @sio_closed_read && @sio_closed_write
+	end
+
+end