rdoc-perl_pod 1.0

data/History.txt

@@ -0,0 +1,5 @@
+=== 1.0 / 2010-12-19
+
+* Major enhancement
+  * Split from rdoc
+

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/rdoc/discover.rb
+lib/rdoc/parser/perl_pod.rb
+test/test_rdoc_parser_perl.rb

data/README.txt

@@ -0,0 +1,33 @@
+= rdoc-perl_pod
+
+* https://github.com/rdoc/rdoc-perl_pod
+
+== DESCRIPTION:
+
+A parser for Perl's POD documentation format.  Allows Perl and Ruby
+documentation to be used together.
+
+== FEATURES/PROBLEMS:
+
+* No maintainer
+* Parses .pl and .pm files
+
+== SYNOPSIS:
+
+After installing rdoc-perl_pod use RDoc on some .pl or .pm files
+
+== REQUIREMENTS:
+
+* RDoc
+* Perl files
+
+== INSTALL:
+
+* gem install rdoc-perl_pod
+
+== LICENSE:
+
+Unknown
+
+Copyright (c) Huge Sasse
+

data/Rakefile

@@ -0,0 +1,22 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.plugin :git
+Hoe.plugin :isolate
+Hoe.plugin :minitest
+Hoe.plugins.delete :rubyforge
+
+Hoe.spec 'rdoc-perl_pod' do
+  developer 'Eric Hodel', 'drbrain@segment7.net'
+  developer 'Hugh Sasse', 'hgs@dmu.ac.uk'
+
+  extra_deps << ['rdoc', '~> 3']
+  extra_dev_deps << ['isolate', '~> 3']
+
+  self.rubyforge_name = 'rdoc'
+  self.isolate_dir = 'tmp/isolated'
+end
+
+# vim: syntax=Ruby

data/lib/rdoc/discover.rb

@@ -0,0 +1,6 @@
+begin
+  gem 'rdoc', '~> 3'
+  require 'rdoc/parser/perl_pod'
+rescue Gem::LoadError
+end
+

data/lib/rdoc/parser/perl_pod.rb

