pubid 0.1.1 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4593d133b8317644f3550f821ed29640ab1fc5ec241c0c1b8a5db119ea1b9c6
-  data.tar.gz: b1ce4684350169c833c8825aa84a3966b51c90585efe7636678402f0d52580af
+  metadata.gz: fd93e44539bfdf58b577341e38c5a802723b0058e55feca77941ac8c3ff7eb63
+  data.tar.gz: 961315e34b66f01bace40aa7b154c391a2d880d98a9ba563f3aeee93d1fc8d23
 SHA512:
-  metadata.gz: df2d32af3143b32af3d6d5f992ed0c01ca3e3ecc60ab0e5fa55884f81f0dff678f42a0f6fa1ffe0cf8b3dbe755748c7ca32f72bdd4ba1c43c19b8d26b130fa9a
-  data.tar.gz: 80ed5a22574564137f015f06479f4d7b7c345b571b3656bf8d51adc797858f89963bda4162248e4eb6ec51dcffaa98bc4356f0e7bbbbd383790d3b7724c5d04d
+  metadata.gz: 3ab7e206004ae2113c0c4153644ba772e58b213f7417fb79f32abfedd155348dfbc988d16a65cca8ffecc45f80da8b7b517fcc25e29415e4f651226875e4b58e
+  data.tar.gz: d45a4e3994cd2b2d84895b5bcddb9fed669eda9e4463243c164a86cb20077ce9e0ce846f6dd9751eacb0cc16fdb8240c63bee7a1eb8dbcc776b2a0b6918b7bbf

data/README.adoc

@@ -1,8 +1,82 @@
-= PubID
+= Publication identifiers library
 
 image:https://badge.fury.io/rb/pubid.svg["Gem Version", link="https://badge.fury.io/rb/pubid"]
 
-== Purpose
+Pubid is a comprehensive framework for building and working with publication identifiers. It provides a robust API for creating, modifying, parsing, exporting, and verifying document identifiers, which are crucial for various document management systems and standards compliance
 
-This gem include all pubid-* gems for compatibility testing.
+This gem includes all pubid-* gems for compatibility testing and allows parsing all identifiers from one gem.
 
