history 0.1.0 → 0.2.0

data/.ruby

@@ -54,14 +54,13 @@ title: History
 created: '2010-02-19'
 organization: Rubyworks
 summary: HISTORY and CHANGELOG parser
-version: 0.1.0
-description: ! 'History is a HISTORY and CHANGELOG file parser. It can parse common
-  layouts for these
+version: 0.2.0
+description: ! 'History is a HISTORY file parser. It can parse common HISTORY file
+  layouts
 
-  file types and provide their contents in a structured model. This can be useful
-  for
+  and provide the contents in a structured model. This can be useful for
 
-  a number of things, in particular it can be used to generate tag messages and add
+  a number of things, in particular it can be used to generate tag messages
 
-  pre-release changelogs to relase announcements.'
-date: '2012-05-24'
+  and add pre-release change lists to release announcements.'
+date: '2012-05-25'

data/DEMO.md

@@ -0,0 +1,113 @@
+# History Gem
+
+History is a HISTORY file parser. It can parse common HISTORY file layouts
+and provide the contents in a structured model. This can be useful for
+a number of things, in particular it can be used to generate tag messages
+and add pre-release change lists to release announcements.
+
+# History Class
+
+The history class encapsulates this list of release
+made by a project. It parses a text file by the
+name of HISTORY into it indivdual relase entries.
+
+Given a HISTORY project file containing:
+
+    = RELEASE HISTORY
+
+    == 1.2.0 / 2010-10-18
+
+    Some Dandy description of the 1.2.0 release.
+    This is  multiline description.
+
+    Changes:
+
+    * This is change 1.
+    * This is change 2.
+    * This is change 3.
+
+
+    == 1.1.0 | 2010-06-06 | "Happy Days"
+
+    Some Dandy description of the 1.1.0 release.
+    This is  multiline description. Notice the
+    header varies from the first.
+
+    The description can even have multiple paragraphs.
+
+    Changes:
+
+    * This is change 1.
+    * This is change 2.
+    * This is change 3.
+
+
+    == 1.0.0 / 2010-04-30
+
+    Some Dandy description of the 1.0.0 release.
+    This is  multiline description. Notice that
+    the "changes:" label isn't strictly needed.
+
+    * This is change 1.
+    * This is change 2.
+    * This is change 3.
+
+
+    == 0.9.0 / 2010-04-10
+
+    1. This is change 1.
+    2. This is change 2.
+    3. This is change 3.
+
+    Some Dandy description of the 0.9.0 release.
+    Notice this time that the changes are listed
+    first and are numerically enumerated.
+
+The History class provides an interface to this information.
+The initializer takes the root directory for the project
+and looks for a file called +HISTORY+, optionally ending
+in an extension such as +.txt+ or +.rdoc+, etc.
+
+    history = History.find('tmp/example')
+
+Now we should have an enumeration of each release entry in
+the HISTORY file.
+
+    history.releases.size.assert == 4
+
+The non-plurual #release method will give us the first entry.
+And we can see that it has been parsed into its component
+attributes.
+
+    history.release.header.assert == '== 1.2.0 / 2010-10-18'
+    history.release.notes.assert.index('description of the 1.2.0')
+
+The header is further parsed into version, date and nickname if given.
+
+    history.release.version.assert == '1.2.0'
+    history.release.date.assert    == '2010-10-18'
+
+We should see like results for the other release entries.
+
+    history.releases[2].version.assert == '1.0.0'
+    history.releases[2].date.assert    == '2010-04-30'
+
+    history.releases[2].header.assert == '== 1.0.0 / 2010-04-30'
+    history.releases[2].notes.assert.index('description of the 1.0.0')
+    history.releases[2].changes.assert.index('This is change 1')
+
+Even though there are variations in the formats of each entry they are
+still parsed correctly. For example the second release has a nick name.
+
+    history.releases[1].nickname.assert == 'Happy Days'
+
+And the last entry has it's changes listed before the description.
+
+    history.releases[3].header.assert == '== 0.9.0 / 2010-04-10'
+    history.releases[3].notes.assert.index('description of the 0.9.0')
+    history.releases[3].changes.assert.index('This is change 1')
+
+The history parser is farily simplistic, but it is flexibile enough
+to parse the most common HISTORY file formats.
+
+

data/HISTORY.md

@@ -1,5 +1,15 @@
 # RELEASE HISTORY
 
