pubid-iso 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c1a3c2eac1820acf806b7b6bc9623b1d485049d96423409b5c2d78d41159d1f
-  data.tar.gz: 39479f01a5fc68ffdf0eb1f5c4039f75fa7ab0e695647973e604ae8773f5361a
+  metadata.gz: 38d4eeb603e945da7dc88276eeec404e80e210dbb7256d0a1c6dbf0f5afe128e
+  data.tar.gz: d3be687ed15dad803823d873a9fb0189a96c97c45870c69a7a4887f165c60075
 SHA512:
-  metadata.gz: d9f2feda42850c68a4bd1782fa7130ac0e2bfddc15956dd07f85208b6ba3dcd2bc8d48fac6a81b01d2393a5a188b041faf88f8607be84d4dc50524561271e54c
-  data.tar.gz: 783336d94b8b9ec835850e8a4d9b25fefd19996f740982eebca19a70954f8672e395b0ba8080efcb585e770cef46e8b795ae9a1363e4733c663e024eb950926f
+  metadata.gz: f99b0267a9322ceb93893b931a7ead3ac6e603cf95b8a75a75a192a8db6de3bab0c75fff137e7294b566a2d10960e8861dcddf9663d7b6a7473d0544f0e15683
+  data.tar.gz: 2067033963eeac42aac98bf5178f0cf19fefe21f5eb334e53e1e3fe41c6665b64b6e580c1f126d4f8936c6008e47c4d12b49cc793e5f305a8732525ade50604b

data/README.adoc

@@ -12,108 +12,140 @@ identifiers.
 . generate language specific PubID
 . generate dated vs undated PubIDs
 
-=== Usage samples
+== Usage
+
+=== Identifier creation
+
+Basic usage of the pubid-iso gem starts with the `Identifier#create` method.
 
 [source,ruby]
 ----
 require "pubid-iso"
 
-pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123)
+pubid = Pubid::Iso::Identifier.create(publisher: "ISO", number: 123)
 pubid.to_s
 
 => "ISO 1234"
 ----
 
-==== With coopublisher
+
+=== With co-publisher
 
 [source,ruby]
 ----
-pubid = Pubid::Iso::Identifier.new(publisher: "ISO", copublisher: "IEC", number: 123)
+pubid = Pubid::Iso::Identifier.create(publisher: "ISO", copublisher: "IEC", number: 123)
 pubid.to_s
 
 => "ISO/IEC 1234"
 ----
 
-==== With document type
+=== With document type
 
 [source,ruby]
 ----
-pubid = Pubid::Iso::Identifier.new(publisher: "ISO", type: "TR", number: 123)
+pubid = Pubid::Iso::Identifier.create(publisher: "ISO", type: "TR", number: 123)
 pubid.to_s
 
 => "ISO/TR 1234"
 ----
 
-==== With stage
+=== With stage
 
 [source,ruby]
 ----
-pubid = Pubid::Iso::Identifier.new(publisher: "ISO", stage: :WD, number: 123)
+pubid = Pubid::Iso::Identifier.create(publisher: "ISO", stage: :WD, number: 123)
 pubid.to_s
 
 => "ISO/WD 1234"
 ----
 
-==== With part number
+=== With part number
 
 [source,ruby]
 ----
-pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1)
+pubid = Pubid::Iso::Identifier.create(publisher: "ISO", number: 123, part: 1)
 pubid.to_s
 
 => "ISO 1234-1"
 ----
 
-==== Iteration
+=== Iteration
+
+An iteration is a version within a stage. A stage must be provided to set
+an iteration.
+
+If an iteration exists but a stage is not set, an error will be raised.
 
 [source,ruby]
 ----
-pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1, stage: :DIS, iteration: 1)
+pubid = Pubid::Iso::Identifier.create(publisher: "ISO", number: 123, part: 1, stage: "DIS", iteration: 1)
 pubid.to_s
 
 => "ISO/DIS 1234-1.1"
 ----
-To apply iteration to document stage should be provided as well.
-Without stage error will be raised.
 
