Class: RDoc::Parser::ChangeLog

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, ::RDoc::Parser
Instance Chain: self, Text, ::RDoc::Parser
Inherits:	RDoc::Parser Object RDoc::Parser RDoc::Parser::ChangeLog
Defined in:	lib/rdoc/parser/changelog.rb

Overview

A ChangeLog file parser.

This parser converts a ChangeLog into an ::RDoc::Markup::Document. When viewed as HTML a ChangeLog page will have an entry for each day's entries in the sidebar table of contents.

This parser is meant to parse the MRI ChangeLog, but can be used to parse any GNU style Change Log.

Class Attribute Summary

::RDoc::Parser - Inherited

.parsers

An Array of arrays that maps file extension (or name) regular expressions to parser classes that will parse matching filenames.

Class Method Summary

::RDoc::Parser - Inherited

.alias_extension	::RDoc::Alias an extension to another extension.
.binary?	Determines if the file is a “binary” file which basically means it has content that an ::RDoc::RDoc parser shouldn't try to consume.
.can_parse	Return a parser that can handle a particular extension.
.can_parse_by_name	Returns a parser that can handle the extension for #file_name.
.check_modeline	Returns the file type from the modeline in #file_name
.for	Finds and instantiates the correct parser for the given #file_name and `content`.
.new	Creates a new ::RDoc::Parser storing `top_level`, #file_name, `content`, `options` and `stats` in instance variables.
.parse_files_matching	Record which file types this parser can understand.
.process_directive	Processes common directives for CodeObjects for the C and Ruby parsers.
.remove_modeline	Removes an emacs-style modeline from the first line of the document.
.use_markup	If there is a `markup: parser_name` comment at the front of the file, use it to determine the parser.
.zip?	Checks if `file` is a zip file in disguise.

Instance Attribute Summary

::RDoc::Parser - Inherited

#file_name

The name of the file being parsed.

Instance Method Summary

#continue_entry_body(entry_body, continuation)

Attaches the continuation of the previous line to the entry_body.
#create_document(groups)

Creates an ::RDoc::Markup::Document given the groups of ChangeLog entries.
#create_entries(entries)

Returns a list of ChangeLog entries an ::RDoc::Markup nodes for the given entries.
#create_items(items)

Returns an ::RDoc::Markup::List containing the given items in the ChangeLog.
#group_entries(entries)

Groups entries by date.
#parse_entries

Parses the entries in the ChangeLog.
#scan

Converts the ChangeLog into an ::RDoc::Markup::Document

Constructor Details

This class inherits a constructor from RDoc::Parser

Instance Method Details

#continue_entry_body(entry_body, continuation)

Attaches the continuation of the previous line to the entry_body.

Continued function listings are joined together as a single entry. Continued descriptions are joined to make a single paragraph.

[ GitHub ]

# File 'lib/rdoc/parser/changelog.rb', line 27


def continue_entry_body entry_body, continuation
  return unless last = entry_body.last

  if last =~ /\)\s*\z/ and continuation =~ /\A\(/ then
    last.sub!(/\)\s*\z/, ',')
    continuation.sub!(/\A\(/, '')
  end

  if last =~ /\s\z/ then
    last << continuation
  else
    last << ' ' << continuation
  end
end

#create_document(groups)

Creates an ::RDoc::Markup::Document given the groups of ChangeLog entries.

[ GitHub ]

# File 'lib/rdoc/parser/changelog.rb', line 45


def create_document groups
  doc = RDoc::Markup::Document.new
  doc.omit_headings_below = 2
  doc.file = @top_level

  doc << RDoc::Markup::Heading.new(1, File.basename(@file_name))
  doc << RDoc::Markup::BlankLine.new

  groups.sort_by do |day,| day end.reverse_each do |day, entries|
    doc << RDoc::Markup::Heading.new(2, day.dup)
    doc << RDoc::Markup::BlankLine.new

    doc.concat create_entries entries
  end

  doc
end

#create_entries(entries)

Returns a list of ChangeLog entries an ::RDoc::Markup nodes for the given entries.

[ GitHub ]

# File 'lib/rdoc/parser/changelog.rb', line 67


def create_entries entries
  out = []

  entries.each do |entry, items|
    out << RDoc::Markup::Heading.new(3, entry)
    out << RDoc::Markup::BlankLine.new

    out << create_items(items)
  end

  out
end

#create_items(items)

Returns an ::RDoc::Markup::List containing the given items in the ChangeLog

[ GitHub ]

# File 'lib/rdoc/parser/changelog.rb', line 84


def create_items items
  list = RDoc::Markup::List.new :NOTE

  items.each do |item|
    item =~ /\A(.*?(?:\([^)]+\))?):\s*/

    title = $1
    body = $'

    paragraph = RDoc::Markup::Paragraph.new body
    list_item = RDoc::Markup::ListItem.new title, paragraph
    list << list_item
  end

  list
