glossarist 2.0.1 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0462402c995f5b7e9fb01a4ee0d8e1f9ee3c5633c18fa071d9db6aa9f21f99f
-  data.tar.gz: 444e2d92467c4101edc81bc1af65fb6aeecaa0e138f63a49076f2283802baf17
+  metadata.gz: 550f2f9abb0af4adf53b54b99bb00eb40b7bac9b1a3dfb96971a2819f524d0af
+  data.tar.gz: 58f56b76ae70724248439a06ed2bd45d851cb1e3a135c4e6488efc2c918c7e88
 SHA512:
-  metadata.gz: ab7f0f87234df6fcd73286969c53e1186fcd247b4d8972a8d305b74cc995a4200785db43215a0d5aae719bc164123035f87a1756c104aa3d36b38775585f2019
-  data.tar.gz: d5f4a8834eb1d8bbb19d8352c13159e4626c8ff65233b5269658b77c4ee753bbcd8dcaf4502981b1ae2556a13e8af8deb45661e86f485cf7df25cf0f9d1cbb57
+  metadata.gz: c3d0e053d7da22e44b70ca26bddfc20981cc03d62a13584d17e1f8883cd072f46ec172c46808437e4d73956a2faf4d61adb51b61a486772d52a6e2339030b400
+  data.tar.gz: 1ea25c4c4ffcc7171cc60e58ba3a4e478d4e0b734037faafcc29790176a1bc72758d79323fa3c5b8365de270f5672a02f4d55c8e5275c0361610f6e2850bfea0

data/README.adoc

@@ -1,11 +1,328 @@
+:glossarist_model_url: https://github.com/glossarist/concept-model/tree/main
+:glossarist_model_v2_schema_url: https://github.com/glossarist/concept-model/tree/main/yaml_schemas
+
 = Glossarist
 