+## 0.2.0 / 2012-05-25
+
+This the first usable release. There's actual code now ;)
+
+Changes:
+
+* Port code from POM project for initial implementation.
+* Place variant from VCLog project in work directory for reference.
+
+
 ## 0.1.0 / 2012-05-24
 
 This is a place holder release until the first working addition

data/README.md

@@ -9,10 +9,10 @@
 
 ## Description
 
-History is a HISTORY and CHANGELOG file parser. It can parse common layouts for these
-file types and provide their contents in a structured model. This can be useful for
-a number of things, in particular it can be used to generate tag messages and add
-pre-release changelogs to relase announcements.
+History is a HISTORY file parser. It can parse common HISTORY file layouts
+and provide the contents in a structured model. This can be useful for
+a number of things, in particular it can be used to generate tag messages
+and add pre-release change lists to release announcements.
 
 
 ## Copyrights

data/demo/00_intro.md

@@ -0,0 +1,6 @@
+# History Gem
+
+History is a HISTORY file parser. It can parse common HISTORY file layouts
+and provide the contents in a structured model. This can be useful for
+a number of things, in particular it can be used to generate tag messages
+and add pre-release change lists to release announcements.

data/demo/01_history.md

@@ -0,0 +1,105 @@
+# History Class
+
+The history class encapsulates this list of release
+made by a project. It parses a text file by the
+name of HISTORY into it indivdual relase entries.
+
+Given a HISTORY project file containing:
+
+    = RELEASE HISTORY
+
+    == 1.2.0 / 2010-10-18
+
+    Some Dandy description of the 1.2.0 release.
+    This is  multiline description.
+
+    Changes:
+
+    * This is change 1.
+    * This is change 2.
+    * This is change 3.
+
+
+    == 1.1.0 | 2010-06-06 | "Happy Days"
+
+    Some Dandy description of the 1.1.0 release.
+    This is  multiline description. Notice the
+    header varies from the first.
+
+    The description can even have multiple paragraphs.
+
+    Changes:
+
+    * This is change 1.
+    * This is change 2.
+    * This is change 3.
+
+
+    == 1.0.0 / 2010-04-30
+
+    Some Dandy description of the 1.0.0 release.
+    This is  multiline description. Notice that
+    the "changes:" label isn't strictly needed.
+
+    * This is change 1.
+    * This is change 2.
+    * This is change 3.
+
+
+    == 0.9.0 / 2010-04-10
+
+    1. This is change 1.
+    2. This is change 2.
+    3. This is change 3.
+
+    Some Dandy description of the 0.9.0 release.
+    Notice this time that the changes are listed
+    first and are numerically enumerated.
+
+The History class provides an interface to this information.
+The initializer takes the root directory for the project
+and looks for a file called +HISTORY+, optionally ending
+in an extension such as +.txt+ or +.rdoc+, etc.
+
+    history = History.find('tmp/example')
+
+Now we should have an enumeration of each release entry in
+the HISTORY file.
+
+    history.releases.size.assert == 4
+
+The non-plurual #release method will give us the first entry.
+And we can see that it has been parsed into its component
+attributes.
+
+    history.release.header.assert == '== 1.2.0 / 2010-10-18'
+    history.release.notes.assert.index('description of the 1.2.0')
+
+The header is further parsed into version, date and nickname if given.
+
+    history.release.version.assert == '1.2.0'
+    history.release.date.assert    == '2010-10-18'
+
+We should see like results for the other release entries.
+
+    history.releases[2].version.assert == '1.0.0'
+    history.releases[2].date.assert    == '2010-04-30'
+
+    history.releases[2].header.assert == '== 1.0.0 / 2010-04-30'
+    history.releases[2].notes.assert.index('description of the 1.0.0')
+    history.releases[2].changes.assert.index('This is change 1')
+
+Even though there are variations in the formats of each entry they are
+still parsed correctly. For example the second release has a nick name.
+
+    history.releases[1].nickname.assert == 'Happy Days'
+
+And the last entry has it's changes listed before the description.
+
+    history.releases[3].header.assert == '== 0.9.0 / 2010-04-10'
+    history.releases[3].notes.assert.index('description of the 0.9.0')
+    history.releases[3].changes.assert.index('This is change 1')
+
+The history parser is farily simplistic, but it is flexibile enough
+to parse the most common HISTORY file formats.
+

data/demo/applique/ae.rb

