read-only-gollum 1.4.0

data/Rakefile

@@ -0,0 +1,142 @@
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test' << '.'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc "Generate RCov test coverage and open in your browser"
+task :coverage do
+  require 'rcov'
+  sh "rm -fr coverage"
+  sh "rcov test/test_*.rb"
+  sh "open coverage/index.html"
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc 'Create a release build'
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+desc 'Build gem'
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc 'Validate gemspec'
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc 'Validate lib files and version file'
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/bin/read-only-gollum

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *%w[.. lib])
+
+help = <<HELP
+Gollum is a multi-format Wiki Engine/API/Frontend.
+
+Basic Command Line Usage:
+  gollum [OPTIONS] [PATH]
+
+        PATH                         The path to the Gollum repository (default .).
+
+Options:
+HELP
+
+require 'optparse'
+require 'rubygems'
+require 'gollum'
+
+exec = {}
+options = { 'port' => 4567, 'bind' => '0.0.0.0' }
+wiki_options = {}
+
+opts = OptionParser.new do |opts|
+  opts.banner = help
+
+  opts.on("--port [PORT]", "Bind port (default 4567).") do |port|
+    options['port'] = port.to_i
+  end
+
+  opts.on("--host [HOST]", "Hostname or IP address to listen on (default 0.0.0.0).") do |host|
+    options['bind'] = host
+  end
+
+  opts.on("--version", "Display current version.") do
+    puts "Gollum " + Gollum::VERSION
+    exit 0
+  end
+
+  opts.on("--config [CONFIG]", "Path to additional configuration file") do |config|
+    options['config'] = config
+  end
+
+  opts.on("--irb", "Start an irb process with gollum loaded for the current wiki.") do
+    options['irb'] = true
+  end
+
+  opts.on("--page-file-dir [PATH]", "Specify the sub directory for all page files (default: repository root).") do |path|
+    wiki_options[:page_file_dir] = path
+  end
+
+  opts.on("--ref [REF]", "Specify the repository ref to use (default: master).") do |ref|
+    wiki_options[:ref] = ref
+  end
+end
+
+# Read command line options into `options` hash
+begin
+  opts.parse!
+rescue OptionParser::InvalidOption
+  puts "gollum: #{$!.message}"
+  puts "gollum: try 'gollum --help' for more information"
+  exit
+end
+
+gollum_path = ARGV[0] || Dir.pwd
+
+if options['irb']
+  require 'irb'
+  # http://jameskilton.com/2009/04/02/embedding-irb-into-your-ruby-application/
+  module IRB # :nodoc:
+    def self.start_session(binding)
+      unless @__initialized
+        args = ARGV
+        ARGV.replace(ARGV.dup)
+        IRB.setup(nil)
+        ARGV.replace(args)
+        @__initialized = true
+      end
+
+      ws  = WorkSpace.new(binding)
+      irb = Irb.new(ws)
+
+      @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC]
+      @CONF[:MAIN_CONTEXT] = irb.context
+
+      catch(:IRB_EXIT) do
+        irb.eval_input
+      end
+    end
+  end
+
+  begin
+    wiki = Gollum::Wiki.new(gollum_path, wiki_options)
+    if !wiki.exist? then raise Grit::InvalidGitRepositoryError end
+    puts "Loaded Gollum wiki at #{File.expand_path(gollum_path).inspect}."
+    puts
+    puts %(    page = wiki.page('page-name'))
+    puts %(    # => <Gollum::Page>)
+    puts
+    puts %(    page.raw_data)
+    puts %(    # => "# My wiki page")
+    puts
+    puts %(    page.formatted_data)
+    puts %(    # => "<h1>My wiki page</h1>")
+    puts
+    puts "Check out the Gollum README for more."
+    IRB.start_session(binding)
+  rescue Grit::InvalidGitRepositoryError, Grit::NoSuchPathError
+    puts "Invalid Gollum wiki at #{File.expand_path(gollum_path).inspect}"
+    exit 0
+  end
+else
+  require 'gollum/frontend/app'
+  Precious::App.set(:gollum_path, gollum_path)
+  Precious::App.set(:wiki_options, wiki_options)
+
+  if cfg = options['config']
+    # If the path begins with a '/' it will be considered an absolute path,
+    # otherwise it will be relative to the CWD
+    cfg = File.join(Dir.getwd, cfg) unless cfg.slice(0) == File::SEPARATOR
+    require cfg
+  end
+
+  Precious::App.run!(options)
+end

data/docs/sanitization.md

@@ -0,0 +1,32 @@
+Sanitization Rules
+==================
+
+Gollum uses the [Sanitize](http://wonko.com/post/sanitize) gem for HTML
+sanitization.
+
+See `lib/gollum.rb` for actual settings.
+
+## ALLOWED TAGS
+
+a, abbr, acronym, address, area, b, big, blockquote, br, button, caption,
+center, cite, code, col, colgroup, dd, del, dfn, dir, div, dl, dt, em,
+fieldset, font, form, h1, h2, h3, h4, h5, h6, hr, i, img, input, ins, kbd,
+label, legend, li, map, menu, ol, optgroup, option, p, pre, q, s, samp,
+select, small, span, strike, strong, sub, sup, table, tbody, td, textarea,
+tfoot, th, thead, tr, tt, u, ul, var
+
+## ALLOWED ATTRIBUTES
+
+abbr, accept, accept-charset, accesskey, action, align, alt, axis, border,
+cellpadding, cellspacing, char, charoff, charset, checked, cite, class, clear,
+cols, colspan, color, compact, coords, datetime, dir, disabled, enctype, for,
+frame, headers, height, href, hreflang, hspace, id, ismap, label, lang,
+longdesc, maxlength, media, method, multiple, name, nohref, noshade, nowrap,
+prompt, readonly, rel, rev, rows, rowspan, rules, scope, selected, shape,
+size, span, src, start, summary, tabindex, target, title, type, usemap,
+valign, value, vspace, width
+
+## ALLOWED PROTOCOLS
+
+a href: http, https, mailto
+img src: http, https

data/lib/gollum.rb

@@ -0,0 +1,41 @@
+# stdlib
+require 'digest/md5'
+require 'ostruct'
+
+# external
+require 'grit'
+require 'github/markup'
+require 'sanitize'
+
+# internal
+require File.expand_path('../gollum/git_access', __FILE__)
+require File.expand_path('../gollum/committer', __FILE__)
+require File.expand_path('../gollum/pagination', __FILE__)
+require File.expand_path('../gollum/blob_entry', __FILE__)
+require File.expand_path('../gollum/wiki', __FILE__)
+require File.expand_path('../gollum/page', __FILE__)
+require File.expand_path('../gollum/file', __FILE__)
+require File.expand_path('../gollum/markup', __FILE__)
+require File.expand_path('../gollum/sanitization', __FILE__)
+require File.expand_path('../gollum/tex', __FILE__)
+require File.expand_path('../gollum/web_sequence_diagram', __FILE__)
+
+module Gollum
+  VERSION = '1.4.0'
+
+  class Error < StandardError; end
+
+  class DuplicatePageError < Error
+    attr_accessor :dir
+    attr_accessor :existing_path
+    attr_accessor :attempted_path
+
+    def initialize(dir, existing, attempted, message = nil)
+      @dir            = dir
+      @existing_path  = existing
+      @attempted_path = attempted
+      super(message || "Cannot write #{@dir}/#{@attempted_path}, found #{@dir}/#{@existing_path}.")
+    end
+  end
+end
+

data/lib/gollum/blob_entry.rb

@@ -0,0 +1,78 @@
+module Gollum
+  class BlobEntry
+    # Gets the String SHA for this blob.
+    attr_reader :sha
+
+    # Gets the full path String for this blob.
+    attr_reader :path
+
+    # Gets the Fixnum size of this blob.
+    attr_reader :size
+
+    def initialize(sha, path, size = nil)
+      @sha  = sha
+      @path = path
+      @size = size
+      @dir  = @name = @blob = nil
+    end
+
+    # Gets the normalized directory path String for this blob.
+    def dir
+      @dir ||= self.class.normalize_dir(::File.dirname(@path))
+    end
+
+    # Gets the file base name String for this blob.
+    def name
+      @name ||= ::File.basename(@path)
+    end
+
+    # Gets a Grit::Blob instance for this blob.
+    #
+    # repo - Grit::Repo instance for the Grit::Blob.
+    #
+    # Returns an unbaked Grit::Blob instance.
+    def blob(repo)
+      @blob ||= Grit::Blob.create(repo,
+        :id => @sha, :name => name, :size => @size)
+    end
+
+    # Gets a Page instance for this blob.
+    #
+    # wiki - Gollum::Wiki instance for the Gollum::Page
+    #
+    # Returns a Gollum::Page instance.
+    def page(wiki, commit)
+      blob = self.blob(wiki.repo)
+      page = wiki.page_class.new(wiki).populate(blob, self.dir)
+      page.version = commit
+      page
+    end
+
+    def inspect
+      %(#<Gollum::BlobEntry #{@sha} #{@path}>)
+    end
+
+    # Normalizes a given directory name for searching through tree paths.
+    # Ensures that a directory begins with a slash, or
+    #
+    #   normalize_dir("")      # => ""
+    #   normalize_dir(".")     # => ""
+    #   normalize_dir("foo")   # => "/foo"
+    #   normalize_dir("/foo/") # => "/foo"
+    #   normalize_dir("/")     # => ""
+    #   normalize_dir("c:/")   # => ""
+    #
+    # dir - String directory name.
+    #
+    # Returns a normalized String directory name, or nil if no directory
+    # is given.
+    def self.normalize_dir(dir)
+      return '' if dir =~ /^.:\/$/
+      if dir
+        dir = ::File.expand_path(dir, '/')
+        dir = '' if dir == '/'
+      end
+      dir
+    end
+  end
+end

data/lib/gollum/committer.rb

@@ -0,0 +1,218 @@
+module Gollum
+  # Responsible for handling the commit process for a Wiki.  It sets up the
+  # Git index, provides methods for modifying the tree, and stores callbacks
+  # to be fired after the commit has been made.  This is specifically
+  # designed to handle multiple updated pages in a single commit.
+  class Committer
+    # Gets the instance of the Gollum::Wiki that is being updated.
+    attr_reader :wiki
+
+    # Gets a Hash of commit options.
+    attr_reader :options
+
+    # Initializes the Committer.
+    #
+    # wiki    - The Gollum::Wiki instance that is being updated.
+    # options - The commit Hash details:
+    #           :message   - The String commit message.
+    #           :name      - The String author full name.
+    #           :email     - The String email address.
+    #           :parent    - Optional Grit::Commit parent to this update.
+    #           :tree      - Optional String SHA of the tree to create the
+    #                        index from.
+    #           :committer - Optional Gollum::Committer instance.  If provided,
+    #                        assume that this operation is part of batch of
+    #                        updates and the commit happens later.
+    #
+    # Returns the Committer instance.
+    def initialize(wiki, options = {})
+      @wiki      = wiki
+      @options   = options
+      @callbacks = []
+    end
+
+    # Public: References the Git index for this commit.
+    #
+    # Returns a Grit::Index.
+    def index
+      @index ||= begin
+        idx = @wiki.repo.index
+        if tree   = options[:tree]
+          idx.read_tree(tree)
+        elsif parent = parents.first
+          idx.read_tree(parent.tree.id)
+        end
+        idx
+      end
+    end
+
+    # Public: The committer for this commit.
+    #
+    # Returns a Grit::Actor.
+    def actor
+      @actor ||= begin
+        @options[:name]  = @wiki.default_committer_name  if @options[:name].to_s.empty?
+        @options[:email] = @wiki.default_committer_email if @options[:email].to_s.empty?
+        Grit::Actor.new(@options[:name], @options[:email])
+      end
+    end
+
+    # Public: The parent commits to this pending commit.
+    #
+    # Returns an array of Grit::Commit instances.
+    def parents
+      @parents ||= begin
+        arr = [@options[:parent] || @wiki.repo.commit(@wiki.ref)]
+        arr.flatten!
+        arr.compact!
+        arr
+      end
+    end
+
+    # Adds a page to the given Index.
+    #
+    # dir    - The String subdirectory of the Gollum::Page without any
+    #          prefix or suffix slashes (e.g. "foo/bar").
+    # name   - The String Gollum::Page filename_stripped.
+    # format - The Symbol Gollum::Page format.
+    # data   - The String wiki data to store in the tree map.
+    # allow_same_ext - A Boolean determining if the tree map allows the same
+    #                  filename with the same extension.
+    #
+    # Raises Gollum::DuplicatePageError if a matching filename already exists.
+    # This way, pages are not inadvertently overwritten.
+    #
+    # Returns nothing (modifies the Index in place).
+    def add_to_index(dir, name, format, data, allow_same_ext = false)
+      path = @wiki.page_file_name(name, format)
+
+      dir = '/' if dir.strip.empty?
+
+      fullpath = ::File.join(*[@wiki.page_file_dir, dir, path].compact)
+      fullpath = fullpath[1..-1] if fullpath =~ /^\//
+
+      if index.current_tree && tree = index.current_tree / dir
+        downpath = path.downcase.sub(/\.\w+$/, '')
+
+        tree.blobs.each do |blob|
+          next if page_path_scheduled_for_deletion?(index.tree, fullpath)
+          file = blob.name.downcase.sub(/\.\w+$/, '')
+          file_ext = ::File.extname(blob.name).sub(/^\./, '')
+          if downpath == file && !(allow_same_ext && file_ext == ext)
+            raise DuplicatePageError.new(dir, blob.name, path)
+          end
+        end
+      end
+
+      index.add(fullpath, @wiki.normalize(data))
+    end
+
+    # Update the given file in the repository's working directory if there
+    # is a working directory present.
+    #
+    # dir    - The String directory in which the file lives.
+    # name   - The String name of the page or the stripped filename
+    #          (should be pre-canonicalized if required).
+    # format - The Symbol format of the page.
+    #
+    # Returns nothing.
+    def update_working_dir(dir, name, format)
+      unless @wiki.repo.bare
+        if @wiki.page_file_dir
+          dir = dir.size.zero? ? @wiki.page_file_dir : ::File.join(dir, @wiki.page_file_dir)
+        end
+
+        path =
+          if dir == ''
+            @wiki.page_file_name(name, format)
+          else
+            ::File.join(dir, @wiki.page_file_name(name, format))
+          end
+
+        Dir.chdir(::File.join(@wiki.repo.path, '..')) do
+          if file_path_scheduled_for_deletion?(index.tree, path)
+            @wiki.repo.git.rm({'f' => true}, '--', path)
+          else
+            @wiki.repo.git.checkout({}, 'HEAD', '--', path)
+          end
+        end
+      end
+    end
+
+    # Writes the commit to Git and runs the after_commit callbacks.
+    #
+    # Returns the String SHA1 of the new commit.
+    def commit
+      sha1 = index.commit(@options[:message], parents, actor, nil, @wiki.ref)
+      @callbacks.each do |cb|
+        cb.call(self, sha1)
+      end
+      sha1
+    end
+
+    # Adds a callback to be fired after a commit.
+    #
+    # block - A block that expects this Committer instance and the created
+    #         commit's SHA1 as the arguments.
+    #
+    # Returns nothing.
+    def after_commit(&block)
+      @callbacks << block
+    end
+
+    # Determine if a given page (regardless of format) is scheduled to be
+    # deleted in the next commit for the given Index.
+    #
+    # map   - The Hash map:
+    #         key - The String directory or filename.
+    #         val - The Hash submap or the String contents of the file.
+    # path - The String path of the page file. This may include the format
+    #         extension in which case it will be ignored.
+    #
+    # Returns the Boolean response.
+    def page_path_scheduled_for_deletion?(map, path)
+      parts = path.split('/')
+      if parts.size == 1
+        deletions = map.keys.select { |k| !map[k] }
+        downfile = parts.first.downcase.sub(/\.\w+$/, '')
+        deletions.any? { |d| d.downcase.sub(/\.\w+$/, '') == downfile }
+      else
+        part = parts.shift
+        if rest = map[part]
+          page_path_scheduled_for_deletion?(rest, parts.join('/'))
+        else
+          false
+        end
+      end
+    end
+
+    # Determine if a given file is scheduled to be deleted in the next commit
+    # for the given Index.
+    #
+    # map   - The Hash map:
+    #         key - The String directory or filename.
+    #         val - The Hash submap or the String contents of the file.
+    # path - The String path of the file including extension.
+    #
+    # Returns the Boolean response.
+    def file_path_scheduled_for_deletion?(map, path)
+      parts = path.split('/')
+      if parts.size == 1
+        deletions = map.keys.select { |k| !map[k] }
+        deletions.any? { |d| d == parts.first }
+      else
+        part = parts.shift
+        if rest = map[part]
+          file_path_scheduled_for_deletion?(rest, parts.join('/'))
+        else
+          false
+        end
+      end
+    end
+
+    # Proxies methods t
+    def method_missing(name, *args)
+      index.send(name, *args)
+    end
+  end
+end