genericode 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36468da54f60d5e0013f2e4e16941051f0b09288d48f6560ceafa3f7b1599af1
-  data.tar.gz: fceaa075b3b6b994659952046e4ebc92eeada80e67d8a2dcce548460223c8912
+  metadata.gz: 45525e09245553fcda6cb3606ec8f7b17c0fde0daf6507c41e47008d5e8dce43
+  data.tar.gz: 66c0b7b056d47c096d736176d9c575df8fba8c830f539d14e076b43a6f07cda8
 SHA512:
-  metadata.gz: aefac994fc63be20cb0c436b5411efb25585bb6013885b0cbc7641f6f79a11c36c93eaf5acd34debd11dc8b42b4f59970e28a1e63ec014196e8927d777996651
-  data.tar.gz: 6eb782a0098930abbc8ed164b9a9218506783416ad69deeddfb47a97b6279600784d85f50d7e6ebcc78dfff680469f5f94d915de8a6c10d5646d00974202884a
+  metadata.gz: d6dd2ebe439fde9ab7584ef67e149b3d79b026ae980b8beec200c5fd99a45e95c35b70663bfd8d27566095778394ce6a65ad2f4e7ff72b4706b7028c94ba55a5
+  data.tar.gz: 59951937dd0cd26496fe64e13f9ba70c12ed7d2757609ebfa10633e4d21a233fae230fc234b7da559f4bc12e1c121b029bec786af445f74d6fd5a703dcff83b0

data/.rubocop.yml

@@ -1,8 +1,34 @@
+inherit_from: .rubocop_todo.yml
+
 AllCops:
-  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.7
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Metrics/BlockLength:
+  AllowedMethods:
+    - describe
+
+Style/Documentation:
+  Enabled: false
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma

data/.rubocop_todo.yml

@@ -0,0 +1,66 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-01-11 09:46:54 UTC using RuboCop version 1.70.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: TreatCommentsAsGroupSeparators, ConsiderPunctuation, Include.
+# Include: **/*.gemfile, **/Gemfile, **/gems.rb
+Bundler/OrderedGems:
+  Exclude:
+    - 'Gemfile'
+
+# Offense count: 1
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'lib/genericode/code_list.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect, CheckForMethodsWithNoSideEffects.
+Lint/Void:
+  Exclude:
+    - 'lib/genericode/code_list.rb'
+
+# Offense count: 8
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 182
+
+# Offense count: 2
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 34
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 216
+
+# Offense count: 5
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 92
+
+# Offense count: 10
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 86
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 92
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 121

data/README.adoc

@@ -0,0 +1,282 @@
+= Genericode
+
+image:https://img.shields.io/gem/v/genericode.svg["Gem Version", link="https://rubygems.org/gems/genericode"]
+image:https://github.com/lutaml/genericode/workflows/rake/badge.svg["Build Status", link="https://github.com/lutaml/genericode/actions?workflow=rake"]
+image:https://codeclimate.com/github/lutaml/genericode/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/lutaml/genericode"]
+
+== Purpose
+
+This Ruby gem implements the
+http://docs.oasis-open.org/codelist/genericode/doc/oasis-code-list-representation-genericode.html[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:
+
+[source,ruby]
+----
+gem 'genericode'
+----
+
+Then execute:
+
+[source,sh]
+----
+$ bundle install
+----
+
+Or install it directly using:
+
+[source,sh]
+----
+$ 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:
+[source,sh]
+----
+$ genericode convert INPUT_FILE OUTPUT_FILE
+----
+
+Example:
+[source,sh]
+----
+$ 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:
+[source,sh]
+----
+$ genericode validate FILE
+----
+
+Example:
+[source,sh]
+----
+$ 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:
+[source,sh]
+----
+$ genericode list_codes FILE [--format=FORMAT] [--output=FILE]
+----
+
+Example:
+[source,sh]
+----
+$ 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:
+[source,sh]
+----
+$ genericode lookup FILE PATH
+----
+
+Examples:
+[source,sh]
+----
+$ 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
+
+[source,ruby]
+----
+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", ...]
+----
+
+[source,ruby]
+----
+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"]
+----
+
+[source,ruby]
+----
+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
+https://github.com/oasis-tcs/codelist-genericode/tree/genericode-v1.0-os/json-example[(GitHub)].
+
+`spec/fixtures/xml`:: XML examples.
+
+`spec/fixtures/xml/standard/*.gc`:: Genericode XML examples from the OASIS
+genericode standard 1.0
+https://github.com/oasis-tcs/codelist-genericode/tree/genericode-v1.0-os/xml[(GitHub)].
+
+`spec/fixtures/xml/niem/*.gc`:: Genericode XML examples from the
+https://reference.niem.gov/niem/specification/code-lists/1.0beta1/niem-code-lists-1.0beta1-2016-03-15.html[NIEM Code Lists Specification, Version 1.0beta1].
+https://github.com/NIEM/NIEM-Code-Lists-Spec/blob/master/example/make-model/make-model.gc[(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
+https://github.com/oasis-tcs/ubl[OASIS UBL 2.3 repository] (branch `ubl-2.5-csd01`),
+https://github.com/oasis-tcs/ubl/tree/ubl-2.5-csd01/os-UBL-2.3/cl/gc/default[`os-UBL-2.3/cl/gc/default`].
+
+NOTE: The "OASIS genericode standard 1.0" refers to the
+https://docs.oasis-open.org/codelist/genericode/v1.0/os/genericode-v1.0-os.html#S-LONGNAME-COMPLEX-TYPE["OASIS Code List Representation (genericode) Version 1.0"]
+
+== License
+
+Copyright Ribose.
+
+BSD-3 license.

