Genericode

Purpose

This Ruby gem implements the OASIS Genericode 1.0 standard.

It can be used to parse and generate code lists in the Genericode format, including:

• Genericode XML: *.gc

• Genericode JSON: *.gcj

Installation

To install the genericode gem, use one of the following methods.

Add this line to your application’s Gemfile:

gem 'genericode'

Then execute:

$ bundle install

Or install it directly using:

$ gem install genericode

After installation, you can start using the genericode gem in your Ruby projects or via the command-line interface.

Genericode path syntax

The "Genericode path" is a simplified syntax used to navigate through and extract data from Genericode structures. It’s designed to be intuitive and flexible.

Basic syntax

The basic syntax uses a combination of column names and values to uniquely identify a row and retrieve associated data:

column_name:value

This will return all data associated with the row where column_name has the specified value.

Multiple column lookup

To narrow down the search using multiple columns:

column1:value1,column2:value2

This will return data for the row where column1 has value1 AND column2 has value2.

Specific column retrieval

To retrieve the value of a specific column for a given row:

column1:value1>target_column

This will return the value of target_column for the row where column1 has value1.

CLI commands

The Genericode gem provides a command-line interface (CLI) with the following commands:

Convert

Converts between Genericode XML and JSON formats.

Usage:

$ genericode convert INPUT_FILE OUTPUT_FILE

Example:

$ genericode convert input.gc output.gcj

This command is useful when you need to convert between XML and JSON representations of your code lists.

Validate

Validates a Genericode file.

Usage:

$ genericode validate FILE

Example:

$ genericode validate codelist.gc

Use this command to check if your Genericode file is valid according to the specification.

List codes

Lists all codes and their associated data in a Genericode file.

Usage:

$ genericode list_codes FILE [--format=FORMAT] [--output=FILE]

Example:

$ genericode list_codes country_codes.gc
$ genericode list_codes country_codes.gc --format=table
$ genericode list_codes country_codes.gc --format=tsv --output=codes.tsv

This command displays all the data in the Genericode file. By default, it outputs in TSV (Tab-Separated Values) format. You can specify the --format option to choose between tsv (default) and table formats. Use the --output option to save the result to a file.

Lookup

Looks up specific data in a Genericode file using the simplified Genericode path syntax.

Usage:

$ genericode lookup FILE PATH

Examples:

$ genericode lookup country_codes.gc "code:US"
$ genericode lookup country_codes.gc "code:FR>name"
$ genericode lookup currency_codes.gc "alpha_code:USD,numeric_code:840>name"

Use this command to extract specific information from a Genericode file using the simplified path syntax. The syntax allows you to:

• Retrieve all data for a specific code: column:value

• Get a specific column value for a given code: column:value>target_column

• Use multiple columns to narrow down the search: column1:value1,column2:value2

To use these CLI commands, ensure that the Genericode gem is installed and available in your system’s PATH.

Ruby API

require 'genericode'

# Load a Genericode file
gc = Genericode::CodeList.from_file("country_codes.gc")

# Lookup examples
gc.lookup("code:US")
# => {"code"=>"US", "name"=>"United States", ...}

gc.lookup("code:FR>name")
# => "France"

gc.lookup("alpha_code:USD,numeric_code:840>name")
# => "US Dollar"

# Other API usage remains the same
gc.identification.short_name.content
# => "CountryCodes"

gc.simple_code_list.row.map(&:value).flatten.map(&:simple_value).map(&:content)
# => ["US", "United States", "FR", "France", ...]

require 'genericode'

# XML element root of `<<gc:CodeList>`
gc = Genericode::CodeList.from_xml(File.read("spec/fixtures/xml/CaseTypeCode.gc"))
# Or:
# JSON element root of `<<gc:CodeList>`
# gc = Genericode.from_json(File.read("spec/fixtures/json/CaseTypeCode.gcj"))

gc.identification.short_name.content
# => "CaseTypeCode"
gc.identification.short_name.version
# => "5.0"

gc.simple_code_list.row.map(&:value).flatten.map(&:simple_value).map(&:content)
# => ["appellate", "bankruptcy", "citation", "civil", "criminal", "domestic", "juvenile"]

require 'genericode'

# XML element root of `<<gc:CodeList>`
gc = Genericode::CodeList.from_json(File.read("spec/fixtures/xml/CaseTypeCode.gcj"))

gc.identification.short_name.content
# => "CaseTypeCode"
gc.identification.short_name.version
# => "5.0"

gc.simple_code_list.row.map(&:value).flatten.map(&:simple_value).map(&:content)
# => ["appellate", "bankruptcy", "citation", "civil", "criminal", "domestic", "juvenile"]

Tests

The spec/fixtures folder tests the library against known examples of Genericode.

Including:

spec/fixtures/json

JSON examples.

spec/fixtures/json/standard/*.gcj

Genericode JSON examples from the OASIS genericode standard 1.0 (GitHub).

spec/fixtures/xml

XML examples.

spec/fixtures/xml/standard/*.gc

Genericode XML examples from the OASIS genericode standard 1.0 (GitHub).

spec/fixtures/xml/niem/*.gc

Genericode XML examples from the NIEM Code Lists Specification, Version 1.0beta1. (GitHub)

Note	A modification was made to remove unrelated namespaces to allow tests to pass.

spec/fixtures/xml/ubl/*.gc

Genericode XML examples from the OASIS UBL 2.3 repository (branch ubl-2.5-csd01), os-UBL-2.3/cl/gc/default.

Note	The "OASIS genericode standard 1.0" refers to the "OASIS Code List Representation (genericode) Version 1.0"

License

Copyright Ribose.

BSD-3 license.