@@ -0,0 +1,163 @@
+require 'rdoc'
+require 'rdoc/parser'
+
+##
+# This is an attamept to write a basic parser for Perl's POD (Plain old
+# Documentation) format.  Ruby code must co-exist with Perl, and some tasks
+# are easier in Perl than Ruby because of existing libraries.
+#
+# One difficult is that Perl POD has no means of identifying the classes
+# (packages) and methods (subs) with which it is associated, it is more like
+# literate programming in so far as it just happens to be in the same place as
+# the code, but need not be.
+#
+# We would like to support all the markup the POD provides so that it will
+# convert happily to HTML.  At the moment I don't think I can do that: time
+# constraints.
+
+class RDoc::Parser::PerlPOD < RDoc::Parser
+
+  VERSION = '1.0'
+
+  parse_files_matching(/.p[lm]$/)
+
+  ##
+  # Prepare to parse a perl file
+
+  def initialize(top_level, file_name, content, options, stats)
+    super
+
+    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
+
+    preprocess.handle @content do |directive, param|
+      warn "Unrecognized directive '#{directive}' in #{@file_name}"
+    end
+  end
+
+  ##
+  # Extract the Pod(-like) comments from the code.  At its most basic there
+  # will ne no need to distinguish between the different types of header, etc.
+  #
+  # This uses a simple finite state machine, in a very procedural pattern. I
+  # could "replace case with polymorphism" but I think it would obscure the
+  # intent, scatter the code all over tha place.  This machine is necessary
+  # because POD requires that directives be preceded by blank lines, so
+  # reading line by line is necessary, and preserving state about what is seen
+  # is necesary.
+
+  def scan
+    @top_level.comment ||= ""
+    state=:code_blank
+    line_number = 0
+    line = nil
+
+    # This started out as a really long nested case statement,
+    # which also led to repetitive code.  I'd like to avoid that
+    # so I'm using a "table" instead.
+
+    # Firstly we need some procs to do the transition and processing
+    # work.  Because these are procs they are closures, and they can
+    # use variables in the local scope.
+    #
+    # First, the "nothing to see here" stuff.
+    code_noop = lambda do
+      if line =~ /^\s+$/
+        state = :code_blank
+      end
+    end
+
+    pod_noop = lambda do
+      if line =~ /^\s+$/
+        state = :pod_blank
+      end
+      @top_level.comment += filter(line)
+    end
+
+    begin_noop = lambda do
+      if line =~ /^\s+$/
+        state = :begin_blank
+      end
+      @top_level.comment += filter(line)
+    end
+
+    # Now for the blocks that process code and comments...
+
+    transit_to_pod = lambda do
+      case line
+      when /^=(?:pod|head\d+)/
+        state = :pod_no_blank
+        @top_level.comment += filter(line)
+      when /^=over/
+        state = :over_no_blank
+        @top_level.comment += filter(line)
+      when /^=(?:begin|for)/
+        state = :begin_no_blank
+      end
+    end
+
+    process_pod = lambda do
+      case line
+      when  /^\s*$/ then
+        state = :pod_blank
+        @top_level.comment += filter(line)
+      when /^=cut/ then
+        state = :code_no_blank
+      when /^=end/ then
+        $stderr.puts "'=end' unexpected at #{line_number} in #{@file_name}"
+      else
+        @top_level.comment += filter(line)
+      end
+    end
+
+    process_begin = lambda do
+      case line
+      when  /^\s*$/ then
+        state = :begin_blank
+        @top_level.comment += filter(line)
+      when /^=end/ then
+        state = :code_no_blank
+      when /^=cut/
+        $stderr.puts "'=cut' unexpected at #{line_number} in #{@file_name}"
+      else
+        @top_level.comment += filter(line)
+      end
+    end
+
+    transitions = { :code_no_blank => code_noop,
+      :code_blank => transit_to_pod,
+      :pod_no_blank => pod_noop,
+      :pod_blank => process_pod,
+      :begin_no_blank => begin_noop,
+      :begin_blank => process_begin,
+    }
+
+    @content.each_line do |l|
+      line = l
+      line_number += 1
+      transitions[state].call
+    end
+
+    @top_level
+  end
+
+  ##
+  # Filter the perl markup that does the same as the rdoc filtering.  Only
+  # basic for now. Will probably need a proper parser to cope with C<<...>>
+  # etc.
+
+  def filter(comment)
+    return '' if comment =~ /^=pod\s*$/
+    comment.gsub!(/^=pod/, '==')
+
+    comment.gsub!(/^=head(\d+)/) do
+      "=" * $1.to_i
+    end
+    comment.gsub!(/=item/, '');
+    comment.gsub!(/C<(.*?)>/, '<tt>\1</tt>');
+    comment.gsub!(/I<(.*?)>/, '<i>\1</i>');
+    comment.gsub!(/B<(.*?)>/, '<b>\1</b>');
+    comment
+  end
+
+end
+

data/test/test_rdoc_parser_perl.rb