data/exe/genericode

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/genericode"
+require_relative "../lib/genericode/cli"
+
+Genericode::Cli::Commands.start(ARGV)

data/lib/genericode/agency.rb

@@ -1,21 +1,41 @@
 # frozen_string_literal: true
 
-require "shale"
+require "lutaml/model"
 
 require_relative "general_identifier"
 require_relative "long_name"
 require_relative "short_name"
+require_relative "json/short_name_mixin"
+require_relative "utils"
 
 module Genericode
-  class Agency < Shale::Mapper
+  class Agency < Lutaml::Model::Serializable
+    include Json::ShortNameMixin
+
     attribute :short_name, ShortName
     attribute :long_name, LongName, collection: true
     attribute :identifier, GeneralIdentifier, collection: true
 
     json do
-      map "ShortName", to: :short_name
-      map "LongName", to: :long_name
-      map "Identifier", to: :identifier
+      map "ShortName", to: :short_name, with: { from: :short_name_from_json, to: :short_name_to_json }
+      map "LongName", to: :long_name, with: { from: :long_name_from_json, to: :long_name_to_json }
+      map "Identifier", to: :identifier, with: { from: :identifier_from_json, to: :identifier_to_json }
+    end
+
+    def long_name_from_json(model, value)
+      model.long_name = LongName.of_json(Utils.array_wrap(value))
+    end
+
+    def long_name_to_json(model, doc)
+      doc["LongName"] = LongName.as_json(Utils.one_or_all(model.long_name))
+    end
+
+    def identifier_from_json(model, value)
+      model.identifier = GeneralIdentifier.of_json(Utils.array_wrap(value))
+    end
+
+    def identifier_to_json(model, doc)
+      doc["Identifier"] = GeneralIdentifier.as_json(Utils.one_or_all(model.identifier))
     end
 
     xml do

data/lib/genericode/annotation.rb

@@ -1,18 +1,24 @@
 # frozen_string_literal: true
 
-require "shale"
+require "lutaml/model"
 
 require_relative "any_other_content"
 require_relative "any_other_language_content"
 
 module Genericode
-  class Annotation < Shale::Mapper
+  class Annotation < Lutaml::Model::Serializable
     attribute :description, AnyOtherLanguageContent, collection: true
     attribute :app_info, AnyOtherContent
 
     json do
       map "Description", to: :description
-      map "AppInfo", to: :app_info
+      map "AppInfo", to: :app_info, render_nil: true
+    end
+
+    def self.of_json(hash, **)
+      hash = { "AppInfo" => hash } if hash.any?
+
+      super
     end
 
     xml do
