francois-webby 0.9.4.1

data/lib/webby/resources/db.rb

@@ -0,0 +1,251 @@
+module Webby::Resources
+
+# A rudimentary "database" for holding resource objects and finding them.
+# The database is held in a Ruby hash keyed by the directories in the
+# content folder.
+#
+class DB
+
+  # call-seq:
+  #    DB.new
+  #
+  # Create a new resources database object. This is used to store resources
+  # and to find them by their attributes.
+  #
+  def initialize
+    @db = Hash.new {|h,k| h[k] = []}
+  end
+
+  # call-seq:
+  #    add( resource )    => resource
+  #
+  # Add the given _resource_ to the database. It will not be added a second
+  # time if it already exists in the database.
+  #
+  def add( page )
+    ary = @db[page.directory]
+
+    # make sure we don't duplicate pages
+    ary.delete page if ary.include? page
+    ary << page
+
+    page
+  end
+  alias :<< :add
+
+  # call-seq:
+  #    clear    => self
+  #
+  # Removes all resources from the database.
+  #
+  def clear
+    @db.clear
+    self
+  end
+
+  # call-seq:
+  #    each {|resource| block}
+  #
+  # Iterate over each resource in the database and pass it to the given
+  # block.
+  #
+  def each( &block )
+    keys = @db.keys.sort
+    keys.each do |k|
+      @db[k].sort.each(&block)
+    end
+    self
+  end
+
+  # call-seq:
+  #    find( limit = nil, opts = {} )                       => resource or nil
+  #    find( limit = nil, opts = {} ) {|resource| block}    => resource or nil
+  #
+  # Find a specific resource or collection of resources in the pages database.
+  # The first resource found will be returned if the _limit_ is nil. If the
+  # _limit_ is an integer, then up to that number of resources will be
+  # returned as an array. If the limit is :all, then all resources matching
+  # the given attributes will be returned.
+  #
+  # Resources can be found using any combination of attributes by passing them
+  # in as options to the +find+ method. This will used simple equality
+  # comparison to find the resource or resources.
+  # 
+  # If the :include option is given as :all then all resources that match
+  # the finder criteria will be returned in an array. If none are found, an
+  # empty array will be returned. If the :include option is given as an
+  # integer then the first n resources found will be returned. Otherwise, or
+  # if the :include option is not given, the first resource found will be
+  # returned
+  # 
+  # For more complex finders, a block should be supplied. The usage follows
+  # that of of the Enumerable#find or Enumerable#find_all methods, depending
+  # on the limit. The method will return the first resource or all
+  # resources, respectively, for which the block returns true.
+  # 
+  # ==== Options
+  # :in_directory<String>::
+  #   The directory to search.
+  # :recursive<Boolean>::
+  #   Whether or not to recurse into subdirectories
+  # :sort_by<Symbol>::
+  #   Sort results using the given attribute
+  # :reverse<Boolean>::
+  #   Reverse the order of the search results
+  #
+  # ==== Examples
+  #    # find the "index" resource in the "foo/bar" directory
+  #    @pages.find( :filename => 'index', :in_directory => 'foo/bar' )
+  #
+  #    # find all resources under the "foo/bar" directory recursively
+  #    @pages.find( :all, :in_directory => 'foo/bar', :recursive => true )
+  #
+  #    # find the resource named "widgets" whose color is "blue"
+  #    @pages.find( :name => 'widgets', :color => 'blue' )
+  #
+  #    # find all resources created in the past week
+  #    @pages.find( :all ) do |resource|
+  #      resource.created_at > Time.now - (7 * 24 * 3600)
+  #    end
+  #
+  def find( *args, &block )
+    opts = Hash === args.last ? args.pop : {}
+
+    limit = args.shift
+    limit = opts.delete(:limit) if opts.has_key?(:limit)
+    sort_by = opts.delete(:sort_by)
+    reverse = opts.delete(:reverse)
+
+    # figure out which directories to search through and whether to recurse
+    # into directories or not
+    search = if (dir = opts.delete(:in_directory))
+      dir = dir.sub(%r/^\//, '')
+      strategy = if opts.delete(:recursive)
+        rgxp = dir.empty? ? '.*' : Regexp.escape(dir)
+        lambda { |key| key =~ %r/^#{rgxp}(\/.*)?$/ }
+      else
+        lambda { |key| key == dir }
+      end
+      matching_keys = @db.keys.select(&strategy)
+      raise RuntimeError, "unknown directory '#{dir}'" if matching_keys.empty?
+      matching_keys.map { |key| @db[key] }.flatten
+    else
+      self
+    end
+
+    # construct a search block if one was not supplied by the user
+    block ||= lambda do |page|
+      found = true
+      opts.each do |key, value|
+        found &&= page.__send__(key.to_sym) == value
+        break if not found
+      end
+      found
+    end
+    
+    # search through the directories for the desired pages
+    ary = []
+    search.each do |page|
+      ary << page if block.call(page)
+    end
+
+    # sort the search results if the user gave an attribute to sort by
+    if sort_by
+      m = sort_by.to_sym
+      ary.delete_if {|p| p.__send__(m).nil?}
+      reverse ? 
+          ary.sort! {|a,b| b.__send__(m) <=> a.__send__(m)} :
+          ary.sort! {|a,b| a.__send__(m) <=> b.__send__(m)} 
+    end
+
+    # limit the search results
+    case limit
+    when :all, 'all'
+      ary
+    when Integer
+      ary.slice(0,limit)
+    else
+      ary.first
+    end
+  end
+
+  # call-seq:
+  #    siblings( page, opts = {} )    => array
+  #
+  # Returns an array of resources that are siblings of the given _page_
+  # resource. A sibling is any resource that is in the same directory as the
+  # _page_.
+  #
+  # ==== Options
+  # :sorty_by<Symbol>::
+  #   The attribute to sort by
+  # :reverse<Boolean>::
+  #   Reverse the order of the results
+  #
+  def siblings( page, opts = {} )
+    ary = @db[page.directory].dup
+    ary.delete page
+    return ary unless opts.has_key? :sort_by
+
+    m = opts[:sort_by]
+    ary.sort! {|a,b| a.__send__(m) <=> b.__send__(m)}
+    ary.reverse! if opts[:reverse]
+    ary
+  end
+
+  # call-seq:
+  #    children( page, opts = {} )    => array
+  #
+  # Returns an array of resources that are children of the given _page_
+  # resource. A child is any resource that exists in a subdirectory of the
+  # page's directory.
+  #
+  # ==== Options
+  # :sorty_by<Symbol>::
+  #   The attribute to sort by
+  # :reverse<Boolean>::
+  #   Reverse the order of the results
+  #
+  def children( page, opts = {} )
+    rgxp = Regexp.new "\\A#{page.directory}/[^/]+"
+
+    keys = @db.keys.find_all {|k| rgxp =~ k}
+    ary  = keys.map {|k| @db[k]}
+    ary.flatten!
+
+    return ary unless opts.has_key? :sort_by
+
+    m = opts[:sort_by]
+    ary.sort! {|a,b| a.__send__(m) <=> b.__send__(m)}
+    ary.reverse! if opts[:reverse]
+    ary
+  end
+
+  # call-seq:
+  #    parent_of( resource )    => resource or nil
+  #
+  #  Returns the parent page of the given resource or nil if the resource is
+  #  at the root of the directory structure. The parent is the "index" page
+  #  of the current directory or the next directory up the chain.
+  #
+  def parent_of( page )
+    dir = page.directory
+
+    loop do
+      if @db.has_key? dir
+        parent = @db[dir].find {|p| p.filename == 'index'}
+        return parent unless parent.nil? or parent == page
+      end
+
+      break if dir.empty?
+      dir = ::File.dirname(dir)
+      dir = '' if dir == '.'
+    end
+
+    return
+  end
+
+end  # class DB
+end  # module Webby
+
+# EOF

data/lib/webby/resources/layout.rb

@@ -0,0 +1,54 @@
+require Webby.libpath(*%w[webby resources resource])
+
+module Webby::Resources
+
+# A Layout is any file that is found in the layout folder of the webiste
+# directory. Layouts container the common elements of all the pages in a
+# website, and pages from the content folder are rendered into the layout.
+#
+class Layout < Resource
+
+  # call-seq:
+  #    Layout.new( path )
+  #
+  # Creates a new Layout object given the full path to the layout file.
+  #
+  def initialize( fn )
+    super
+
+    @_meta_data = MetaFile.meta_data(@path)
+    @_meta_data ||= {}
+    @_meta_data.sanitize!
+  end
+
+  # Returns the extension to be applied to output files rendered by the
+  # layotut. This will either be a string or +nil+ if the layout does not
+  # specify an extension to use.
+  #
+  def extension
+    return _meta_data['extension'] if _meta_data.has_key? 'extension'
+
+    if _meta_data.has_key? 'layout'
+      lyt = ::Webby::Resources.find_layout(_meta_data['layout'])
+      lyt ? lyt.extension : nil
+    end
+  end
+
+  # The output file destination for the layout. This is the ".cairn" file in
+  # the output folder. It is used to determine if the layout is newer than
+  # the build products.
+  #
+  def destination
+    ::Webby.cairn
+  end
+
+  # Layouts do not have a URL. This method will alwasy return +nil+.
+  #
+  def url
+    nil
+  end
+
+end  # class Layout
+end  # module Webby::Resources
+
+# EOF

data/lib/webby/resources/meta_file.rb

@@ -0,0 +1,211 @@
+require 'yaml'
+
+module Webby::Resources
+
+# The MetaFile class is used to read meta-data and content from files. The
+# meta-data is in a YAML block located at the top of the file. The content
+# is the remainder of the file (everything after the YAML block).
+#
+# The meta-data data must be found between two YAML block separators "---",
+# each on their own line.
+#
+# Example:
+#
+#     ---
+#     layout: blog
+#     filter: markdown
+#     tags:
+#       - ruby
+#       - web development
+#     ---
+#     This is a blog entry formatted using MarkDown and tagged as "ruby" and
+#     "web development". The layout being used is the "blog" format.
+#
+class MetaFile
+
+  class Error < StandardError; end
+
+  META_SEP = %r/\A---\s*(?:\r\n|\n)?\z/   # :nodoc:
+  ERR_MSG = "corrupt meta-data (perhaps there is an errant YAML marker '---' in the file)" # :nodoc:
+
+  # call-seq:
+  #    MetaFile.read( filename )    => string
+  #
+  # Opens the file identified by _filename_ and returns the contents of the
+  # file as a string. Any meta-data at the top of the file is skipped and
+  # is not included in the returned string. If the file contains no
+  # meta-data, then this method behaves the same as File#read.
+  #
+  def self.read( name )
+    ::File.open(name, 'r') {|fd| MetaFile.new(fd).read}
+  end
+
+  # call-seq:
+  #    MetaFile.meta_data( filename )    => object or nil
+  #
+  # Opens the file identified by _filename_ and returns the meta-data
+  # located at the top of the file. If the file contains no meta-data, then
+  # +nil+ is returned.
+  #
+  def self.meta_data( name )
+    ::File.open(name, 'r') {|fd| MetaFile.new(fd).meta_data}
+  end
+
+  # call-seq:
+  #    MetaFile.meta_data?( filename )    => true or false
+  #
+  # Opens the file identified by _filename_ and returns true if there is a
+  # meta-data block at the top of the file, and returns false if there is
+  # not a meta-data block at the top of the file.
+  #
+  def self.meta_data?( name )
+    ::File.open(name, 'r') {|fd| MetaFile.new(fd).meta_data?}
+  end
+
+  # Creates a new MetaFile parser that will read from the given _io_ stream.
+  #
+  def initialize( io )
+    raise ArgumentError, "expecting an IO stream" unless io.respond_to? :gets
+    @io = io
+    @meta_count = 0
+  end
+
+  # Returns the entire contents of the IO stream exluding any meta-data
+  # found at the beginning of the stream.
+  #
+  def read
+    count = meta_end
+    @io.seek 0
+    count.times {@io.gets} unless count.nil?
+    @io.read
+  end
+
+  # Reads in each meta-data section and yields it to the given block. The
+  # first meta-data section is yielded "as is", but subsequent meta-data
+  # sections are merged with this first section and then yielded. This
+  # allows the user to define common items in the first meta-data section
+  # and only include items that are different in the subsequent sections.
+  #
+  # Example:
+  #
+  #    ---
+  #    title:      First Title
+  #    author:     me
+  #    directory:  foo/bar/baz
+  #    ---
+  #    title:      Second Title
+  #    author:     you
+  #    ---
+  #    title:      Third Title
+  #    author:     them
+  #    ---
+  #
+  # and parsing the meta-data above yields ...
+  #
+  #    meta_file.each do |hash|
+  #      pp hash
+  #    end
+  #
+  # the following output
+  #
+  #    { 'title' => 'First Title',
+  #      'author' => 'me',
+  #      'directory' => 'foo/bar/baz' }
+  #
+  #    { 'title' => 'Second Title',
+  #      'author' => 'you',
+  #      'directory' => 'foo/bar/baz' }
+  #
+  #    { 'title' => 'Third Title',
+  #      'author' => 'them',
+  #      'directory' => 'foo/bar/baz' }
+  #
+  # Even though the "directory" item only appears in the first meta-data
+  # block, it is copied to all the subsequent blocks.
+  #
+  def each
+    return unless meta_data?
+
+    first, count = nil, 0
+    @io.seek 0
+
+    buffer = @io.gets
+    while count < @meta_count
+      while (line = @io.gets) !~ META_SEP
+        buffer << line
+      end
+
+      h = YAML.load(buffer)
+      raise Error, ERR_MSG unless h.instance_of?(Hash)
+
+      if first then h = first.merge(h)
+      else first = h.dup end
+
+      buffer = line
+      count += 1
+
+      yield h
+    end
+  rescue ArgumentError => err
+    msg = ERR_MSG.dup << "\n\t-- " << err.message
+    raise Error, msg
+  end
+
+  # Returns the meta-data defined at the top of the file. Returns +nil+ if
+  # no meta-data is defined. The meta-data is returned as Ruby objects
+  #
+  # Meta-data is stored in YAML format between two YAML separators "---" on
+  # their own lines.
+  #
+  def meta_data
+    return if meta_end.nil?
+
+    @io.seek 0
+    return YAML.load(@io)
+  end
+
+  # Returns true if the IO stream contains meta-data. Returns false if the
+  # IO stream does not contain meta-data.
+  #
+  def meta_data?
+    meta_end.nil? ? false : true
+  end
+
+  # Returns the number of meta-data blocks at the top of the file.
+  #
+  def meta_count
+    meta_end
+    @meta_count
+  end
+
+  # Returns the position in the IO stream where the meta-data ends and the
+  # regular data begins. If there is no meta-data in the stream, returns +nil+.
+  #
+  def meta_end
+    return @meta_end if defined? @meta_end
+    @meta_end = nil
+
+    @io.seek 0
+    line = @io.read(4)
+    return unless META_SEP =~ line
+
+    @io.seek 0
+    @io.gets
+    pos, count = nil, 1
+
+    while line = @io.gets
+      count += 1
+      if META_SEP =~ line
+        pos = count
+        @meta_count += 1
+      end
+    end
+    return if pos.nil?
+
+    @meta_end = pos
+  end
+
+end  # class MetaFile
+end  # module Webby::Resources
+
+# EOF