gollum 1.0.0

data/lib/gollum/page.rb

@@ -0,0 +1,354 @@
+module Gollum
+  class Page
+    include Pagination
+
+    Wiki.page_class = self
+
+    VALID_PAGE_RE = /^(.+)\.(md|mkdn?|mdown|markdown|textile|rdoc|org|creole|re?st(\.txt)?|asciidoc|pod)$/i
+    FORMAT_NAMES = { :markdown => "Markdown",
+                     :textile  => "Textile",
+                     :rdoc     => "RDoc",
+                     :org      => "Org-mode",
+                     :creole   => "Creole",
+                     :rest     => "reStructuredText",
+                     :asciidoc => "AsciiDoc",
+                     :pod      => "Pod" }
+
+    # Checks if a filename has a valid extension understood by GitHub::Markup.
+    #
+    # filename - String filename, like "Home.md".
+    #
+    # Returns the matching String basename of the file without the extension.
+    def self.valid_filename?(filename)
+      filename && filename.to_s =~ VALID_PAGE_RE && $1
+    end
+
+    # Checks if a filename has a valid extension understood by GitHub::Markup.
+    # Also, checks if the filename has no "_" in the front (such as
+    # _Footer.md).
+    #
+    # filename - String filename, like "Home.md".
+    #
+    # Returns the matching String basename of the file without the extension.
+    def self.valid_page_name?(filename)
+      match = valid_filename?(filename)
+      filename =~ /^_/ ? false : match
+    end
+
+    # Public: Initialize a page.
+    #
+    # wiki - The Gollum::Wiki in question.
+    #
+    # Returns a newly initialized Gollum::Page.
+    def initialize(wiki)
+      @wiki = wiki
+      @blob = nil
+    end
+
+    # Public: The on-disk filename of the page including extension.
+    #
+    # Returns the String name.
+    def filename
+      @blob && @blob.name
+    end
+
+    # Public: The canonical page name without extension, and dashes converted 
+    # to spaces.
+    #
+    # Returns the String name.
+    def name
+      filename.split('.')[0..-2].join('.').gsub('-', ' ')
+    end
+
+    # Public: If the first element of a formatted page is an <h1> tag it can
+    # be considered the title of the page and used in the display. If the
+    # first element is NOT an <h1> tag, the title will be constructed from the
+    # filename by stripping the extension and replacing any dashes with
+    # spaces.
+    #
+    # Returns the fully sanitized String title.
+    def title
+      doc = Nokogiri::HTML(%{<div id="gollum-root">} + self.formatted_data + %{</div>})
+
+      header =
+      case self.format
+        when :asciidoc
+          doc.css("div#gollum-root > div#header > h1:first-child")
+        when :org
+          doc.css("div#gollum-root > p.title:first-child")
+        when :pod
+          doc.css("div#gollum-root > a.dummyTopAnchor:first-child + h1")
+        when :rest
+          doc.css("div#gollum-root > div > div > h1:first-child")
+        else
+          doc.css("div#gollum-root > h1:first-child")
+      end
+
+      if !header.empty?
+        Sanitize.clean(header.to_html)
+      else
+        Sanitize.clean(name)
+      end
+    end
+
+    # Public: The path of the page within the repo.
+    #
+    # Returns the String path.
+    attr_reader :path
+
+    # Public: The raw contents of the page.
+    #
+    # Returns the String data.
+    def raw_data
+      @blob && @blob.data
+    end
+
+    # Public: The formatted contents of the page.
+    #
+    # Returns the String data.
+    def formatted_data
+      @blob && Gollum::Markup.new(self).render
+    end
+
+    # Public: The format of the page.
+    #
+    # Returns the Symbol format of the page. One of:
+    #   [ :markdown | :textile | :rdoc | :org | :rest | :asciidoc | :pod |
+    #     :roff ]
+    def format
+      case @blob.name
+        when /\.(md|mkdn?|mdown|markdown)$/i
+          :markdown
+        when /\.(textile)$/i
+          :textile
+        when /\.(rdoc)$/i
+          :rdoc
+        when /\.(org)$/i
+          :org
+        when /\.(creole)$/i
+          :creole
+        when /\.(re?st(\.txt)?)$/i
+          :rest
+        when /\.(asciidoc)$/i
+          :asciidoc
+        when /\.(pod)$/i
+          :pod
+        when /\.(\d)$/i
+          :roff
+        else
+          nil
+      end
+    end
+
+    # Public: The current version of the page.
+    #
+    # Returns the Grit::Commit.
+    attr_reader :version
+
+    # Public: All of the versions that have touched the Page.
+    #
+    # options - The options Hash:
+    #           :page     - The Integer page number (default: 1).
+    #           :per_page - The Integer max count of items to return.
+    #           :follow   - Follow's a file across renames, but falls back 
+    #                       to a slower Grit native call.  (default: false)
+    #
+    # Returns an Array of Grit::Commit.
+    def versions(options = {})
+      if options[:follow]
+        options[:pretty] = 'raw'
+        options.delete :max_count
+        options.delete :skip
+        log = @wiki.repo.git.native "log", options, "master", "--", @path
+        Grit::Commit.list_from_string(@wiki.repo, log)
+      else
+        @wiki.repo.log('master', @path, log_pagination_options(options))
+      end
+    end
+
+    # Public: The footer Page.
+    #
+    # Returns the footer Page or nil if none exists.
+    def footer
+      return nil if page_match('_Footer', self.filename)
+
+      dirs = self.path.split('/')
+      dirs.pop
+      while !dirs.empty?
+        tree = self.version.tree / dirs.join('/')
+        if page = find_page_in_this_tree(tree, dirs.join('/'), '_Footer')
+          return page
+        end
+        dirs.pop
+      end
+
+      tree = self.version.tree
+      if page = find_page_in_this_tree(tree, '', '_Footer')
+        return page
+      end
+
+      return nil
+    end
+
+    #########################################################################
+    #
+    # Class Methods
+    #
+    #########################################################################
+
+    # Convert a human page name into a canonical page name.
+    #
+    # name - The String human page name.
+    #
+    # Examples
+    #
+    #   Page.cname("Bilbo Baggins")
+    #   # => 'Bilbo-Baggins'
+    #
+    # Returns the String canonical name.
+    def self.cname(name)
+      name.gsub(%r{[ /<>]}, '-')
+    end
+
+    # Convert a format Symbol into an extension String.
+    #
+    # format - The format Symbol.
+    #
+    # Returns the String extension (no leading period).
+    def self.format_to_ext(format)
+      case format
+        when :markdown then 'md'
+        when :textile  then 'textile'
+        when :rdoc     then 'rdoc'
+        when :org      then 'org'
+        when :creole   then 'creole'
+        when :rest     then 'rest'
+        when :asciidoc then 'asciidoc'
+        when :pod      then 'pod'
+      end
+    end
+
+    #########################################################################
+    #
+    # Internal Methods
+    #
+    #########################################################################
+
+    # The underlying wiki repo.
+    #
+    # Returns the Gollum::Wiki containing the page.
+    attr_reader :wiki
+
+    # Set the Grit::Commit version of the page.
+    #
+    # Returns nothing.
+    attr_writer :version
+
+    # Find a page in the given Gollum repo.
+    #
+    # name    - The human or canonical String page name to find.
+    # version - The String version ID to find.
+    #
+    # Returns a Gollum::Page or nil if the page could not be found.
+    def find(name, version)
+      if commit = @wiki.repo.commit(version)
+        if page = find_page_in_tree(commit.tree, name)
+          page.version = commit
+          page
+        end
+      end
+    end
+
+    # Find a page in a given tree.
+    #
+    # tree - The Grit::Tree in which to look.
+    # name - The canonical String page name.
+    #
+    # Returns a Gollum::Page or nil if the page could not be found.
+    def find_page_in_tree(tree, name)
+      treemap = {}
+      trees = [tree]
+
+      while !trees.empty?
+        ptree = trees.shift
+        ptree.contents.each do |item|
+          case item
+            when Grit::Blob
+              if page_match(name, item.name)
+                return self.class.new(@wiki).populate(item, tree_path(treemap, ptree))
+              end
+            when Grit::Tree
+              treemap[item] = ptree
+              trees << item
+          end
+        end
+      end
+
+      return nil # nothing was found
+    end
+
+    # Find a page in a given tree without recursing into subtrees.
+    #
+    # tree - The Grit::Tree in which to look.
+    # dir  - The String path of the given Grit::Tree.
+    # name - The canonical String page name.
+    #
+    # Returns a Gollum::Page or nil if the page could not be found.
+    def find_page_in_this_tree(tree, dir, name)
+      treemap = {}
+      tree.contents.each do |item|
+        case item
+          when Grit::Blob
+            if page_match(name, item.name)
+              path = dir == '' ? '' : ::File.join('/', dir)
+              page = self.class.new(@wiki).populate(item, path)
+              page.version = self.version
+              return page
+            end
+        end
+      end
+
+      return nil # nothing was found
+    end
+
+    # Populate the Page with information from the Blob.
+    #
+    # blob - The Grit::Blob that contains the info.
+    # path - The String directory path of the page file.
+    #
+    # Returns the populated Gollum::Page.
+    def populate(blob, path)
+      @blob = blob
+      @path = (path + '/' + blob.name)[1..-1]
+      self
+    end
+
+    # The full directory path for the given tree.
+    #
+    # treemap - The Hash treemap containing parentage information.
+    # tree    - The Grit::Tree for which to compute the path.
+    #
+    # Returns the String path.
+    def tree_path(treemap, tree)
+      if ptree = treemap[tree]
+        tree_path(treemap, ptree) + '/' + tree.name
+      else
+        ''
+      end
+    end
+
+    # Compare the canonicalized versions of the two names.
+    #
+    # name     - The human or canonical String page name.
+    # filename - the String filename on disk (including extension).
+    #
+    # Returns a Boolean.
+    def page_match(name, filename)
+      if match = self.class.valid_filename?(filename)
+        Page.cname(name).downcase == Page.cname(match).downcase
+      else
+        false
+      end
+    end
+  end
+end

