Library
Constructing Identifiers
There are three ways to obtain an identifier: parsing a printed reference,
rebuilding from a serialized hash, and constructing from typed attributes.
The v1 entry point — Pubid::Iso::Identifier.create(...) — no longer exists;
the v2 constructor is .new with keyword arguments.
Parsing
Pubid.parse routes on the leading prefix token (longest match first), so the
right grammar is chosen even when the caller does not know the flavor:
require 'pubid'
Pubid.parse("ISO 8601-1:2019").class # => Pubid::Iso::Identifiers::InternationalStandardPubid.parse("JIS Z 8301:2019").class # => Pubid::Jis::Identifiers::JapaneseIndustrialStandardWhen the flavor is known, name it directly: Pubid::Iso.parse("ISO 9001:2015").
The constructor
Pubid::<Flavor>::Identifier.new takes one keyword argument per declared
attribute, coerces scalars into the components the attributes declare, and
raises ArgumentError naming any key the class does not declare — a
silently-dropped key would otherwise produce an identifier with no year and
no diagnostic.
Pubid::Iso::Identifier.new(number: "8601", part: "1", year: "2019")# => ISO 8601-1:2019For a non-default document type, construct the concrete class — the class is the type:
Pubid::Iso::Identifiers::TechnicalReport.new(number: 123).to_s# => "ISO/TR 123"Scalars coerce into degenerate components — year:, month:, day: fold
into the date, edition: 2 wraps into the edition component, and IEC accepts
languages: ["en"] and copublishers: ["ISO"]:
Pubid::Iec::Identifiers::InternationalStandard.new( number: "1000", part: "1", year: 2023, edition: 2, languages: ["en"],).to_s # => "IEC 1000-1:2023 ED2(en)"The coercion is type-aware: a flavor that declares an attribute as a plain
string keeps the string, and number is never wrapped.
Stages (ISO)
ISO stages are typed stages — a stage and document type combined (WD,
DIS, FDIS, WD Amd, DAM, FDCor). Look the registry entry up and set
it:
Pubid::Iso::Identifiers::InternationalStandard.new( number: 123, typed_stage: Pubid::Iso.locate_stage("WD"),).to_s # => "ISO/WD 123"
ts = Pubid::Iso.locate_stage("FDIS")ts.abbreviation # => "FDIS"ts.name # => "Final Draft International Standard"ISO type and stage are derived from typed_stage — there is no separate
type: or stage: keyword to set. The stage iteration (.2 in
ISO/DIS 123-1.2) is its own keyword, stage_iteration:.
Supplements with a base
A supplement wraps the document it modifies under the uniform base
attribute; the supplement is its own class with the ordinal in number:
base = Pubid::Iso::Identifiers::InternationalStandard.new( number: "123", part: "1", year: 2019,)
Pubid::Iso::Identifiers::Amendment.new(number: 1, year: 2021, base: base).to_s# => "ISO 123-1:2019/Amd 1:2021"
Pubid::Iso::Identifiers::Corrigendum.new(number: "1", year: "2021", base: base).to_s# => "ISO 123-1:2019/Cor 1:2021"IEC renders the compact supplement face:
base = Pubid::Iec::Identifiers::InternationalStandard.new( number: "60050", part: "351", year: 2013,)Pubid::Iec::Identifiers::Amendment.new(number: "1", year: 2016, base: base).to_s# => "IEC 60050-351:2013/AMD1:2016"IEEE carries its identity in a code: keyword:
Pubid::Ieee::Identifier.new(code: "802.11", year: 2020).to_s# => "IEEE Std 802.11-2020"Copublishers
Joint publications are modeled per flavor. IEC coerces copublisher scalars;
ISO takes its own Publisher component:
Pubid::Iec::Identifiers::InternationalStandard.new( number: "1000", copublishers: ["ISO"],).to_s # => "IEC/ISO 1000"
Pubid::Iso::Identifier.new( publisher: Pubid::Iso::Components::Publisher.new(copublisher: ["IEC"]), number: 123,).to_s # => "ISO/IEC 123"from_hash
#to_hash emits the canonical hash, and Pubid.from_hash rebuilds the
concrete class from it — reading the _type key
(pubid:<flavor>:<type>), so the caller never names the flavor:
id = Pubid::Iso.parse("ISO 9001:2015/Amd 1:2020/Cor 1:2021")Pubid.from_hash(id.to_hash).to_s # => "ISO 9001:2015/Amd 1:2020/Cor 1:2021"The round-trip invariant from_hash(id.to_hash) == id holds for every flavor
— equality is what index lookups are made of, so a construction path that
holds a value the other path does not would break matching.
Errors
Pubid.parse raises Pubid::Errors::ParseError (a Parslet::ParseFailed)
for an unparseable string; unknown constructor keys raise ArgumentError;
a hash with no or unknown _type raises Pubid::Errors::InvalidInputError.
Rescue Pubid::Errors::Error to catch all of them.