@@ -20,7 +26,7 @@ module Genericode
       namespace "http://docs.oasis-open.org/codelist/ns/genericode/1.0/", "gc"
 
       map_element "Description", to: :description, prefix: nil, namespace: nil
-      map_element "AppInfo", to: :app_info, prefix: nil, namespace: nil
+      map_element "AppInfo", to: :app_info, prefix: nil, namespace: nil, render_nil: true
     end
   end
 end

data/lib/genericode/any_other_content.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require "shale"
+require "lutaml/model"
 
 module Genericode
-  class AnyOtherContent < Shale::Mapper
+  class AnyOtherContent < Lutaml::Model::Serializable
     xml do
       root "AnyOtherContent"
       namespace "http://docs.oasis-open.org/codelist/ns/genericode/1.0/", "gc"

data/lib/genericode/any_other_language_content.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require "shale"
+require "lutaml/model"
 
 module Genericode
-  class AnyOtherLanguageContent < Shale::Mapper
-    attribute :lang, Shale::Type::String
+  class AnyOtherLanguageContent < Lutaml::Model::Serializable
+    attribute :lang, :string
 
     json do
       map "lang", to: :lang

data/lib/genericode/canonical_uri.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require "uri"
+
+module Genericode
+  # Rule 4: Must be an absolute URI, must not be relative
+  class CanonicalUri < Lutaml::Model::Serializable
+    attribute :content, :string
+
+    xml do
+      root "CanonicalUri"
+      map_content to: :content
+    end
+
+    def valid?
+      valid_uri?(content) && absolute_uri?(content)
+    end
+
+    private
+
+    def valid_uri?(uri)
+      uri =~ URI::DEFAULT_PARSER.make_regexp
+    end
+
+    def absolute_uri?(uri)
+      URI.parse(uri).absolute?
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+end

data/lib/genericode/cli/code_lister.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../code_list"
+require "tabulo"
+require "csv"
+
+module Genericode
+  module Cli
+    class CodeLister
+      class << self
+        def list_codes(file_path, format: :tsv)
+          code_list = CodeList.from_file(file_path)
+
+          # Validate data types
+          code_list.validate_verbose.each do |error|
+            raise Error, "#{error[:code]}: #{error[:message]}" if error[:code] == "INVALID_DATA_TYPE"
+
+            # Ensure valid ColumnRefs
+            raise Error, "#{error[:code]}: #{error[:message]}" if error[:code] == "INVALID_COLUMN_REF"
+          end
+
+          case format
+          when :tsv
+            list_tsv(code_list)
+          when :table
+            list_table(code_list)
+          else
+            raise Error, "Unknown format: #{format}"
+          end
+        end
+
+        private
+
+        def list_tsv(code_list)
+          columns = code_list.column_set.column
+          rows = code_list.simple_code_list.row
+
+          CSV.generate(col_sep: "\t") do |csv|
+            csv << columns.map { |col| col.short_name.content }
+            rows.each do |row|
+              csv << columns.map do |col|
+                value = row.value.find { |v| v.column_ref == col.id }
+                value&.simple_value&.content || ""
+              end
+            end
+          end.strip.encode("UTF-8")
+        end
+
+        def list_table(code_list)
+          columns = code_list.column_set.column
+          rows = code_list.simple_code_list.row
+
+          table = Tabulo::Table.new(rows) do |t|
+            columns.each do |column|
+              t.add_column(column.short_name.content) do |row|
+                value = row.value.find { |v| v.column_ref == column.id }
+                value&.simple_value&.content || ""
+              end
+            end
+          end
+
+          table.to_s
+        end
+      end
+    end
+  end
+end

data/lib/genericode/cli/code_lookup.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "../code_list"
+
+module Genericode
+  module Cli
+    class CodeLookup
+      def self.lookup(file_path, path)
+        code_list = CodeList.from_file(file_path)
+        result = code_list.lookup(path)
+
+        if result.is_a?(Hash)
+          result.map { |k, v| "#{k}: #{v}" }.join("\n")
+        else
+          result.to_s
+        end
+      rescue Error => e
+        raise Error, e.message
+      end
+    end
+  end
+end