data/lib/gollum/pagination.rb

@@ -0,0 +1,61 @@
+module Gollum
+  module Pagination
+    def self.included(klass)
+      klass.extend ClassMethods
+      class << klass
+        # Default Integer max count of items to return in git commands.
+        attr_accessor :per_page
+      end
+      klass.per_page = 30
+    end
+
+    module ClassMethods
+      # Turns a page number into an offset number for the git skip option.
+      #
+      # page - Integer page number.
+      #
+      # Returns an Integer.
+      def page_to_skip(page)
+        ([1, page.to_i].max - 1) * per_page
+      end
+
+      # Fills in git-specific options for the log command using simple 
+      # pagination options.
+      #
+      # options - Hash of options:
+      #           page - Optional Integer page number (default: 1)
+      #           per_page - Optional Integer max count of items to return.
+      #                      Defaults to #per_class class method.
+      #
+      # Returns Hash with :max_count and :skip keys.
+      def log_pagination_options(options = {})
+        skip = page_to_skip(options.delete(:page))
+        options[:max_count] = [options.delete(:per_page).to_i, per_page].max
+        options[:skip]      = skip if skip > 0
+        options
+      end
+    end
+
+    # Turns a page number into an offset number for the git skip option.
+    #
+    # page - Integer page number.
+    #
+    # Returns an Integer.
+    def page_to_skip(page)
+      self.class.page_to_skip(page)
+    end
+
+    # Fills in git-specific options for the log command using simple 
+    # pagination options.
+    #
+    # options - Hash of options:
+    #           page - Optional Integer page number (default: 1)
+    #           per_page - Optional Integer max count of items to return.
+    #                      Defaults to #per_class class method.
+    #
+    # Returns Hash with :max_count and :skip keys.
+    def log_pagination_options(options = {})
+      self.class.log_pagination_options(options)
+    end
+  end
+end