@@ -0,0 +1,2 @@
+require 'ae'
+require 'ae/should'

data/demo/applique/fixtures.rb

@@ -0,0 +1,25 @@
+require 'fileutils'
+
+FIXTURE_DIR = 'tmp/example/'
+
+# Remove the example project if it exists.
+Before :all do
+  FileUtils.rm_r(FIXTURE_DIR) if File.exist?(FIXTURE_DIR)
+  File.open(FIXTURE_DIR + '/.ruby', 'w'){ |f| f << "" }
+end
+
+When 'Given an empty project directory' do
+  FileUtils.rm_r(FIXTURE_DIR) if File.exist?(FIXTURE_DIR)
+end
+
+When 'iven a ((([\.\w]+))) project file' do |name, text|
+  FileUtils.mkdir_p(FIXTURE_DIR)
+  File.open(FIXTURE_DIR + name, 'w') do |f|
+    f << text
+  end
+end
+
+When 'no ((([\.\w]+))) file in a project' do |name|
+  FileUtils.rm(FIXTURE_DIR + name)
+end
+

data/demo/applique/history.rb

@@ -0,0 +1 @@
+require 'history'

data/lib/history.rb

@@ -1 +1,124 @@
-# TODO
+#require 'history/core_ext'
+require 'history/release'
+
+# 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.
+#
+class History
+
+  # File glob for finding the HISTORY file.
+  DEFAULT_FILE = '{History}{,.*}'
+
+  # Match against version number string.
+  HEADER_RE = /^[=#]+\s*\d+\.\S+/
+
+  # Convenience constant for `File::FNM_CASEFOLD`.
+  CASEFOLD = File::FNM_CASEFOLD
+
+  #
+  def self.parse(text, opts={})
+    opts[:text] = text
+    new(opts[:file], opts)
+  end
+
+  def self.text(text, opts={})
+    parse(text, opts)
+  end
+
+  #
+  def self.file(file)
+    new(file)
+  end
+
+  #
+  def self.find(root=Dir.pwd)
+    file = Dir.glob(File.join(root, DEFAULT_FILE), CASEFOLD).first
+    new(file)
+  end
+
+  # HISTORY file's path.
+  attr :file
+
+  # HISTORY file's raw contents.
+  attr :text
+
+  # List of release entries.
+  attr :releases
+
+  # New History.
+  def initialize(file=nil, opts={})
+    if Hash === file
+      opts = file
+      file = nil
+    end
+
+    @file = file
+    @text = opts[:text]
+
+    if @file
+      # if file is given but no text, raise error if file not found
+      raise "file not found" unless File.exist?(@file) unless @text
+    else
+      @file = Dir.glob(DEFAULT_FILE, CASEFOLD).first || 'HISTORY'
+    end
+
+    unless @text
+      @text = File.read(@file) if File.exist?(@file)
+    end
+
+    parse
+  end
+
+  # Read and parse the Histoy file.
+  def parse
+    @releases = []
+    entry = nil
+
+    if text
+      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)
+    end
+  end
+
+  # Lookup release by version.
+  def [](version)
+    releases.find{ |r| r.version == version }
+  end
+
+  # Returns first entry in releases list.
+  def release
+    releases.first
+  end
+
+end #class History

data/lib/history.yml

@@ -0,0 +1,66 @@
+---
+source:
+- var
+authors:
+- name: trans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2012'
+  license: BSD-2-Clause
+requirements:
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: qed
+  groups:
+  - test
+  development: true
+- name: ae
+  groups:
+  - test
+  development: true
+dependencies: []
+alternatives: []
+conflicts: []
+repositories:
+- uri: git://github.com/rubyworks/history.git
+  scm: git
+  name: upstream
+resources:
+- uri: http://rubyworks.github.com/history
+  label: Website
+  type: home
+- uri: http://github.com/rubyworks/history
+  label: Source Code
+  type: code
+- uri: http://github.com/rubyworks/history/issues
+  label: Issue Tracker
+  type: bugs
+- uri: http://groups.google.com/groups/rubyworks-mailinglist
+  label: Mailing List
+  type: mail
+- uri: irc://us.chat.freenode.net/rubyworks
+  label: IRC Channel
+  type: chat
+categories: []
+extra: {}
+load_path:
+- lib
+revision: 0
+name: history
+title: History
+created: '2010-02-19'
+organization: Rubyworks
+summary: HISTORY and CHANGELOG parser
+version: 0.2.0
+description: ! 'History is a HISTORY file parser. It can parse common HISTORY file
+  layouts
+
+  and provide the contents in a structured model. This can be useful for
+
+  a number of things, in particular it can be used to generate tag messages
+
+  and add pre-release change lists to release announcements.'
+date: '2012-05-25'

