class Detroit::VClog

VClog service generates changelogs from SCM commit messages.

TODO: Support multiple formats in one pass.

Constants

VALID_FORMATS
VALID_TYPES

Attributes

id[RW]

Show revision/reference numbers (true/false)?

level[RW]

Minimum change level to include.

output[RW]

Output is either a file name with a clear extension to infer type or a list of such file names, or a hash mapping file name to type.

output: NOTES.rdoc

output:
  - NOTES.rdoc
  - site/notes.html

output:
  NOTES: markdown
  site/notes.html: html

Recognized formats include ‘html`, `xml`, `atom`, `rss`, `json`, `yaml`, `rdoc`, `markdown` and `md`, `ansi`, `gnu` and `txt`.

point[RW]

Divide messages into change points (true/false)?

style[RW]

Some formats can reference an optional stylesheet (namely xml and html).

summary[RW]

Reduced detail?

title[RW]

Some formats, such as rdoc, use a title field. Defaults to project title.

type[R]

Changelog layout type (changelog or history). Default is changelog.

version[RW]

Current version of project.

Public Class Methods

man_page() click to toggle source
# Convert formats into a hash of `format => fname`.
def formats_mapping(formats=nil)
  formats ||= self.formats
  case formats
  when String
    formats_mapping([formats])
  when Array
    h = {}
    formats.each do |format|
      h[format] = infer_output_fname(format, type)
    end
    h
  when Hash
    formats
  else
    raise ArgumentError, "invalid formats field -- #{formats.inspect}"
  end
end

#
def infer_output_fname(format, type)
  fname = case type
          when 'rel', 'history'
            'history'
          else
            'changelog'
          end 
  #apply_naming_policy(fname, log_format.downcase)
  ext = format_extension(format)
  fname + ext
end

#
def format_extension(format)
  ".#{format}"
end

# # # def valid? # return false unless output.all?{ |x, f| f =~ VALID_FORMATS } # return false unless type =~ VALID_TYPES # return true # end

# File lib/detroit-vclog.rb, line 344
def self.man_page
  File.dirname(__FILE__)+'/../man/detroit-vclog.5'
end

Public Instance Methods

assemble(station, options={}) click to toggle source
# File lib/detroit-vclog.rb, line 88
def assemble(station, options={})
  case station
  when :document then document
  when :reset    then reset
  when :purge    then purge
  end
end
assemble?(station, options={}) click to toggle source
# File lib/detroit-vclog.rb, line 79
def assemble?(station, options={})
  case station
  when :document then true
  when :reset    then true
  when :purge    then true
  end
end
clean() click to toggle source

TODO: anything to remove ?

# File lib/detroit-vclog.rb, line 156
def clean
end
current?() click to toggle source

TODO: Check the output files and see if they are older than the current change log.

@return [Boolean] whether output is up-to-date

# File lib/detroit-vclog.rb, line 103
def current?
  false
  #output_mapping.each do |file, format|
  #  return false if outofdate?(file, *dnote_session.files)
  #else
  #  "VCLogs are current."
  #end
end
document() click to toggle source

Generate the log.

# File lib/detroit-vclog.rb, line 113
def document
  output_mapping.each do |file, format, type|
    next unless verify_format(format, file)
    #file = File.join(output, fname)
    trace "vclog --#{type} -f #{format} >> #{file}"
    if dryrun?
      false # file hasn't changed
    else
      changed = save(file, format, type)
      if changed
        report "Updated " + relative_from_root(file)
      else
        report "Current " + relative_from_root(file)
      end
      changed
    end
  end
end
purge() click to toggle source

Remove output directory output directory.

# File lib/detroit-vclog.rb, line 160
def purge
  output_mapping.each do |file, format, type|
    if File.exist?(file)
      rm(file)
      report "Removed #{file}"
    end
  end
end
render(format, doctype) click to toggle source

Convert log to desired format.

# File lib/detroit-vclog.rb, line 175
def render(format, doctype)
  doctype = type if doctype.nil?
  doctype = 'history'   if doctype == 'rel'
  doctype = 'changelog' if doctype == 'log'

  options = {
    :type       => doctype,
    :format     => format,
    :stylesheet => style,
    :level      => level,
    :point      => point,
    :is         => id,
    :version    => version,
    :title      => title,
    :summary    => summary
  }

  repo.report(options)
end
repo() click to toggle source

Access to version control system.

# File lib/detroit-vclog.rb, line 170
def repo
  @repo ||= VCLog::Repo.new(project.root.to_s)
end
reset() click to toggle source

Mark the output directory as out of date.

# File lib/detroit-vclog.rb, line 146
def reset
  output_mapping.each do |file, format, type|
    if File.exist?(file)
      utime(0,0,file)
      report "Reset #{file}."
    end
  end
end
save(file, format, type) click to toggle source

Save changelog/history to output file.

# File lib/detroit-vclog.rb, line 133
def save(file, format, type)
  text = render(format, type)
  if File.exist?(file)
    return false if File.read(file) == text
  else
    dir = File.dirname(file)
    mkdir_p(dir) unless File.exist?(dir)
  end
  File.open(file, 'w'){ |f| f << text }
  return true
end
type=(f) click to toggle source

Set output type.

# File lib/detroit-vclog.rb, line 67
def type=(f)
  type = f.to_s.downcase
  if type !~ VALID_TYPES
    abort "Invalid vclog type - #{type}"
  end
  @type = type
end

Private Instance Methods

infer_format(file) click to toggle source
# File lib/detroit-vclog.rb, line 231
def infer_format(file)
  fmt = File.extname(file).sub('.','')
  fmt = DEFAULT_FORMAT if type.empty?
  fmt
end
infer_type(file) click to toggle source
# File lib/detroit-vclog.rb, line 238
def infer_type(file)
  case file
  when /history/i
    'history'
  when /log/
    'changelog'
  else
    type
  end
end
initialize_defaults() click to toggle source
# File lib/detroit-vclog.rb, line 264
def initialize_defaults
  @version    = metadata.version
  @title      = metadata.title
  @output     = project.log + 'changelog.atom'
  @type       = 'log'
  @level      = 0
  @summary    = false
end
initialize_requires() click to toggle source
# File lib/detroit-vclog.rb, line 259
def initialize_requires
  require 'vclog'
end
output_mapping() click to toggle source
Convert output into a list of [file, format, type].

++

TODO: apply_naming_policy ?
# File lib/detroit-vclog.rb, line 211
def output_mapping
  @output_mapping ||= (
    list = []
    case output
    when Array
      output.each do |path|
        list << [path, infer_format(path), infer_type(path)]
      end
    when String
      list << [output, infer_format(output), infer_type(output)]
    when Hash
      output.each do |path, format|
        list << [path, format, infer_type(path)]
      end
    end
    list
  )
end
relative_from_root(path) click to toggle source
# File lib/detroit-vclog.rb, line 250
def relative_from_root(path)
  begin
    Pathname.new(path).relative_path_from(project.root)
  rescue
    path
  end
end
verify_format(format, file) click to toggle source
# File lib/detroit-vclog.rb, line 198
def verify_format(format, file)
  if format !~ VALID_FORMATS
    report "Invalid format for `#{file}' - `#{fmt}'."   # report_error
    false
  else
    true
  end
end