data/lib/gollum/wiki.rb

@@ -0,0 +1,335 @@
+module Gollum
+  class Wiki
+    include Pagination
+
+    class << self
+      # Sets the page class used by all instances of this Wiki.
+      attr_writer :page_class
+
+      # Sets the file class used by all instances of this Wiki.
+      attr_writer :file_class
+
+      # Gets the page class used by all instances of this Wiki.
+      # Default: Gollum::Page.
+      def page_class
+        @page_class ||
+          if superclass.respond_to?(:page_class)
+            superclass.page_class
+          else
+            ::Gollum::Page
+          end
+      end
+
+      # Gets the file class used by all instances of this Wiki.
+      # Default: Gollum::File.
+      def file_class
+        @file_class ||
+          if superclass.respond_to?(:file_class)
+            superclass.file_class
+          else
+            ::Gollum::File
+          end
+      end
+    end
+
+
+    # The String base path to prefix to internal links. For example, when set
+    # to "/wiki", the page "Hobbit" will be linked as "/wiki/Hobbit". Defaults
+    # to "/".
+    attr_reader :base_path
+
+    # Public: Initialize a new Gollum Repo.
+    #
+    # repo    - The String path to the Git repository that holds the Gollum
+    #           site.
+    # options - Optional Hash:
+    #           :base_path  - String base path for all Wiki links.  
+    #                         Default: "/"
+    #           :page_class - The page Class. Default: Gollum::Page
+    #           :file_class - The file Class. Default: Gollum::File
+    #
+    # Returns a fresh Gollum::Repo.
+    def initialize(path, options = {})
+      @path       = path
+      @repo       = Grit::Repo.new(path)
+      @base_path  = options[:base_path]  || "/"
+      @page_class = options[:page_class] || self.class.page_class
+      @file_class = options[:file_class] || self.class.file_class
+    end
+
+    # Public: check whether the wiki's git repo exists on the filesystem.
+    #
+    # Returns true if the repo exists, and false if it does not.
+    def exist?
+      @repo.git.exist?
+    end
+
+    # Public: Get the formatted page for a given page name.
+    #
+    # name    - The human or canonical String page name of the wiki page.
+    # version - The String version ID to find (default: "master").
+    #
+    # Returns a Gollum::Page or nil if no matching page was found.
+    def page(name, version = 'master')
+      @page_class.new(self).find(name, version)
+    end
+
+    # Public: Get the static file for a given name.
+    #
+    # name    - The full String pathname to the file.
+    # version - The String version ID to find (default: "master").
+    #
+    # Returns a Gollum::File or nil if no matching file was found.
+    def file(name, version = 'master')
+      @file_class.new(self).find(name, version)
+    end
+
+    # Public: Create an in-memory Page with the given data and format. This
+    # is useful for previewing what content will look like before committing
+    # it to the repository.
+    #
+    # name   - The String name of the page.
+    # format - The Symbol format of the page.
+    # data   - The new String contents of the page.
+    #
+    # Returns the in-memory Gollum::Page.
+    def preview_page(name, data, format)
+      page = @page_class.new(self)
+      ext  = @page_class.format_to_ext(format.to_sym)
+      path = @page_class.cname(name) + '.' + ext
+      blob = OpenStruct.new(:name => path, :data => data)
+      page.populate(blob, path)
+      page.version = self.repo.commit("HEAD")
+      page
+    end
+
+    # Public: Write a new version of a page to the Gollum repo root.
+    #
+    # name   - The String name of the page.
+    # format - The Symbol format of the page.
+    # data   - The new String contents of the page.
+    # commit - The commit Hash details:
+    #          :message - The String commit message.
+    #          :name    - The String author full name.
+    #          :email   - The String email address.
+    #
+    # Returns the String SHA1 of the newly written version.
+    def write_page(name, format, data, commit = {})
+      map = {}
+      if pcommit = @repo.commit('master')
+        map = tree_map(pcommit.tree)
+      end
+
+      map   = add_to_tree_map(map, '', name, format, data)
+      index = tree_map_to_index(map)
+
+      parents = pcommit ? [pcommit] : []
+      actor   = Grit::Actor.new(commit[:name], commit[:email])
+      index.commit(commit[:message], parents, actor)
+    end
+
+    # Public: Update an existing page with new content. The location of the
+    # page inside the repository will not change. If the given format is
+    # different than the current format of the page, the filename will be
+    # changed to reflect the new format.
+    #
+    # page   - The Gollum::Page to update.
+    # name   - The String extension-less name of the page.
+    # format - The Symbol format of the page.
+    # data   - The new String contents of the page.
+    # commit - The commit Hash details:
+    #          :message - The String commit message.
+    #          :name    - The String author full name.
+    #          :email   - The String email address.
+    #
+    # Returns the String SHA1 of the newly written version.
+    def update_page(page, name, format, data, commit = {})
+      pcommit  = @repo.commit('master')
+      map      = tree_map(pcommit.tree)
+      name   ||= page.name
+      format ||= page.format
+      index    = nil
+
+      if page.name == name && page.format == format
+        index = tree_map_to_index(map)
+        index.add(page.path, normalize(data))
+      else
+        map   = delete_from_tree_map(map, page.path)
+        dir   = ::File.dirname(page.path)
+        map   = add_to_tree_map(map, dir, name, format, data)
+        index = tree_map_to_index(map)
+      end
+
+      actor = Grit::Actor.new(commit[:name], commit[:email])
+      index.commit(commit[:message], [pcommit], actor)
+    end
+
+    # Public: Delete a page.
+    #
+    # page   - The Gollum::Page to delete.
+    # commit - The commit Hash details:
+    #          :message - The String commit message.
+    #          :author  - The String author full name.
+    #          :email   - The String email address.
+    #
+    # Returns the String SHA1 of the newly written version.
+    def delete_page(page, commit)
+      pcommit = @repo.commit('master')
+      map     = tree_map(pcommit.tree)
+
+      map   = delete_from_tree_map(map, page.path)
+      index = tree_map_to_index(map)
+
+      actor = Grit::Actor.new(commit[:name], commit[:email])
+      index.commit(commit[:message], [pcommit], actor)
+    end
+
+    # Public: Lists all pages for this wiki.
+    #
+    # treeish - The String commit ID or ref to find  (default: master)
+    #
+    # Returns an Array of Gollum::Page instances.
+    def pages(treeish = nil)
+      treeish ||= 'master'
+      if commit = @repo.commit(treeish)
+        tree_list(commit)
+      else
+        []
+      end
+    end
+
+    # Public: All of the versions that have touched the Page.
+    #
+    # options - The options Hash:
+    #           :page     - The Integer page number (default: 1).
+    #           :per_page - The Integer max count of items to return.
+    #
+    # Returns an Array of Grit::Commit.
+    def log(options = {})
+      @repo.log('master', nil, log_pagination_options(options))
+    end
+
+    #########################################################################
+    #
+    # Internal Methods
+    #
+    #########################################################################
+
+    # The Grit::Repo associated with the wiki.
+    #
+    # Returns the Grit::Repo.
+    attr_reader :repo
+
+    # The String path to the Git repository that holds the Gollum site.
+    #
+    # Returns the String path.
+    attr_reader :path
+
+    # Normalize the data.
+    #
+    # data - The String data to be normalized.
+    #
+    # Returns the normalized data String.
+    def normalize(data)
+      data.gsub(/\r/, '')
+    end
+
+    # Fill an array with a list of pages.
+    #
+    # commit   - The Grit::Commit 
+    # tree     - The Grit::Tree to start with.
+    # sub_tree - Optional String specifying the parent path of the Page.
+    #
+    # Returns a flat Array of Gollum::Page instances.
+    def tree_list(commit, tree = commit.tree, sub_tree = nil)
+      list = []
+      path = tree.name ? "#{sub_tree}/#{tree.name}" : ''
+      tree.contents.each do |item|
+        case item
+          when Grit::Blob
+            if @page_class.valid_page_name?(item.name)
+              page = @page_class.new(self).populate(item, path)
+              page.version = commit
+              list << page
+            end
+          when Grit::Tree
+            list.push *tree_list(commit, item, path)
+        end
+      end
+      list
+    end
+
+    # Fill an index with the existing state of the repository.
+    #
+    # tree - The Grit::Tree to start with.
+    #
+    # Returns a nested Hash of filename to content mappings.
+    def tree_map(tree)
+      map = {}
+      tree.contents.each do |item|
+        case item
+          when Grit::Blob
+            map[item.name] = item.data
+          when Grit::Tree
+            map[item.name] = tree_map(item)
+        end
+      end
+      map
+    end
+
+    # Use a treemap to fill in the index.
+    #
+    # map   - The Hash map:
+    #         key - The String directory or filename.
+    #         val - The Hash submap or the String contents of the file.
+    # index - The Grit::Index to use. Leave blank when calling from outside
+    #         this method (default: nil).
+    #
+    # Returns the Grit::Index.
+    def tree_map_to_index(map, prefix = '', index = nil)
+      index ||= @repo.index
+      map.each do |k, v|
+        case k
+          when String
+            name = [prefix, k].join('/')[1..-1]
+            index.add(k, v)
+          when Hash
+            new_prefix = [prefix, k].join('/')[1..-1]
+            tree_map_to_index(v, new_prefix, index)
+        end
+      end
+      index
+    end
+
+    def add_to_tree_map(map, dir, name, format, data)
+      ext  = @page_class.format_to_ext(format)
+      path = @page_class.cname(name) + '.' + ext
+
+      parts = dir.split('/')
+      container = nil
+      parts.each do |part|
+        container = map[part]
+      end
+
+      (container || map)[path] = normalize(data)
+      map
+    end
+
+    # Delete an entry from a tree map.
+    #
+    # map  - The Hash tree map of the repository.
+    # path - The String path of the file to delete.
+    #
+    # Returns the modified Hash tree map.
+    def delete_from_tree_map(map, path)
+      parts = path.split('/')
+      name  = parts.pop
+      container = nil
+      parts.each do |part|
+        container = map[part]
+      end
+      (container || map).delete(name)
+      map
+    end
+  end
+end