poki

#!/usr/bin/env ruby

# ================================================================
# Poki: A poor man's wiki generator
# Code: https://github.com/johnkerl/poki
# Docs: http://johnkerl.org/poki/doc
#
# John Kerl
# kerl.john.r@gmail.com
# 2015-04-26
# ================================================================

$us                           = File.basename $0
$default_config_file_name     = "poki.cfg"
$default_template_file_name   = "template.html"
$default_content_file_prefix  = "content-for-"
$output_file_mode_during_edit = 0644;
$output_file_mode_after_edit  = 0444;

require 'getoptlong'
require 'fileutils'

# ================================================================
def usage()
   $stderr.puts <<EOF
Usage: #{$us} [options]
Options:
-c {config file}         Default #{$default_config_file_name}
-t {template file}       Default #{$default_template_file_name}
-p {content-file prefix} Default #{$default_content_file_prefix}
-h|--help                Print this message
Please see ./doc in poki's source directory
https://github.com/johnkerl/poki
https://johnkerl.org/poki/doc
EOF
end

# ================================================================
def main()
  config_file_name    = $default_config_file_name
  template_file_name  = $default_template_file_name
  content_file_prefix = $default_content_file_prefix

  opts = GetoptLong.new(
    [ '-c', GetoptLong::REQUIRED_ARGUMENT ],
    [ '-t', GetoptLong::REQUIRED_ARGUMENT ],
    [ '-p', GetoptLong::REQUIRED_ARGUMENT ],
    [ '-h','--help', GetoptLong::NO_ARGUMENT ]
  )

  begin
    opts.each do |opt, arg|
      case opt
        when '-c'; config_file_name    = arg
        when '-t'; template_file_name  = arg
        when '-p'; content_file_prefix = arg
        when '-h'; usage
        when '--help'; usage
      end
    end
    rescue GetoptLong::Error
      usage
  end
  usage if ARGV.length != 0

  # Hashmaps are insertion-ordered in Ruby 1.9 and above
  page_map = load_config_file(config_file_name)

  generate_pages(template_file_name, content_file_prefix, config_file_name, page_map)
end

