Skip to content

Accessor and generator of OASIS Genericode 1.0

Notifications You must be signed in to change notification settings

lutaml/genericode

Repository files navigation

Genericode

Gem Version Build Status Code Climate

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.

About

Accessor and generator of OASIS Genericode 1.0

Resources

Code of conduct

Stars

Watchers

Forks

Packages

No packages published