-==== Amendment and Corrigendum
+
+=== Supplement identifiers
+
+A supplement identifier represents a supplement on top of a base document.
+
+A supplement can be of the following types:
+
+* Amendment `:amd`
+* Addendum `:add` (superseded by Amendment)
+* Technical Corrigendum `:cor`
+* Supplement `:supp`
+
+The general construction of a supplement identifier requires a base identifier.
+
+NOTE: See documentation on
+https://rubydoc.info/gems/pubid-iso/Pubid%2FIso%2FSupplement:initialize[PubId::Iso::Supplement#initialize]
+and
+https://rubydoc.info/gems/pubid-core/Pubid%2FCore%2FSupplement:initialize[Pubid::Core::Supplement#initialize]
+to see all available options.
+
+=== Amendment
+
 [source,ruby]
 ----
-> pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1, year: 2019, amendments: [{ number: "1", year: "2021", stage: :WD }])
+> base = Pubid::Iso::Identifier.create(publisher: "ISO", number: 123, part: 1, year: 2019)
+> pubid = Pubid::Iso::Identifier.create(type: :amd, number: 1, year: "2021", stage: "WD", base: base)
 > pubid.to_s
 => "ISO 1234-1:2019/WD Amd 1:2021"
+----
+
+=== Corrigendum
 
-> pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1, year: 2019, corrigendums: [{ number: "1", year: "2021", stage: :WD }])
+[source,ruby]
+----
+> base = Pubid::Iso::Identifier.create(publisher: "ISO", number: 123, part: 1, year: 2019)
+> pubid = Pubid::Iso::Identifier.create(type: :cor, number: "1", year: "2021", stage: :WD, base: base)
 > pubid.to_s
 => "ISO 1234-1:2019/WD Cor 1:2021"
 ----
-See documentation on https://rubydoc.info/gems/pubid-iso/Pubid%2FIso%2FSupplement:initialize[PubId::Iso::Supplement#initialize] and https://rubydoc.info/gems/pubid-core/Pubid%2FCore%2FSupplement:initialize[Pubid::Core::Supplement#initialize] to see all available options.
 
-==== Using format options
+
+=== Using format options
+
 [source,ruby]
 ----