+Glossarist gem implements the {glossarist_model_url}[Glossarist model] in ruby. All the entities in the model are available as classes and all the attributes are available as methods of those classes.
+This gem also allows you to read/write data to concept dataset or create your own collection and save that to glossarist model V2 dataset.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[,ruby]
+----
+gem 'glossarist'
+----
+
+And then execute:
+[,bash]
+----
+bundle install
+----
+
+Or install it yourself as:
+[,bash]
+----
+gem install glossarist
+----
+
+== Usage
+
+=== Reading a Glossarist model V2 from files
+
+To load the glossarist model V2 dataset
+
+[,ruby]
+----
+collection = Glossarist::ManagedConceptCollection.new
+collection.load_from_files("path/to/glossarist-v2-dataset")
+----
+
+=== Writing a Glossarist model V2 to files
+
+To wite the glossarist model V2 dataset to files
+
+[,ruby]
+----
+collection = Glossarist::ManagedConceptCollection.new
+collection.load_from_files("path/to/glossarist-v2-dataset")
+
+# ... Update the collection ...
+
+collection.save_to_files("path/to/glossarist-v2-dataset")
+----
+
+=== ManagedConceptCollection
+
+This is a collection for <<managed-concept,managed concepts>>. It includes the ruby 'Enumerable' module.
+
+[,ruby]
+----
+collection = Glossarist::ManagedConceptCollection.new
+----
+
+[[id,managed-concept]]
+=== ManagedConcept
+
+Following fields are available for ManagedConcept:
+
+id:: String identifier for the concept
+uuid:: UUID for the concept
+related:: Array of <<related-concept,RelatedConcept>>
+status:: Enum for the normative status of the term.
+dates:: Array of <<concept-date,ConceptDate>>
+localized_concepts:: Hash of all localizations where keys are language codes and values are uuid of the localized concept.
+groups:: Array of groups in string format
+localizations:: Hash of all localizations for this concept where keys are language codes and values are instances of <<localized-concept,LocalizedConcept>>.
+
+There are two ways to initialize and populate a managed concept
+
+1. Setting the fields by using a hash while initializing
++
+[,ruby]
+----
+concept = Glossarist::ManagedConcept.new({
+  "data" => {
+    "id" => "123",
+    "localized_concepts" => {
+      "ara" => "<uuid>",
+      "eng" => "<uuid>"
+    },
+    "localizations" => <Array of localized concepts or localized concept hashes>,
+    "groups" => [
+      "foo",
+      "bar",
+    ],
+  },
+})
+----
+
+2. Setting the fields after creating an object
++
+[,ruby]
+----
+concept = Glossarist::ManagedConcept.new
+concept.id = "123"
+concept.groups = ["foo", "bar"]
+concept.localizations = <Array of localized concepts or localized concept hashes>
+----
+
+[[id,localized-concept]]
+=== LocalizedConcept
+
+Localizations of the term to different languages.
+
+Localized concept has the following fields
+
+id:: An optional identifier for the term, to be used in cross-references.
+uuid:: UUID for the concept
+designations:: Array of <<designation,Designations>> under which the term being defined is known. This method will also accept an array of hashes for designation and will convert them to their respective classes.
+domain:: An optional semantic domain for the term being defined, in case the term is ambiguous between several semantic domains.
+subject:: Subject of the term.
+definition:: Array of <<detailed-definition,Detailed Definition>> of the term.
+non_verb_rep:: Array of <<non-verbal,non-verbal>> representations used to help define the term.
+notes:: Zero or more notes about the term. A note is in <<detailed-definition,Detailed Definition>> format.
+examples:: Zero or more examples of how the term is to be used in <<detailed-definition,Detailed Definition>> format.
+language_code:: The language of the localization, as an ISO-639 3-letter code.
+entry_status:: Entry status of the concept. Must be one of the following: +notValid+, +valid+, +superseded+, +retired+.
+classification:: Classification of the concept. Must be one of the following: +preferred+, +admitted+, +deprecated+.
+
+[[id,designation]]
+=== Designation::Base
+
+A name under which a managed term is known.
+
+Methods::
+  `from_h(options)`::: Creates a new designation instance based on the specified type.
+
+Parameters::
+  * options (Hash) - The options for creating the designation.
+  * "type" (String) - The type of designation (expression, symbol, abbreviation, graphical_symbol, letter_symbol). Note: type key should be string and not a symbol so { type: "expression" } will not work.
+  * Additional options depend on the specific designation type.
+
+Returns::
+  Designation::{type}::: A new instance of specified type. e.g `Glossarist::Designation::Base.from_h("type" => "expression")` will return `Glossarist::Designation::Expression`
+
+Example
+[,ruby]
+----
+# Example usage of Designation::Base class
+
+attributes_for_expression = { designation: "foobar", geographical_area: "abc", normative_status: "status" }
+designation_expression = Designation::Base.from_h({ "type" => "expression" }.merge(attributes_for_expression))
+
+attributes_for_abbreviation = { designation: "foobar", geographical_area: "abc", normative_status: "status", international: true }
+designation_abbreviation = Designation::Base.from_h({ "type" => "abbreviation" }.merge(attributes_for_abbreviation))
+
+----
+
+[[id,related-concept]]
+=== RelatedConcept
+
+A term related to the current term.
+
+Following fields are available for the Related Concept
+
+type:: An enum to denote the relation of the term to the current term.
+content:: The designation of the related term.
+ref:: A <<citation, citation>> of the related term, in a Termbase.
+
+There are two ways to initialize and populate a related concept
+
+1. Setting the fields by using a hash while initializing
++
+[,ruby]
+----
+related_concept = Glossarist::RelatedConcept.new({
+  content: "Test content",
+  type: :supersedes,
+  ref: <concept citation>
+})
+----
+
+2. Setting the fields after creating an object
++
+[,ruby]
+----
+related_concept = Glossarist::RelatedConcept.new
+related_concept.type = "supersedes"
+related_concept.content = "designation of the related concept"
+related_concept.ref = <Citation object>
+----
+
+[[id,concept-date]]
+=== Concept Date
+
+A date relevant to the lifecycle of the managed term.
+
+Following fields are available for the Concept Date
+
+- date: The date associated with the managed term in Iso8601Date format.
+- type: An enum to denote the event which occured on the given date and associated with the lifecycle of the managed term.
+
+There are two ways to initialize and populate a concept date
+
+1. Setting the fields by using a hash while initializing
++
+[,ruby]
+----
+concept_date = Glossarist::ConceptDate.new({
+  date: "2010-11-01T00:00:00.000Z",
+  type: :accepted,
+})
+----
+
+2. Setting the fields after creating an object
++
+[,ruby]
+----
+concept_date = Glossarist::ConceptDate.new
+concept_date.type = :accepted
+concept_date.date = "2010-11-01T00:00:00.000Z"
+----
+
+[[id,detailed-definition]]
+=== DetailedDefinition
+
+A definition of the managed term.
+
+It has the following attributes:
+
+content:: The text of the definition of the managed term.
+sources:: List of Bibliographic references(<<citation,Citation>>) for this particular definition of the managed term.
+
+There are two ways to initialize and populate a detailed definition
+
+1. Setting the fields by using a hash while initializing
++
+[,ruby]
+----
+detailed_definition = Glossarist::DetailedDefinition.new({
+  content: "plain text reference",
+  sources: [<list of citations>],
+})
+----
+
+2. Setting the fields after creating an object
++
+[,ruby]
+----
+detailed_definition = Glossarist::DetailedDefinition.new
+detailed_definition.content = "plain text reference",
+detailed_definition.sources = [<list of citations>]
+----
+
+[[id,citation]]
+=== Citation
+
+Citation can be either structured or unstructured. A citation is structured if its reference contains one or all of the following keys `{ id: "id", source: "source", version: "version"}` and is unstructured if its reference is plain text. This also has 2 methods `structured?` and `plain?` to check if citation is structured or not.
+
+Citation has the following attributes.
+
+ref:: A hash or string based on type of citation. Hash if citation is structured or string if citation is plain.
+clause:: Referred clause of the document.
+link:: Link to document.
+
+There are two ways to initialize and populate a Citation
+
+1. Setting the fields by using a hash while initializing
++
+[,ruby]
+----
+# Unstructured Citation
+citation = Glossarist::Citation.new({
+  ref: "plain text reference",
+  clause: "clause",
+  link: "link",
+})
+
+# Structured Citation
+citation = Glossarist::Citation.new({
+  ref: { id: "123", source: "source", version: "1.1" },
+  clause: "clause",
+  link: "link",
+})
+----
+
+2. Setting the fields after creating an object
++
+[,ruby]
+----
+citation = Glossarist::Citation.new
+citation.ref = <plain or structured ref>
+citation.clause = "some clause"
+----
+
+=== NonVerbRep
+
+Non-verbal Representation have the following fields
+
+image:: An image used to help define a term.
+table:: A table used to help define a term.
+formula:: A formula used to help define a term.
+sources:: Bibliographic <<concept-source,concept source>> for the non-verbal representation of the term.
+
+[[id,concept-source]]
+=== ConceptSource
+
+Concept Source has the following fields
+
+status:: The status of the managed term in the present context, relative to the term as found in the bibliographic source.
+type:: The type of the managed term in the present context.
+origin:: The bibliographic <<citation,citation>> for the managed term. This is also aliased as `ref`.
+modification:: A description of the modification to the cited definition of the term, if any, as it is to be applied in the present context.
+
+
 == Commands
 
-`generate_latex`: Convert Concepts to Latex format
+`generate_latex`:: Convert Concepts to Latex format
 
 === Usage:
-  glossarist generate_latex p, --concepts-path=CONCEPTS_PATH
+[,bash]
+----
+glossarist generate_latex p, --concepts-path=CONCEPTS_PATH
+----
 
 === Options:
 [cols="1,1"]

data/lib/glossarist/managed_concept_collection.rb

@@ -64,6 +64,8 @@ module Glossarist
     def store(managed_concept)
       @managed_concepts[managed_concept.uuid] = managed_concept
       @managed_concepts_ids[managed_concept.id] = managed_concept.uuid if managed_concept.id
+
+      managed_concept
     end
 
     alias :<< :store

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.0.1"
+  VERSION = "2.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.2
 platform: ruby
 authors:
 - Ribose
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-28 00:00:00.000000000 Z
+date: 2023-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: relaton