Revix: revision history models

Purpose

Revix is a Ruby gem for working with Metanorma document revision history.

It provides a set of models and utilities for parsing, manipulating, and serializing revision history data in YAML and XML formats.

Installation

Add this line to your application’s Gemfile:

gem 'revix'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install revix

Usage

Parsing revision history

From YAML

- edition: 1.0.0
  date:
    - type: published
      value: 2012-04
  contributor:
    - person:
        name:
          abbreviation: JMS
          completename: J. Michael Straczynski
  amend:
    - description: Approved edition of S-102
      location:
        - type: clause
          value: 4.0
        - type: whole

require 'revix'

# Parse from YAML string
yaml_content = File.read('revision_history.yaml')
history = Revix::RevisionHistory.from_yaml(yaml_content)

# Access revision data
history.revisions.each do |revision|
  puts "Edition: #{revision.edition}"
  puts "Date: #{revision.date.first.value} (#{revision.date.first.type})"

  revision.contributor.each do |contributor|
    if contributor.person
      puts "Contributor: #{contributor.person.name.completename} (#{contributor.person.name.abbreviation})"
    elsif contributor.organization
      puts "Contributor: #{contributor.organization.name}"
    end
  end

  revision.amend.each do |amendment|
    puts "Amendment: #{amendment.description}"

    amendment.location&.each do |location|
      if location.value
        puts "  Location: #{location.type}=#{location.value}"
      else
        puts "  Location: #{location.type}"
      end
    end

    amendment.classification&.each do |classification|
      puts "  Classification: #{classification.tag} = #{classification.value}"
    end
  end
end

From XML

<revision-history>
  <revision>
    <date type="published">2012-04</date>
    <edition>1.0.0</edition>
    <contributor>
      <person>
        <name abbreviation="JMS">
          <completename>J. Michael Straczynski</completename>
        </name>
      </person>
    </contributor>
    <amend>
      <amendment>
        <description>Approved edition of S-102</description>
        <location type="clause">4.0</location>
        <location type="whole"/>
      </amendment>
    </amend>
  </revision>
</revision-history>

require 'revix'

# Parse from XML string
xml_content = File.read('revision_history.xml')
history = Revix::RevisionHistory.from_xml(xml_content)

# Access revision data (same as with YAML)

Serializing revision history

To YAML

require 'revix'

# Create a revision history object
history = Revix::RevisionHistory.new(revisions: [
  Revix::Revision.new(
    date: [Revix::DateInfo.new(type: "published", value: "2012-04")],
    edition: "1.0.0",
    contributor: [
      Revix::Contributor.new(
        person: Revix::Person.new(
          name: Revix::Name.new(
            abbreviation: "JMS",
            completename: "J. Michael Straczynski"
          )
        )
      )
    ],
    amend: [
      Revix::Amendment.new(
        description: "Approved edition of S-102",
        location: [
          Revix::Location.new(type: "clause", value: "4.0"),
          Revix::Location.new(type: "whole")
        ]
      )
    ]
  )
])

# Serialize to YAML
yaml_content = history.to_yaml
File.write('revision_history.yaml', yaml_content)

To XML

# Serialize to XML
xml_content = history.to_xml
File.write('revision_history.xml', xml_content)

Data model

The Revix gem provides the following models.

+-------------------+
|  RevisionHistory  |
|                   |
| +revisions        |
+--------+----------+
         |
         | 1..*
+--------v----------+      +------------+
|     Revision      |      |  DateInfo  |
|                   |      |            |
| -edition          |<>--->| -type      |
| -relation_type    |      | -value     |
| +date             |      |            |
| +contributor      |      +------------+
| +amend            |
+--------+----------+
         |
    +----+----+---------------------+
    |         |                     |
+---v---+ +---v----------+  +-------v--------+
|Person | | Organization |  | Amendment      |
|       | |              |  |                |
| +name | | -name        |  | -description   |
|       | | -subdivision |  | -change        |
|       | | -abbreviation|  | +location      |
+---+---+ +--------------+  | +classification|
    |                       +-------+--------+
    |                               |
    |                  +------------+------+
+---v---+              |                   |
| Name  |       +------+-------+   +-------+-------+
|       |       +  Location    |   | Classification|
| -abbr |       |              |   |               |
| -full |       | -type        |   | -tag          |
+-------+       | -value       |   | -value        |
                +--------------+   +---------------+

RevisionHistory

The main container for all revisions.

revisions: A collection of Revision objects

Revision

Represents a single revision entry.

date: A collection of DateInfo objects
edition: The version number as a string
contributor: A collection of Contributor objects
amend: A collection of Amendment objects
relation_type: The relation type (optional)

DateInfo

Represents date information.

type: The type of date (e.g., "published", "updated")
value: The date value as a string

Contributor

Represents a contributor, which can be either a person or an organization.

person: A Person object (optional)
organization: An Organization object (optional)

Person

Represents a person contributor.

name: A Name object

Organization

Represents an organization contributor.

name: The organization name as a string
subdivision: The organization subdivision as a string (optional)
abbreviation: The organization abbreviation as a string (optional)

Name

Represents a person’s name.

abbreviation: The person’s abbreviation or initials
completename: The person’s full name

Amendment

Represents an amendment.

description: The amendment description as a string
location: A collection of Location objects (optional)
classification: A collection of Classification objects (optional)
change: The type of change (default: "modify")

Location

Represents a location affected by an amendment.

type: The location type. Accepts the defined Metanorma location types, including: section, clause, part, paragraph, chapter, page, line, table, annex, figure, example, note, formula, list, time, anchor, whole.
value: The location value (e.g., 4.0, B), can be nil for types like whole.

Classification

Represents a classification tag/value pair.

tag: The classification tag (e.g., "severity", "type")
value: The classification value (e.g., "major", "editorial")

Copyright

This gem is developed, maintained and funded by Ribose Inc.

License

The gem is available as open source under the terms of the 2-Clause BSD License.

revix

Runtime