-> pubid = Pubid::Iso::Identifier.new(
+> base = Pubid::Iso::Identifier.create(
   number: "8601",
   part: "1",
   year: 2019,
   edition: 1,
-  amendment: {number: "1", year: "2021", stage: "DIS"}
+  language: "en"
 )
+> pubid = Pubid::Iso::Identifier.create(type: :amd, number: "1", year: "2021", stage: "DAM", base: base)
 > pubid.to_s(:ref_num_short)
 => "ISO 8601-1:2019/DAM 1:2021(E)"
-> pubid.to_s(:ref_num_long)
-=> "ISO 8601-1:2019/DAmd 1:2021(en)"
 > pubid.to_s(:ref_dated)
 => "ISO 8601-1:2019/DAM 1:2021"
-> pubid.to_s(:ref_dated_long)
-=> "ISO 8601-1:2019/DAmd 1:2021"
 > pubid.to_s(:ref_undated)
 => "ISO 8601-1:2019/DAM 1"
-> pubid.to_s(:ref_undated_long)
-=> "ISO 8601-1:2019/DAmd 1"
 ----
 
-==== Using language specific rendering
+=== Using language specific rendering
 [source,ruby]
 ----
 > pubid = Pubid::Iso::Identifier.parse("ISO/FDIS 26000:2010(ru)")
@@ -124,28 +156,30 @@ See documentation on https://rubydoc.info/gems/pubid-iso/Pubid%2FIso%2FSupplemen
 => "Guide ISO/CEI 71:2001(fr)"
 ----
 
-==== Rendering URN identifier
+=== Rendering URN identifier
+
 [source,ruby]
 ----
-> pubid = Pubid::Iso::Identifier.new(
+> base = Pubid::Iso::Identifier.create(
   number: "8601",
   part: "1",
   year: 2019,
   edition: 1,
-  amendments: {number: "1", year: "2021", stage: "DIS"}
 )
+> pubid = Pubid::Iso::Identifier.create(type: :amd, number: "1", year: "2021", stage: "DAM", base: base)
 > pubid.urn
-=> "urn:iso:std:iso:8601:-1:ed-1:amd:2021:v1"
+=> "urn:iso:std:iso:8601:-1:ed-1:stage-draft:amd:2021:v1"
 ----
 
-==== Typed stage abbreviation
+=== Typed stage abbreviation
+
 [source,ruby]
 ----
 > pubid = Pubid::Iso::Identifier.parse("ISO/FDIS 26000:2010")
 > pubid.typed_stage_abbrev
 => "FDIS"
 > pubid.typed_stage_name
-=> "Final Draft"
+=> "Final Draft International Standard"
 
 > pubid = Pubid::Iso::Identifier.parse("ISO/FDTR 26000:2010")
 > pubid.typed_stage_abbrev
@@ -160,13 +194,58 @@ See documentation on https://rubydoc.info/gems/pubid-iso/Pubid%2FIso%2FSupplemen
 => "Working Draft Technical Report"
 ----
 
-See documentation (https://www.rubydoc.info/gems/pubid-iso/Pubid/Iso/Identifier#initialize-instance_method[Pubid::Iso::Identifier] and https://www.rubydoc.info/gems/pubid-core/Pubid/Core/Identifier#initialize-instance_method[Pubid::Core::Identifier]) for all available attributes and options.
+=== Identifier's class and type
+
+`Identifier#parse` resolves a parsed identifier to the correct class and type.
+
+[source,ruby]
+----
+Pubid::Iso::Identifier.parse("ISO/TC 184/SC 4 N1000").class
+# => Pubid::Iso::Identifier::TechnicalCommittee
+Pubid::Iso::Identifier.parse("ISO/TC 184/SC 4 N1000").type
+# => {:key=>:tc, :title=>"Technical Committee"}
+Pubid::Iso::Identifier.parse("ISO 10001").class
+# => Pubid::Iso::Identifier::InternationalStandard
+Pubid::Iso::Identifier.parse("ISO 10001").type
+# => {:key=>:is, :title=>"International Standard"}
+----
+
+
+
+=== Root identifier
+
+`Identifier#root` points to the root identifier.
+
+The root identifier is defined as:
+
+* for supplement identifiers, the root identifier is the base identifier;
+
+* for other identifiers, the root identifier is the identifier itself.
+
+[source,ruby]
+----
+> pubid = Pubid::Iso::Identifier.parse("ISO/WD TR 26000:2010")
+> pubid.root.to_s
+=> "ISO/WD TR 26000:2010"
+> pubid = Pubid::Iso::Identifier.parse("ISO 10231:2003/Amd 1:2015")
+> pubid.root.to_s
+=> "ISO 10231:2003"
+> pubid = Pubid::Iso::Identifier.parse("ISO/IEC 13818-1:2015/Amd 3:2016/Cor 1:2017")
+> pubid.root.to_s
+=> "ISO/IEC 13818-1:2015"
+----
+
+See documentation
+(https://www.rubydoc.info/gems/pubid-iso/Pubid/Iso/Identifier#initialize-instance_method[Pubid::Iso::Identifier]
+and
+https://www.rubydoc.info/gems/pubid-core/Pubid/Core/Identifier#initialize-instance_method[Pubid::Core::Identifier])
+for all available attributes and options.
 
 == Elements of the PubID
 
 === Document identifier
 
-==== General
+=== General
 
 The ISO document identifier is assembled out of these metadata elements:
 
@@ -178,7 +257,7 @@ document type:: type of ISO deliverable
 copyright year:: year of publication of document
 language:: language of document
 
-==== Publisher
+=== Publisher
 
 This is the abbreviation of the publishing organization, typically `ISO`.
 
@@ -194,7 +273,7 @@ An International Workshop Agreement document has publisher abbreviation of
 ====
 
 
-==== Document type and stage
+=== Document type and stage
 
 ISO document stages in document identifiers are mapped as follows.
 
@@ -281,7 +360,7 @@ Once the document is published (stage 60 substage 60), no status abbreviation is
 given.
 
 
-==== Full PubID patterns
+=== Full PubID patterns
 
 The patterns are as follows:
 

data/lib/pubid/iso/errors.rb

@@ -2,9 +2,6 @@ module Pubid::Iso
   module Errors
     class ParseError < StandardError; end
     class PublishedIterationError < StandardError; end
-    class HarmonizedStageCodeInvalidError < StandardError; end
-    class HarmonizedStageRenderingError < StandardError; end
-    class StageInvalidError < StandardError; end
     class IsStageIterationError < StandardError; end
     class IterationWithoutStageError < StandardError; end
     class WrongFormat < StandardError; end

data/lib/pubid/iso/harmonized_stage_code.rb

@@ -1,149 +1,5 @@
 module Pubid::Iso
-  class HarmonizedStageCode
-    include Comparable
-    # attr_accessor :stage, :substage
-    attr_accessor :stages
+  class HarmonizedStageCode < Pubid::Core::HarmonizedStageCode
 
-    DESCRIPTIONS = {
-      "00.00" => "Proposal for new project received",
-      "00.20" => "Proposal for new project under review",
-      "00.60" => "Close of review",
-      "00.98" => "Proposal for new project abandoned",
-      "00.99" => "Approval to ballot proposal for new project",
-      "10.00" => "Proposal for new project registered",
-      "10.20" => "New project ballot initiated",
-      "10.60" => "Close of voting",
-      "10.92" => "Proposal returned to submitter for further definition",
-      "10.98" => "New project rejected",
-      "10.99" => "New project approved",
-      "20.00" => "New project registered in TC/SC work programme",
-      "20.20" => "Working draft (WD) study initiated",
-      "20.60" => "Close of comment period",
-      "20.98" => "Project deleted",
-      "20.99" => "WD approved for registration as CD",
-      "30.00" => "Committee draft (CD) registered",
-      "30.20" => "CD study/ballot initiated",
-      "30.60" => "Close of voting/ comment period",
-      "30.92" => "CD referred back to Working Group",
-      "30.98" => "Project deleted",
-      "30.99" => "CD approved for registration as DIS",
-      "40.00" => "DIS registered",
-      "40.20" => "DIS ballot initiated: 12 weeks",
-      "40.60" => "Close of voting",
-      "40.92" => "Full report circulated: DIS referred back to TC or SC",
-      "40.93" => "Full report circulated: decision for new DIS ballot",
-      "40.98" => "Project deleted",
-      "40.99" => "Full report circulated: DIS approved for registration as FDIS",
-      "50.00" => "Final text received or FDIS registered for formal approval",
-      "50.20" => "Proof sent to secretariat or FDIS ballot initiated: 8 weeks",
-      "50.60" => "Close of voting. Proof returned by secretariat",
-      "50.92" => "FDIS or proof referred back to TC or SC",
-      "50.98" => "Project deleted",
-      "50.99" => "FDIS or proof approved for publication",
-      "60.00" => "International Standard under publication",
-      "60.60" => "International Standard published",
-      "90.20" => "International Standard under systematic review",
-      "90.60" => "Close of review",
-      "90.92" => "International Standard to be revised",
-      "90.93" => "International Standard confirmed",
-      "90.99" => "Withdrawal of International Standard proposed by TC or SC",
-      "95.20" => "Withdrawal ballot initiated",
-      "95.60" => "Close of voting",
-      "95.92" => "Decision not to withdraw International Standard",
-      "95.99" => "Withdrawal of International Standard"
-    }.freeze
-
-    DRAFT_STAGES = %w[00.00 00.20 00.60 00.99 10.00 10.20 10.60 10.92 10.99 20.00 20.20 20.60 20.99 30.00
-                      30.20 30.60 30.92 30.99 40.00 40.20 40.60 40.92 40.93 40.99 50.00 50.20 50.60
-                      50.92 50.99].freeze
-
-    CANCELED_STAGES = %w[00.98 10.98 20.98 30.98 40.98 50.98 95.99].freeze
-
-    PUBLISHED_STAGES = %w[60.00 60.60 90.20 90.60 90.92 90.93 90.99 95.20 95.60 95.92].freeze
-
-    STAGES_NAMES = {
-      preliminary: "00",
-      proposal: "10",
-      preparatory: "20",
-      committee: "30",
-      enquiry: "40",
-      approval: "50",
-      publication: "60",
-      review: "90",
-      withdrawal: "95",
-    }.freeze
-
-    SUBSTAGES_NAMES = {
-      registration: "00",
-      start_of_main_action: "20",
-      completion_of_main_action: "60",
-      repeat_an_earlier_phase: "92",
-      repeat_current_phase: "93",
-      abandon: "98",
-      proceed: "99",
-    }.freeze
-
-    # @param stage_or_code [String,Array<String>] stage number or whole harmonized code with substage
-    #   or list or stages for fuzzy stages eg. "10", 10, "20.20", ["10.20", "20.20"]
-    # @param substage [Integer, String] eg. "00", 0
-    def initialize(stage_or_code, substage = "00")
-      @stages = if stage_or_code.is_a?(Array)
-                  stage_or_code
-                elsif stage_or_code.is_a?(String) && DESCRIPTIONS.key?(stage_or_code)
-                  [stage_or_code]
-                # when stage is stage name
-                elsif STAGES_NAMES.key?(stage_or_code)
-                  ["#{STAGES_NAMES[stage_or_code]}.#{SUBSTAGES_NAMES[substage]}"]
-                else
-                  # stage is number
-                  ["#{stage_or_code}.#{substage}"]
-                end
-      validate_stages
-    end
-
-    def validate_stages
-      @stages.each do |stage|
-        # raise an error when stage is wrong
-        raise Errors::HarmonizedStageCodeInvalidError unless DESCRIPTIONS.key?(stage)
-      end
-    end
-
-    def to_s
-      if fuzzy?
-        return "draft" if @stages.all? { |s| DRAFT_STAGES.include?(s) || CANCELED_STAGES.include?(s) }
-
-        return "published" if @stages.all? { |s| PUBLISHED_STAGES.include?(s) }
-
-        raise Errors::HarmonizedStageRenderingError, "cannot render fuzzy stages"
-      else
-        @stages.first
-      end
-    end
-
-    def ==(other)
-      (stages & other.stages) == other.stages
-    end
-
-    def fuzzy?
-      @stages.length > 1
-    end
-
-    def stage
-      raise Errors::HarmonizedStageRenderingError, "cannot render stage for fuzzy stages" if fuzzy?
-
-      return nil if @stages.empty?
-
-      @stages.first.split(".").first
-    end
-
-    def substage
-      raise Errors::HarmonizedStageRenderingError, "cannot render substage for fuzzy stages" if fuzzy?
-
-      @stages.first.split(".").last
-    end
-
-    def description
-      DESCRIPTIONS[to_s]
-    end
   end
 end

data/lib/pubid/iso/identifier/amendment.rb

@@ -0,0 +1,38 @@
+require_relative "../renderer/amendment"
+require_relative "../renderer/urn-amendment"
+
+module Pubid::Iso
+  module Identifier
+    class Amendment < Supplement
+      def_delegators 'Pubid::Iso::Identifier::Amendment', :type
+
+      TYPED_STAGES = {
+        damd: {
+          abbr: "DAM",
+          legacy_abbr: %w[DAmd FPDAM],
+          name: "Draft Amendment",
+          harmonized_stages: %w[40.00 40.20 40.60 40.92 40.93 40.98 40.99],
+        },
+        fdamd: {
+          abbr: "FDAM",
+          legacy_abbr: %w[FDAmd],
+          name: "Final Draft Amendment",
+          harmonized_stages: %w[50.00 50.20 50.60 50.92 50.98 50.99],
+        },
+      }.freeze
+      def self.type
+        { key: :amd, title: "Amendment" }
+      end
+
+      def self.get_renderer_class
+        Renderer::Amendment
+      end
+
+      def urn
+        raise Errors::NoEditionError, "Base document must have edition" unless base_has_edition?
+
+        Renderer::UrnAmendment.new(get_params).render
+      end
+    end
+  end
+end