# ================================================================
def load_config_file(config_file_name)
  page_map = {}
  line_number = 0
  File.readlines(config_file_name).each do |content_line|
    line_number += 1

    # Strip comments
    content_line = content_line.chomp.strip.sub(/#.*/, '')
    # Skip blank lines, or lines with only comments on them
    next if content_line.empty?

    fields = content_line.chomp.strip.split(/\s+/, 2)
    if fields.length != 2
      raise "#{$us}: Didn't find page name and page title at line #{line_number} of Poki config file #{config_file_name}'"
    end
    output_file_name = fields[0]
    title            = fields[1]
    page_map[output_file_name] = title
  end
  page_map
end

# ================================================================
def generate_pages(template_file_name, content_file_prefix, config_file_name, page_map)
  for output_file_name, title in page_map
    # Separator lines aren't associated with a local input HTML file.
    next if output_file_name =~ /^sep:/
    # External links aren't associated with a local input HTML file.
    next if output_file_name =~ /^ext:/

    input_file_name = "#{content_file_prefix}#{output_file_name}"
    generate_page(template_file_name, input_file_name, output_file_name, title, config_file_name, page_map)
  end
end

# ----------------------------------------------------------------
def generate_page(template_file_name, input_file_name, output_file_name, title, config_file_name, page_map)
  if test(?f, output_file_name)
    FileUtils.chmod($output_file_mode_during_edit, output_file_name)
  end

  File.open(output_file_name, "w", $output_file_mode_during_edit) do |output_handle|
    File.readlines(template_file_name).each do |template_line|

      # Template directive: Mark autogenerated pages as autogenerated.
      if template_line =~ /POKI_PUT_AUTOGEN_DISCLAIMER_HERE/
        output_handle.puts(template_line.sub('POKI_PUT_AUTOGEN_DISCLAIMER_HERE', ''))
        output_handle.puts "<!-- PAGE GENERATED FROM #{template_file_name} and #{input_file_name} BY #{$us}. -->"
        output_handle.puts "<!-- PLEASE MAKE CHANGES THERE AND THEN RE-RUN #{$us}. -->"

      # Template directive: For left-hand link-list.
      elsif template_line =~ /POKI_PUT_PAGE_LIST_HERE/
        output_handle.puts(template_line.sub('POKI_PUT_PAGE_LIST_HERE', ''))
        generate_page_list(template_file_name, output_file_name, page_map, output_handle)

      # Template directive: Page titles in browser window title, as well as page-content title.
      elsif template_line =~ /POKI_PUT_TITLE_HERE/
        output_handle.puts(template_line.sub('POKI_PUT_TITLE_HERE', title))

      # Template directive: Page body.
      elsif template_line =~ /POKI_PUT_BODY_HERE/
        output_handle.puts(template_line.sub('POKI_PUT_BODY_HERE', ''))
        generate_page_body(input_file_name, page_map, output_handle, config_file_name)

      # Absent any other directives, copy the template file to the output file.
      else
        output_handle.write(template_line)

      end
    end
    FileUtils.chmod($output_file_mode_after_edit, output_file_name)
    puts "Generated #{output_file_name}"
  end
end

# ----------------------------------------------------------------
def generate_page_list(template_file_name, output_file_path, page_map, output_handle)
  output_file_name = File.basename(output_file_path)
  output_handle.puts "<!-- PAGE LIST GENERATED FROM #{template_file_name} BY #{$us} -->"
  for link_name, link_text in page_map
    if link_name =~ /^sep:/
      output_handle.puts "<br/>#{link_text}"
    elsif link_name =~ /^ext/
      url = link_name.sub(/^ext:/, '')
      output_handle.puts "<br/>&bull;&nbsp;<a href=\"#{url}\">#{link_text}</a>"
    else
      bs = ""
      be = ""
      if output_file_name == link_name
        # Bold the current file in the navbar. xxx to do: use callback CSS so the caller
        # can control how to format this.
        bs = "<b>"
        be = "</b>"
      end
      output_handle.puts "<br/>&bull;&nbsp;<a href=\"#{link_name}\">#{bs}#{link_text}#{be}</a>"
    end
  end
end

# ----------------------------------------------------------------
def generate_page_body(input_file_name, page_map, output_handle, config_file_name)
  output_handle.puts "<!-- BODY COPIED FROM #{input_file_name} BY #{$us} -->"
  File.readlines(input_file_name).each do |content_line|

    # Page-content directive: table of contents.
    if content_line =~ /POKI_PUT_TOC_HERE/
      generate_toc(input_file_name, output_handle)

    # Page-content directive: include other file (do HTML escapes)
    elsif content_line =~ /POKI_INCLUDE_ESCAPED\(([^)]+)\)HERE/
      included_file_name = $1
      include_escaped(included_file_name, output_handle)

    # Page-content directive: include other file (do HTML escapes) and print its output
    elsif content_line =~ /POKI_INCLUDE_AND_RUN_ESCAPED\(([^)]+)\)HERE/
      included_file_name = $1
      cmd = File.readlines(included_file_name).join('')
      run_command(cmd, output_handle, true)

    # Page-content directive: run a script which generates HTML and print its output
    elsif content_line =~ /POKI_RUN_UNESCAPED\(([^)]+)\)HERE/
      included_file_name = $1
      cmd = File.readlines(included_file_name).join('')
      run_command(cmd, output_handle, false)

    # Page-content directive: include other file (do HTML escapes) and print its output
    elsif content_line =~ /POKI_RUN_CONTENT_GENERATOR\(([^)]+)\)HERE/
      cmd = $1
      run_content_generator(cmd, output_handle)

    # Page-content directive: format as if included from a file.
    elsif content_line =~ /POKI_CARDIFY\(([^)]+)\)HERE/
      content_line = $1
      cardify(content_line, output_handle, true)
    elsif content_line =~ /POKI_CARDIFY{{([^)]+)}}HERE/
      content_line = $1
      cardify(content_line, output_handle, true)

    elsif content_line =~ /POKI_CARDIFY{{(.+)}}HERE/
      content_line = $1
      cardify(content_line, output_handle, true)

    # Page-content directive: include other file (do HTML escapes)
    elsif content_line =~ /POKI_RUN_COMMAND{{(.+)}}HERE/
      cmd = $1
      run_command(cmd, output_handle, true)

    # Page-content directive: include other file (do HTML escapes)
    elsif content_line =~ /POKI_RUN_COMMAND_TOLERATING_ERROR{{(.+)}}HERE/
      cmd = $1
      run_command_tolerating_error(cmd, output_handle)

    # Page-content directive: link to sibling in pageset.
    elsif content_line =~ /POKI_PUT_LINK_FOR_PAGE\(([^)]+)\)HERE/
      other_page_link = $1
      other_page_name = other_page_link.sub(/#.*/, '')
      other_page_title = page_map[other_page_name]
      if other_page_title.nil?
        raise "Couldn't find page title for \"#{other_page_name}\" in #{config_file_name}."
      end
      href = "<a href=\"#{other_page_link}\">#{other_page_title}</a>"
      content_line.sub!(/POKI_PUT_LINK_FOR_PAGE\([^)]+\)HERE/, href)
      output_handle.puts(content_line)

    # Page-content directive: automark <h1>, <h2>, etc. with jump-to tags so they can be found by the
    # table of contents. Example: <h1>Title</h1> becomes <h1>Title</h1> <a id="#Title">
    elsif content_line =~ /<h([1-9])>(.*)<\/h[1-9]>/
      tag = $2.strip
      # If there's a section with a space in it (e.g. "Naming conventions") then
      # make the href text the same but underscorify the link itself (e.g.
      # "Naming_conventions").
      #output_handle.write(content_line.chomp + "  <a id=\"#{tag.gsub(' ', '_')}\"/>")
      output_handle.print("<a id=\"#{tag.gsub(' ', '_')}\"/>")
      output_handle.write(content_line)

    else
      output_handle.write(content_line)
    end
  end
