TwP-webby 0.9.0

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.dir]
+
+    # 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.dir].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.dir}/[^/]+"
+
+    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.dir
+
+    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/file.rb

@@ -0,0 +1,221 @@
+require 'yaml'
+
+module Webby::Resources
+
+# The Webby::Resources::File class is identical to the core Ruby file class
+# except for YAML meta-data stored at the top of the file. This meta-data
+# is made available through the <code>meta_data</code> and
+# <code>meta_data=</code> functions.
+#
+# 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 File < ::File
+
+  META_SEP = %r/\A---\s*\r?\n\z/o   # :nodoc:
+
+  class << self
+    # call-seq:
+    #    File.read( name [, length [, offset]])    => string
+    #
+    # Opens the file, optionally seeks to the given _offset_, then returns
+    # _length_ bytes (defaulting to the rest of the file). +read+ ensures
+    # the file is closed before returning.
+    #
+    def read( name, *args )
+      fd = new name, 'r'
+      fd.read(*args)
+    ensure
+      fd.close unless fd.nil?
+    end
+
+    # call-seq:
+    #    File.readlines( name, sep_string = $/ )    => array
+    #
+    # Reads the entire file specified by _name_ as individual lines, and
+    # returns those lines in an array. Lines are separated by _sep_string_.
+    # +readlines+ ensures the file is closed before returning.
+    #
+    def readlines( name, sep = $/ )
+      fd = new name, 'r'
+      fd.readlines sep
+    ensure
+      fd.close unless fd.nil?
+    end
+
+    # call-seq:
+    #    File.meta_data( name )    => object or nil
+    #
+    # Reads the meta-data from the file specified by _name_. +meta_data+
+    # ensures the files is closed before returning.
+    #
+    def meta_data( name )
+      fd = new name, 'r'
+      fd.meta_data
+    ensure
+      fd.close unless fd.nil?
+    end
+
+    # call-seq:
+    #    File.dirname( filename )    => dir_name
+    #
+    # Returns all components of the _filename_ except the last one. The
+    # filename must be formed using forward slashes ("/") regardless of the
+    # separator used on the local file system.
+    #
+    def dirname( fn )
+      ::File.dirname(fn).sub(%r/\A[^\/]+\/?/o, '')
+    end
+
+    # call-seq:
+    #    File.basename( filename )    => base_name
+    #
+    # Returns the last component of the _filename_, which must be formed
+    # using forward slashes ("/"regardless of the separator used on the
+    # local file system. The suffix is removed from the filename.
+    #
+    def basename( fn )
+      ::File.basename(fn, '.*')
+    end
+
+    # call-seq:
+    #    File.extname( filename )    => ext_name
+    #
+    # Returns the extension (the portion of file name in path after the
+    # period). This method excludes the period from the extension name.
+    #
+    def extname( fn )
+      ::File.extname(fn).tr('.', '')
+    end
+  end
+
+  # call-seq:
+  #    File.new( filename, mode = "r" )          => file
+  #    File.new( filename [, mode [, perm]] )    => file
+  #
+  # Opens the file named by _filename_ according to _mode_ (default is 'r')
+  # and returns a new +Webby::Resources::File+ object. See the description
+  # of class +IO+ for a description of _mode_. The file _mode_ may
+  # optionally be specified as a +Fixnum+ by or-ing together the flags
+  # (+O_RDONLY+ etc, again described under +IO+). Optional permission bits
+  # may be given in _perm_. These _mode_ and permission bits are platform
+  # dependent; on Unix systems, see +open(2)+ for details. 
+  #
+  #    f = File.new("testfile", "r")
+  #    f = File.new("newfile",  "w+")
+  #    f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)
+  #
+  def initialize( *args )
+    super
+    @meta_end = end_of_meta_data
+  end
+
+  # call-seq:
+  #    meta_data
+  #
+  # 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?
+
+    cur, meta_end, @meta_end = tell, @meta_end, nil
+    seek 0
+    return YAML.load(self)
+
+  ensure
+    @meta_end = meta_end if defined? meta_end and meta_end
+    seek cur if defined? cur and cur
+  end
+
+  # call-seq
+  #    meta_data = object
+  #
+  # Stores the given _object_ as meta-data in YAML format at the top of the
+  # file. If the _objectc_ is +nil+, then the meta-data section will be
+  # removed from the file.
+  #
+  # Meta-data is stored in YAML format between two YAML separators "---" on
+  # their own lines.
+  #
+  def meta_data=( data )
+    return if data.nil? and @meta_end.nil?
+
+    seek 0
+    lines = readlines
+
+    truncate 0
+    unless data.nil?
+      write YAML.dump(data)
+      write "--- #$/"
+    end
+    lines.each {|line| write line}
+  ensure
+    @meta_end = end_of_meta_data
+    seek 0, IO::SEEK_END
+  end
+
+  alias :_gets :gets
+  private :_gets
+
+  %w(getc gets read read_nonblock readbytes readchar readline readlines readpartial scanf).each do |m|
+    self.class_eval <<-CODE
+      def #{m}(*a)
+        skip_meta_data
+        super
+      end
+    CODE
+  end
+
+
+  private
+
+  # Moves the file pointer to the end of the meta-data section. Does nothing
+  # if there is no meta-data section or if the file pointer is already past
+  # the meta-data section.
+  #
+  def skip_meta_data
+    return if @meta_end.nil? 
+    return if tell >= @meta_end
+    seek @meta_end
+  end
+
+  # Returns the position in this file where the meta-data ends and the file
+  # data begins. If there is no meta-data in the file, returns +nil+.
+  #
+  def end_of_meta_data
+    cur = tell
+
+    seek 0
+    line = _gets
+    return unless META_SEP =~ line
+
+    while line = _gets
+      break if META_SEP =~ line
+    end
+    return if line.nil?
+    tell
+
+  ensure
+    seek cur
+  end
+
+end  # class File
+end  # module Webby::Resources
+
+# EOF