+== Current use cases
+The current use cases, as listed below, are what we have needed until now and have discovered through use of pubid to pubid-*,  metanorma-*, and relaton-* projects. Work on pubid is not complete and will be expanding during the ongoing integration process.
+
+- building identifiers from scratch
+- modifiying identifiers (e.g. basing an amendment identifier on a base identifier)
+- parsing string identifiers
+- exporting/importing to different formats or styles (hash, yaml, URN, etc.)
+- verification of compliance for the identifier's representation standard (NIST PubID 1.0 for NIST, RFC 5141 for ISO URN), or using commonly found patterns
+- verifying that a provided identifier is correct
+- comparing two provided identifiers (with the option to exclude specified attributes)
+- converting legacy identifiers to updated format
+
+== Purpose and Usage Guidelines
+
+The pubid library is intended to be used wherever operations on publication identifiers are required. It acts as an intermediary between users and publication identifiers, streamlining the processes of creation, modification, comparison, and attribute access. By centralizing these operations in pubid-core, we ensure that any updates to identifier standards are seamlessly integrated across all related projects in an ecosystem.
+
+It is crucial to use the pubid library for all operations with identifiers to ensure that updates in identifier standards are consistently reflected in these operations, and are driven by a data representation of the identifier, rather than the identifier string. For example, if an identifier like `ISO/R 657/IV` is updated to `ISO/R 657-4:1969` by a standards body, and pubid acts on that update, the library will automatically recognize this change. Hence, comparing:
+[source,ruby]
+----
+Pubid::Registry.parse("ISO/R 657/IV") == Pubid::Registry.parse("ISO/R 657-4:1969")
+=> true
+----
+or accessing the year:
+[source,ruby]
+----
+Pubid::Registry.parse("ISO/R 657/IV").year
+=> 1969
+----
+will yield the updated results.
+
+Moreover, changes in how identifiers are compared may cause some identifiers to become equal or unequal based on the latest updates. Thus, to reflect these changes accurately, the pubid library should be used for all publication identifier operations.
+
+=== Information model
+
+Technical documents in general, and standards specifically, are routinely identified and cited by document identifier, rather than by author, title, and/or publication date, as is routine practice for other bibliographic types. These document identifiers are usually somewhat arbitrary, containing a number identifying the current document as one in a sequence of documents.
+
+However, technical document identifiers typically also contain representation of at least some of the bibliographic information about the document. This is why bibliographic citation of technical document (particularly in other technical documents) is often restricted to just the document identifier and the title: the identifier is felt in such communities to convey all the relevant bibliographic information needed to make sense of the standard. (The expectations on what information is needed is different from other bibliographic types within their communities: authorship for example is typically corporate, dates are assumed by default to be the latest availabe edition, and the place of publication and publisher are identiified with the organisation publishing the document.)
+
+Pubid uses semantic representation of the bibliographic information used to generate an identifier for an organisation. That is why the format of the identifier can be updated without changing the underlying semantics it encodes. Each organisation that Pubid supports has its own semantics, but there are recurring semantic fields that Pubid uses, which drive what the identifiers look like, and which correspond to bibliographic information. (The Relaton bibliographic model equivalent is linked after each definition.)
+
+* The `publisher` is the organisation responsible for the document. Standards-defining organisations, in particular, are identified by established acronyms, such as _ISO_, _IEC_, _NIST_, which are usually prefixed  to the document identifier; that prefix takes the place of a publisher field. The choice of publisher determines the flavour of Pubid that is used. (Relaton: https://www.relaton.org/model/creator/[Creator, type: Publisher])
+* Technical documents are often published by multiple organisations. Such co-publication is indicated through using the acronyms of all organisations involved in the prefix; publishers after the first are indicated as `copublisher`. For example, the prefix _ISO/IEC/IEEE_ indicates that the document is copublished by all three organisations; ISO will be treated as the primary publisher by Pubid. (Relaton: https://www.relaton.org/model/creator/[Creator, type: Publisher])
+* Technical documents are almost always numbered in a sequence; that `number` is used along with the publisher to identify the document uniquely. (Relaton: https://www.relaton.org/model/series/[Series number])
+* Technical documents may consist of different parts, which can be referenced individually. The `part` number for the document is used in addition to the number in that case. (Relaton: https://www.relaton.org/model/citation/[Citation, type: Part])
+* In special circumstances, multiple subsequent versions of a document can appear with the same number; this applies for example to multiple drafts. These subsequent versions can be indicated as `iteration`. (Relaton: https://www.relaton.org/model/edition/[Edition: Version])
+* Often there is different numbering used for different types of technical document; for example, technical reports, technical notes, and standards have different number sequences in ISO. For that reason, the document `type` may be required in addition to the number. For inclusion in an identifier the organisation will typically have a standardised abbreviation for each of the document types. (Relaton: https://www.relaton.org/model/series/[Series], though Relaton for standards organisations treats these for convenience as subtypes of document, the document https://www.relaton.org/model/bibtype/[type] being `standard`)
+* In some cases, different numbering is used not for different types of document, but different defined `series`. If that is the case, the organisation will typically have a standardised abbreviation for the series as well. (Relaton: https://www.relaton.org/model/series/[Series])
+* Some organisations publish standards in multiple languages. In that case, the document `language` can also be provided, to indicate a particular language version.
+* Technical documents are often cited undated; in that case, the latest version of the document is usually assumed. If a specific edition of a document needs to be specified in the edition, this can be done by supplying an `edition` number, the `year` of publication, or both, depending on the organisation. (Relaton: https://www.relaton.org/model/edition/[Edition], https://www.relaton.org/model/production/#date[Date])
+* Unlike other documents, technical documents are often circulated and cited in draft version before they are officially published. If this is routinely done, the organisation may provide for means to specify that a document is a `draft`, or the `stage` or `status` which the document has reached in the authoring process. If stages are used in citing documents, the organisation will typically have standard abbreviations for those stages, which will be used in the identifier. (Relaton: https://www.relaton.org/model/edition/[Edition])
+* Just as documents can be bibliographically related to other documents, document identifiers can be based on other document identifiers. This is done in Pubid by specifying two Pubid identifiers, with the first treated as an attribute of the second. The first common case of derived identifiers is when one document is a supplement of another (e.g. an appendix, a corrigendum); this is encoded in Pubid by specifying a `base` Pubid identifier, as an attribute of the derived document, with its own distinct `number`, `type` (e.g. _Appendix_), and `year`. The second case is when a document published by one organisation is `adopted` for use by another organisation: this often is indicated in document identifiers simply by prefixing the adopting organisation's acronym to the original identifier (e.g. _BS ISO 639_). (Relaton: https://www.relaton.org/model/relations/#derived-relations[Relations: `updates`, `adoptedFrom`])
+
+=== Usage
+
+`Pubid::Registry#parse` resolves the pubid class related to the identifier (`Pubid::Iso::Identifier` for "ISO" identifiers) and returns an object with the parsed identifier
+
+[source,ruby]
+----
+require "pubid"
+
+pubid = Pubid::Registry.parse("ISO/IEC 13213")
+pubid.class
+=> Pubid::Iso::Identifier::Base
+pubid.publisher
+=> "ISO"
+pubid.copublisher
+=> "IEC"
+pubid.number
+=> 13213
+pubid.to_s
+=> "ISO/IEC 13213"
+----
+
+You can find usage examples in the https://github.com/metanorma/pubid-core[pubid-core] repository. For more specific usage guides, refer to repositories related to specific identifier providers, such as https://github.com/metanorma/pubid-iso[pubid-iso] for ISO identifiers and https://github.com/metanorma/pubid-ccsds[pubid-ccsds] for CCSDS identifier)

data/lib/pubid/registry.rb

@@ -0,0 +1,30 @@
+module Pubid
+  class Registry
+    class << self
+      def parse(*args)
+        modules = [Pubid::Iso,
+                   Pubid::Ieee,
+                   Pubid::Nist,
+                   Pubid::Iec,
+                   Pubid::Cen,
+                   Pubid::Bsi,
+                   Pubid::Ccsds,
+                   Pubid::Itu,
+                   Pubid::Jis]
+        modules.each do |mod|
+          module_identifier = Kernel.const_get("#{mod}::Identifier")
+          return module_identifier.parse(*args) if module_identifier.parseable?(*args)
+        end
+
+        # Go through each module to try to parse unknown prefix
+        modules.each do |mod|
+          return Kernel.const_get("#{mod}::Identifier").parse(*args)
+        rescue Pubid::Core::Errors::ParseError
+          next
+        end
+
+        raise Pubid::Core::Errors::ParseError, "cannot find module to parse #{args}"
+      end
+    end
+  end
+end

data/lib/pubid/version.rb

@@ -1,3 +1,3 @@
 module Pubid
-  VERSION = "0.1.1".freeze
+  VERSION = "1.15.0".freeze
 end

data/lib/pubid.rb

@@ -0,0 +1,15 @@
+module Pubid
+end
+
+require_relative "pubid/registry"
+
+require "pubid-core"
+require "pubid-iso"
+require "pubid-ieee"
+require "pubid-nist"
+require "pubid-iec"
+require "pubid-cen"
+require "pubid-bsi"
+require "pubid-ccsds"
+require "pubid-itu"
+require "pubid-jis"

metadata

@@ -1,183 +1,183 @@
 --- !ruby/object:Gem::Specification
 name: pubid
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.15.0
 platform: ruby
 authors:
 - Ribose Inc.
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-01 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: pubid-bsi
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
+        version: 1.15.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: pubid-ccsds
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
+        version: 1.15.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-core
+  name: pubid-cen
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 1.12.2
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 1.12.2
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-nist
+  name: pubid-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-iso
+  name: pubid-etsi
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-ieee
+  name: pubid-iec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-cen
+  name: pubid-ieee
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.3
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.3
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-iec
+  name: pubid-iso
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-ccsds
+  name: pubid-itu
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-itu
+  name: pubid-jis
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-jis
+  name: pubid-nist
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
-  name: pubid-bsi
+  name: pubid-plateau
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 1.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 1.15.0
 description: Gem including all pubid-* gems.
 email:
 - open.source@ribose.com
@@ -189,12 +189,14 @@ extra_rdoc_files:
 files:
 - LICENSE.txt
 - README.adoc
+- lib/pubid.rb
+- lib/pubid/registry.rb
 - lib/pubid/version.rb
 homepage: https://github.com/metanorma/pubid
 licenses:
 - BSD-2-Clause
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -209,8 +211,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Gem including all pubid-* gems.
 test_files: []