Class: History

Inherits:
Object
  • Object
show all
Defined in:
lib/history.rb,
lib/history/release.rb

Overview

The History class is a HISTORY file parser. It parses HISTORY files into a structure of individual release sections.

The file is expected to be in RDoc or simple Markdown format with each section beginning with a secondary header (‘==` or `##`) giving version and date of release, then a note followed by a point by point outline of changes.

For example:

== 1.0.0 / 2009-10-07

Say something about this version.

Changes:

* outline oimportant changelog items

‘Changes:` is used as a parsing marker. While optional, it helps the parser find the list of changes, rather than looking for an asterisk or digit, so that ordered and unordered lists can be used in the note section too.

Ideally, this class will be continuely imporved to handle greater variety of layout.

Defined Under Namespace

Classes: Release

Constant Summary collapse

DEFAULT_FILE =

File glob for finding the HISTORY file.

'{History}{,.*}'
HEADER_RE =

Match against version number string.

/^[=#]+\s*\d+\.\S+/
CASEFOLD =

Convenience constant for ‘File::FNM_CASEFOLD`.

File::FNM_CASEFOLD

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(io = nil, opts = {}) ⇒ History

New History.



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/history.rb', line 87

def initialize(io=nil, opts={})
  if Hash === io
    opts = file
    io   = nil
  end

  @releases = []

  case io
  when String
    parse(io)
  when Pathname
    @file = io
    parse(io.read)
  when File
    @file = io.path
    parse(io.read)
  else
    parse(io.read)
  end

  @file = opts[:file] if opts.key?(:file)
end

Instance Attribute Details

#file ⇒ Object (readonly)

HISTORY file’s path.



78
79
80
 
# File 'lib/history.rb', line 78

def file
  @file
end

#releases ⇒ Object (readonly)

List of release entries.



84
85
86
 
# File 'lib/history.rb', line 84

def releases
  @releases
end

#text ⇒ Object (readonly)

HISTORY file’s raw contents.



81
82
83
 
# File 'lib/history.rb', line 81

def text
  @text
end

Class Method Details

.at(root = Dir.pwd) ⇒ Object

Lookup history file given a project root directory. If a history file is not present, assume a default file name of ‘HISTORY`.



54
55
56
57
58
59
60
61
 
# File 'lib/history.rb', line 54

def self.at(root=Dir.pwd)
  if file = Dir.glob(File.join(root, DEFAULT_FILE), CASEFOLD).first
    new(Pathname.new(file))
  else
    file = File.join(root, 'HISTORY')
    new(:file=>file)
  end
end

.exist?(path = Dir.pwd) ⇒ Boolean

Does a HISTORY file exist?

Returns:

  • (Boolean) 


69
70
71
72
73
74
75
 
# File 'lib/history.rb', line 69

def self.exist?(path=Dir.pwd)
  if File.directory?(path)
    Dir.glob(File.join(path, DEFAULT_FILE), CASEFOLD).first
  else
    File.exist?(path) ? path : false
  end
end

.find(root = Dir.pwd) ⇒ Object

Alias for #at.



64
65
66
 
# File 'lib/history.rb', line 64

def self.find(root=Dir.pwd)
  at(root)
end

.parse(text) ⇒ Object

Parse history from given text.



42
43
44
 
# File 'lib/history.rb', line 42

def self.parse(text)
  new(text.to_s)
end

.read(file) ⇒ Object

Read and parse history from given file.



47
48
49
 
# File 'lib/history.rb', line 47

def self.read(file)
  new(Pathname.new(file))
end

Instance Method Details

#[](version) ⇒ Object

Lookup release by version.



134
135
136
 
# File 'lib/history.rb', line 134

def [](version)
  releases.find{ |r| r.version == version }
end

#exist? ⇒ Boolean

Does history file exist?

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/history.rb', line 112

def exist?
  File.file?(@file)
end

#parse(text) ⇒ Object

Parse History text.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/history.rb', line 117

def parse(text)
  return unless text
  releases, entry = [], nil
  text.each_line do |line|
    if HEADER_RE =~ line
      releases << Release.new(entry) if entry
      entry = line
    else
      next unless entry
      entry << line
    end
  end
  releases << Release.new(entry)
  @releases = releases
end

#release ⇒ Object

Returns first entry in release list.



139
140
141
 
# File 'lib/history.rb', line 139

def release
  releases.first
end