end

# ----------------------------------------------------------------
def generate_toc(input_file_name, output_handle)
  # Read all the <h1>, <h2>, <h3>, etc. from the current file and create internal links
  tags   = []
  depths = {}
  File.readlines(input_file_name).each do |scan_line|
    if scan_line =~ /^<h([1-9])>(.*)<\/h[1-9]>/
      depth = $1
      tag   = $2.strip
      tags << tag
      depths[tag] = depth.to_i - 1
    end
  end

  output_handle.puts('<div class="pokitoc">')
  output_handle.puts("<center><b>Contents:</b></center>")
  tags.each do |tag|
    # Indent h2 more than h1, h3 more than h2, etc.
    depths[tag].times{output_handle.write "&nbsp;&nbsp;&nbsp;&nbsp;"}
    output_handle.write "&bull;&nbsp;"
    # If there's a section with a space in it (e.g. "Naming conventions") then
    # make the href text the same but underscorify the link itself (e.g.
    # "Naming_conventions").
    output_handle.write "<a href=\"##{tag.gsub(' ', '_')}\">#{tag}</a>"
    output_handle.puts "<br/>"
  end
  output_handle.puts("</div>")
  output_handle.puts("<p/>")
end

# ----------------------------------------------------------------
def include_escaped(included_file_name, output_handle)
  write_card(File.readlines(included_file_name), output_handle, true)
end

# ----------------------------------------------------------------
def run_command(cmd, output_handle, do_escape)
  cmd_output = `#{cmd} 2>&1`
  status = $?.to_i
  if status != 0
    raise "\"#{cmd}\" exited with non-zero code #{status}."
  end
  write_card(['$ '+cmd] + cmd_output.split(/\n/), output_handle, do_escape)
end

# ----------------------------------------------------------------
def run_command_tolerating_error(cmd, output_handle)
  cmd_output = `#{cmd} 2>&1`
  write_card(['$ '+cmd] + cmd_output.split(/\n/), output_handle, true)
end

# ----------------------------------------------------------------
def run_content_generator(cmd, output_handle)
  cmd_output = `#{cmd} 2>&1`
  status = $?.to_i
  if status != 0
    raise "\"#{cmd}\" exited with non-zero code #{status}."
  end
  output_handle.puts(cmd_output)
end

# ----------------------------------------------------------------
def cardify(content_line, output_handle, do_escape)
  write_card([content_line], output_handle, do_escape)
end

# ----------------------------------------------------------------
def write_card(content_lines, output_handle, do_escape)
  output_handle.puts('<p/>')
  output_handle.puts('<div class="pokipanel">')
  output_handle.puts('<pre>')
  content_lines.each do |content_line|
    if do_escape
      output_handle.puts(html_escape_line(content_line))
    else
      output_handle.puts(content_line)
    end
  end
  output_handle.puts('</pre>')
  output_handle.puts('</div>')
  output_handle.puts('<p/>')
end

# ----------------------------------------------------------------
def html_escape_line(line)
  line.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").rstrip
end

# ================================================================
# Top-down programming style, please.
main()