data/lib/history/release.rb

@@ -0,0 +1,91 @@
+class History
+
+  # History release entry.
+  #
+  class Release
+
+    # The full text of the release note.
+    attr :text
+
+    # The header.
+    attr :header
+
+    # The description.
+    attr :notes
+
+    # The list of changes.
+    attr :changes
+
+    # Version number (as a string).
+    attr :version
+
+    # Release date.
+    attr :date
+
+    # Nick name of the release, if any.
+    attr :nickname
+
+    #
+    def initialize(text)
+      @text = text.strip
+      parse
+    end
+
+    # Returns the complete text.
+    def to_s
+      text
+    end
+
+    ;; private
+
+    # Parse the release text into +header+, +notes+
+    # and +changes+ components.
+    def parse
+      lines = text.lines.to_a
+
+      @header = lines.shift.strip
+
+      parse_release_stamp(@header)
+
+      # remove blank lines from top
+      lines.shift until lines.first !~ /^\s+$/
+
+      # find line that looks like the startt of a list of c hanges.
+      idx = nil
+      idx ||= lines.index{ |line| /^changes\:\s*$/i =~ line }
+      idx ||= lines.index{ |line| /^1.\ / =~ line }
+      idx ||= lines.index{ |line| /^\*\ / =~ line }
+
+      if idx.nil?
+        @notes   = lines.join
+        @changes = ''
+      elsif idx > 0
+        @notes   = lines[0...idx].join
+        @changes = lines[idx..-1].join
+      else
+        gap = lines.index{ |line| /^\s*$/ =~ line }
+        @changes = lines[0...gap].join
+        @notes   = lines[gap..-1].join
+      end
+    end
+
+    # Parse out the different components of the header, such
+    # as `version`, release `date` and release `nick name`.
+    def parse_release_stamp(text)
+      # version
+      if md = /\b(\d+\.\d.*?)(\s|$)/.match(text)
+        @version = md[1]
+      end
+      # date
+      if md = /\b(\d+\-\d+\-.*?\d)(\s|\W|$)/.match(text)
+        @date = md[1]
+      end
+      # nickname
+      if md = /\"(.*?)\"/.match(text)
+        @nickname = md[1]
+      end
+    end
+
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: history
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-24 00:00:00.000000000 Z
+date: 2012-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: detroit
-  requirement: &23265980 !ruby/object:Gem::Requirement
+  requirement: &16961460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *23265980
+  version_requirements: *16961460
 - !ruby/object:Gem::Dependency
   name: qed
-  requirement: &23264740 !ruby/object:Gem::Requirement
+  requirement: &16983160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *23264740
+  version_requirements: *16983160
 - !ruby/object:Gem::Dependency
   name: ae
-  requirement: &23263820 !ruby/object:Gem::Requirement
+  requirement: &16979640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,16 +43,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *23263820
-description: ! 'History is a HISTORY and CHANGELOG file parser. It can parse common
-  layouts for these
+  version_requirements: *16979640
+description: ! 'History is a HISTORY file parser. It can parse common HISTORY file
+  layouts
 
-  file types and provide their contents in a structured model. This can be useful
-  for
+  and provide the contents in a structured model. This can be useful for
 
-  a number of things, in particular it can be used to generate tag messages and add
+  a number of things, in particular it can be used to generate tag messages
 
-  pre-release changelogs to relase announcements.'
+  and add pre-release change lists to release announcements.'
 email:
 - transfire@gmail.com
 executables: []
@@ -61,12 +60,21 @@ extra_rdoc_files:
 - LICENSE.txt
 - HISTORY.md
 - README.md
+- DEMO.md
 files:
 - .ruby
+- demo/00_intro.md
+- demo/01_history.md
+- demo/applique/ae.rb
+- demo/applique/fixtures.rb
+- demo/applique/history.rb
+- lib/history/release.rb
 - lib/history.rb
+- lib/history.yml
 - LICENSE.txt
 - HISTORY.md
 - README.md
+- DEMO.md
 homepage: http://rubyworks.github.com/history
 licenses:
 - BSD-2-Clause