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 installOr install it directly using:
$ gem install genericodeAfter 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_FILEExample:
$ genericode convert input.gc output.gcjThis 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 FILEExample:
$ genericode validate codelist.gcUse 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.tsvThis 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 PATHExamples:
$ 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)
NoteA 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.