data/lib/webby/resources/layout.rb

@@ -0,0 +1,63 @@
+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
+
+    @mdata = ::Webby::Resources::File.meta_data(@path)
+    @mdata ||= {}
+    @mdata.sanitize!
+  end
+
+  # call-seq:
+  #    destination    => string
+  #
+  # 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
+
+  # call-seq:
+  #    extension    => string or nil
+  #
+  # 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 @mdata['extension'] if @mdata.has_key? 'extension'
+
+    if @mdata.has_key? 'layout'
+      lyt = ::Webby::Resources.find_layout(@mdata['layout'])
+      ext = lyt ? lyt.extension : nil
+    end
+  end
+
+  # call-seq:
+  #    url    => nil
+  #
+  # 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/page.rb

@@ -0,0 +1,118 @@
+require Webby.libpath(*%w[webby resources resource])
+
+module Webby::Resources
+
+# A Page is a file in the content folder that contains YAML meta-data at
+# the top of the file. Pages are processed by the Webby rendering engine
+# and then inserted into the desired layout. The string resulting from
+# processing and layout is then written to the output directory.
+#
+class Page < Resource
+
+  # Resource page number (if needed)
+  attr_reader :number
+
+  # call-seq:
+  #    Resource.new( path )
+  #
+  # Creates a new page object from the full path to the page file.
+  #
+  def initialize( fn )
+    super
+    @number = nil
+
+    @mdata = ::Webby::Resources::File.meta_data(@path)
+    @mdata ||= {}
+    @mdata = ::Webby.site.page_defaults.merge(@mdata)
+    @mdata.sanitize!
+  end
+
+  # call-seq:
+  #    render   => string
+  #
+  # This method is being deprecated. Please use the +Renderer#render+ method
+  # instead.
+  #
+  def render( renderer = nil )
+    Webby.deprecated "render", "it is being replaced by the Renderer#render() method"
+    renderer ||= ::Webby::Renderer.new(self)
+    renderer._render_page
+  end
+
+  # call-seq
+  #    url    => string or nil
+  #
+  # Returns a string suitable for use as a URL linking to this page. Nil
+  # is returned for layouts.
+  #
+  def url
+    return @url if defined? @url and @url
+
+    @url = destination.sub(::Webby.site.output_dir, '')
+    @url = File.dirname(@url) if filename == 'index' and number.nil?
+    @url
+  end
+
+  # call-seq:
+  #    page.number = Integer
+  #
+  # Sets the page number for the current resource to the given integer. This
+  # number is used to modify the output destination for resources that
+  # require pagination.
+  #
+  def number=( num )
+    @number = num
+    @url = @dest = nil
+  end
+
+  # call-seq:
+  #    destination    => string
+  #
+  # Returns the path in the output directory where the rendered page should
+  # be stored. This path is used to determine if the page is dirty and in
+  # need of rendering.
+  #
+  # The destination for a page can be overridden by explicitly setting
+  # the 'destination' property in the page's meta-data.
+  #
+  def destination
+    return @dest if defined? @dest and @dest
+
+    @dest = if @mdata.has_key? 'destination' then @mdata['destination']
+            else ::File.join(dir, filename) end
+
+    @dest = ::File.join(::Webby.site.output_dir, @dest)
+    @dest << @number.to_s if @number
+
+    ext = extension
+    unless ext.nil? or ext.empty?
+      @dest << '.' << ext
+    end
+    @dest
+  end
+
+  # call-seq:
+  #    extension    => string
+  #
+  # Returns the extension that will be appended to the output destination
+  # filename. The extension is determined by looking at the following:
+  #
+  # * this page's meta-data for an 'extension' property
+  # * the meta-data of this page's layout for an 'extension' property
+  # * the extension of this page file
+  #
+  def extension
+    return @mdata['extension'] if @mdata.has_key? 'extension'
+
+    if @mdata.has_key? 'layout'
+      lyt = ::Webby::Resources.find_layout(@mdata['layout'])
+      ext = lyt ? lyt.extension : nil
+      return ext if ext
+    end
+    @ext
+  end
+
+end  # class Page
+end  # module Webby::Resources
+
+# EOF