@@ -0,0 +1,74 @@
+require 'stringio'
+require 'tempfile'
+require 'rubygems'
+require 'minitest/autorun'
+require 'rdoc'
+require 'rdoc/options'
+require 'rdoc/parser/perl_pod'
+
+class TestRdocParserPerlPOD < MiniTest::Unit::TestCase
+
+  def setup
+    @tempfile = Tempfile.new self.class.name
+    filename = @tempfile.path
+
+    @top_level = RDoc::TopLevel.new filename
+    @fn = filename
+    @options = RDoc::Options.new
+    @stats = RDoc::Stats.new 0
+  end
+
+  def teardown
+    @tempfile.close
+  end
+
+  def test_uncommented_perl
+    content = <<-EOF
+while (<>) {
+  tr/a-z/A-Z;
+  print
+}
+    EOF
+
+    comment =  util_get_comment content
+    assert_equal "", comment
+  end
+
+  def test_perl_without_pod
+    content = <<-EOF
+#!/usr/local/bin/perl
+#
+#This is a pointless perl program because it does -p.
+#
+while(<>) {print;}:
+    EOF
+
+    comment = util_get_comment content
+    assert_equal "", comment
+  end
+
+  def test_simple_pod_no_structure
+    content = <<-EOF
+=begin pod
+
+This just contains plain old documentation
+
+=end
+    EOF
+    comment = util_get_comment content
+    assert_equal 'This just contains plain old documentation', comment
+  end
+
+  # Get the comment of the @top_level when it has processed the input.
+  def util_get_comment(content)
+    parser = util_parser content
+    parser.scan.comment
+  end
+
+  # create a new parser with the supplied content.
+  def util_parser(content)
+    RDoc::Parser::PerlPOD.new @top_level, @fn, content, @options, @stats
+  end
+
+end
+

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification 
+name: rdoc-perl_pod
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- Eric Hodel
+- Hugh Sasse
+autorequire: 
+bindir: bin
+cert_chain: 
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIDNjCCAh6gAwIBAgIBADANBgkqhkiG9w0BAQUFADBBMRAwDgYDVQQDDAdkcmJy
+  YWluMRgwFgYKCZImiZPyLGQBGRYIc2VnbWVudDcxEzARBgoJkiaJk/IsZAEZFgNu
+  ZXQwHhcNMDcxMjIxMDIwNDE0WhcNMDgxMjIwMDIwNDE0WjBBMRAwDgYDVQQDDAdk
+  cmJyYWluMRgwFgYKCZImiZPyLGQBGRYIc2VnbWVudDcxEzARBgoJkiaJk/IsZAEZ
+  FgNuZXQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCbbgLrGLGIDE76
+  LV/cvxdEzCuYuS3oG9PrSZnuDweySUfdp/so0cDq+j8bqy6OzZSw07gdjwFMSd6J
+  U5ddZCVywn5nnAQ+Ui7jMW54CYt5/H6f2US6U0hQOjJR6cpfiymgxGdfyTiVcvTm
+  Gj/okWrQl0NjYOYBpDi+9PPmaH2RmLJu0dB/NylsDnW5j6yN1BEI8MfJRR+HRKZY
+  mUtgzBwF1V4KIZQ8EuL6I/nHVu07i6IkrpAgxpXUfdJQJi0oZAqXurAV3yTxkFwd
+  g62YrrW26mDe+pZBzR6bpLE+PmXCzz7UxUq3AE0gPHbiMXie3EFE0oxnsU3lIduh
+  sCANiQ8BAgMBAAGjOTA3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
+  BBS5k4Z75VSpdM0AclG2UvzFA/VW5DANBgkqhkiG9w0BAQUFAAOCAQEAHagT4lfX
+  kP/hDaiwGct7XPuVGbrOsKRVD59FF5kETBxEc9UQ1clKWngf8JoVuEoKD774dW19
+  bU0GOVWO+J6FMmT/Cp7nuFJ79egMf/gy4gfUfQMuvfcr6DvZUPIs9P/TlK59iMYF
+  DIOQ3DxdF3rMzztNUCizN4taVscEsjCcgW6WkUJnGdqlu3OHWpQxZBJkBTjPCoc6
+  UW6on70SFPmAy/5Cq0OJNGEWBfgD9q7rrs/X8GGwUWqXb85RXnUVi/P8Up75E0ag
+  14jEc90kN+C7oI/AGCBN0j6JnEtYIEJZibjjDJTSMWlUKKkj30kq7hlUC2CepJ4v
+  x52qPcexcYZR7w==
+  -----END CERTIFICATE-----
+
+date: 2010-12-23 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 3
+        version: "3"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 2
+        - 0
+        - 0
+        version: 2.0.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: isolate
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 3
+        version: "3"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 2
+        - 7
+        - 0
+        version: 2.7.0
+  type: :development
+  version_requirements: *id004
+description: |-
+  A parser for Perl's POD documentation format.  Allows Perl and Ruby
+  documentation to be used together.
+email: 
+- drbrain@segment7.net
+- hgs@dmu.ac.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/rdoc/discover.rb
+- lib/rdoc/parser/perl_pod.rb
+- test/test_rdoc_parser_perl.rb
+has_rdoc: true
+homepage: https://github.com/rdoc/rdoc-perl_pod
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: rdoc
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A parser for Perl's POD documentation format
+test_files: 
+- test/test_rdoc_parser_perl.rb