end

#group_entries(entries)

Groups entries by date.

[ GitHub ]

# File 'lib/rdoc/parser/changelog.rb', line 104


def group_entries entries
  @time_cache ||= {}
  entries.group_by do |title, _|
    begin
      time = @time_cache[title]
      (time || Time.parse(title)).strftime '%Y-%m-%d'
    rescue NoMethodError, ArgumentError
      time, = title.split '  ', 2
      Time.parse(time).strftime '%Y-%m-%d'
    end
  end
end

#parse_entries

Parses the entries in the ChangeLog.

Returns an Array of each ChangeLog entry in order of parsing.

A ChangeLog entry is an Array containing the ChangeLog title (date and committer) and an Array of ChangeLog items (file and function changed with description).

An example result would be:

[ 'Tue Dec  4 08:33:46 2012  Eric Hodel  <drbrain@segment7.net>',
  [ 'README.EXT:  Converted to RDoc format',
    'README.EXT.ja:  ditto']]

[ GitHub ]

# File 'lib/rdoc/parser/changelog.rb', line 132


def parse_entries
  @time_cache ||= {}
  entries = []
  entry_name = nil
  entry_body = []

  @content.each_line do |line|
    case line
    when /^\s*$/ then
      next
    when /^\w.*/ then
      entries << [entry_name, entry_body] if entry_name

      entry_name = $&

      begin
        time = Time.parse entry_name
        @time_cache[entry_name] = time
        # HACK Ruby 1.8 does not raise ArgumentError for Time.parse "Other"
        entry_name = nil unless entry_name =~ /#{time.year}/
      rescue NoMethodError
        # HACK Ruby 2.1.2 and earlier raises NoMethodError if time part is absent
        entry_name.split '  ', 2
      rescue ArgumentError
        if /out of range/ =~ $!.message
          Time.parse(entry_name.split('  ', 2)[0]) rescue entry_name = nil
        else
          entry_name = nil
        end
      end

      entry_body = []
    when /^(\t| {8})?\*\s*(.*)/ then # "\t* file.c (func): ..."
      entry_body << $2
    when /^(\t| {8})?\s*(\(.*)/ then # "\t(func): ..."
      entry = $2

      if entry_body.last =~ /:/ then
        entry_body << entry
      else
        continue_entry_body entry_body, entry
      end
    when /^(\t| {8})?\s*(.*)/ then
      continue_entry_body entry_body, $2
    end
  end

  entries << [entry_name, entry_body] if entry_name

  entries.reject! do |(entry,_)|
    entry == nil
  end

  entries
end

#scan

Converts the ChangeLog into an ::RDoc::Markup::Document

[ GitHub ]

# File 'lib/rdoc/parser/changelog.rb', line 191


def scan
  @time_cache = {}
  entries = parse_entries
  grouped_entries = group_entries entries

  doc = create_document grouped_entries

  @top_level.comment = doc

  @top_level
end