metanorma-plugin-glossarist 0.1.8 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12c432cfc7a1397fe5a88e961db51aa103712a0a81bc1eca871e073774c60fbe
-  data.tar.gz: a8d24f1c847b536dae718dc96ba559a8f5e83f8213c6a9490b3f173a3b88e881
+  metadata.gz: a817c5969de17ce761956773dce8a9aeb2dee7e2c1bde5f3970783438dd008a1
+  data.tar.gz: 2cbc4ca6b683be306731443ab4ca1d8930b97a2bad8a1c0588d8c12d54b27d80
 SHA512:
-  metadata.gz: 7acd13849a68c375d9113a8a93dc4abe55df7d6c9a72f3aeb1fbd10f0b3c8e746c2f06f203fe85718f6e5306132211fac8fea044fe346350e9abd6914958ce4e
-  data.tar.gz: 4dd925541b2181f9301b838eb1c4b5c2a52b7e7e458334b25956c18ee1511b10d4c18f0b58680e6ab8087323978851d8f3ed2afee7241fc089fb38e22ae62abd
+  metadata.gz: 5f37a8fd2db74f26be2868893eeac5ad65f5014e15f7748ff21975747c864f5d52d14a66bd1263d3be1a608a6032564b2db2a13045222a642a1308a7ad7d5637
+  data.tar.gz: c9b4b823a8e9ba4167d37b7f4d8a4d3c51c27af9cb5d411b35d3690dce50206ef1b682ccbe7bd0cb03fed06a1d977252cb3bc24222ccd570a909196f64c015a5

data/Gemfile

@@ -1,4 +1,9 @@
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
 source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}" }
 
-# Specify your gem's dependencies in metanorma-plugin-glossarist.gemspec
 gemspec
+
+eval_gemfile("Gemfile.devel") rescue nil

data/README.md

@@ -1,8 +1,6 @@
 # Metanorma::Plugin::Glossarist
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/metanorma/plugin/glossarist`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Metanorma plugin that allows you to access data from the glossarist dataset inside a Metanorma document.
 
 ## Installation
 
@@ -22,7 +20,271 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+In order to use the macros in Metanorma, add the gem gem `metanorma-plugin-glossarist` in your Gemfile.
+
+## Available Macros
+
+Currently, there are 6 macros available for this plugin and all of them support all [Liquid syntax expressions](https://shopify.github.io/liquid/basics/introduction/), including:
+
+- Loading Dataset
+  - `:glossarist-dataset: <dataset name>:<dataset path>`
+  - `[glossarist,<dataset path>, [filters], <dataset name>]`
+- Rendering a single term from loaded dataset `glossarist::render[<dataset name>, <term>]`
+- Rendering all terms from loaded dataset `glossarist::import[<dataset name>]`
+- Rendering bibliography for a single term in the dataset `glossarist::render_bibliography_entry[<dataset name>, <term>]`
+- Rendering bibliography for all terms in the dataset`glossarist::render_bibliography[<dataset name>]`
+
+### Loading Dataset
+
+There are 2 ways of loading a dataset
+1. Global syntax `:glossarist-dataset: <dataset name>:<dataset path>`
+2. Block syntax `[glossarist,<dataset path>, [filters], <dataset name>]`
+
+### Global syntax `:glossarist-dataset: <dataset name>:<dataset path>`
+
+This will load the glossarist data from `<dataset path>` into `<dataset name>` which can be used anywhere in the document after this line.
+
+#### Example
+
+Suppose we have a term named `foobar` in our dataset with the definition `The term foobar is used as metasyntactic variables and placeholder names in computer programming`
+
+```adoc
+:glossarist-dataset: dataset:./path/to/glossarist-dataset
+
+=== Section 1
+{{ dataset['foobar']['eng'].definition[0].content }}
+```
+
+this will output
+
+```adoc
+=== Section 1
+The term foobar is used as metasyntactic variables and placeholder names in computer programming
+```
+
+### Block syntax`[glossarist,<dataset path>, [filters], <dataset name>]`
+
+This will load the glossarist data from `<dataset path>` into `<dataset name>` which can be used in the given block. Filters are optional and can be used to filter and/or sort the loaded concepts from the glossarist dataset multiple filters can be added by separating them with a semicolon `;`. Filter can be added by adding `filter='<filters to apply>;<another filter>'`
+
+Available filters are:
+- `sort_by:<field name>`: will sort the dataset in ascending order of the given field values e.g `sort_by:term` will sort concepts in ascending order based on the term.
+- `<field name>:<values>`: will only load a concept if the value of the given field name is equal to the given value e.g `group=foo` will only load a concept if it has a group named `foo` or `lang=ara` will only load Arabic translations for all concepts.
+
+#### Example
+
+Suppose we have the following terms in our dataset
+
+| Name | Definition | Groups |
+| ----- | ----- | ----- |
+| foo | The term foo is used as metasyntactic variables and placeholder names in computer programming | foo |
+| bar | The term bar is used as metasyntactic variables and placeholder names in computer programming | foo, bar |
+| baz | The term baz is used as metasyntactic variables and placeholder names in computer programming | baz |
+
+```adoc
+=== Definitions
+[glossarist, /path/to/glossarist-dataset, dataset]
+----
+{%- for concept in dataset -%}
+==== {{ concept.term }}
+
+{{ concept.eng.definition[0].content }}
+{%- endfor -%}
+----
+```
+
+this will output
+
+```adoc
+=== Section 1
+
+==== foo
+
+The term foo is used as metasyntactic variables and placeholder names in computer programming
+
+==== bar
+
+The term bar is used as metasyntactic variables and placeholder names in computer programming
+
+==== baz
+
+The term baz is used as metasyntactic variables and placeholder names in computer programming
+```
+
+Applying sorting and filtering by group
+
+```adoc
+=== Definitions
+[glossarist, /path/to/glossarist-dataset, filter='group=foo;sort_by=term', dataset]
+----
+{%- for concept in dataset -%}
+==== {{ concept.term }}
+
+{{ concept.eng.definition[0].content }}
+{%- endfor -%}
+----
+```
+
+this will output
+
+```adoc
+=== Section 1
+
+==== bar
+
+The term bar is used as metasyntactic variables and placeholder names in computer programming
+
+==== foo
+
+The term foo is used as metasyntactic variables and placeholder names in computer programming
+```
+
+### Rendering a single term from loaded dataset
+
+This can be used to render a single concept from the loaded dataset. See [Loading Dataset](#loading-dataset) to load a dataset.
+This will use the [default template for rendering concepts](#default-template-for-rendering-concepts)
+
+#### Syntax
+
+`glossarist::render[<dataset name>, <term>]`
+
+#### Example
+
+Suppose we have a term named `foobar` in our dataset with the definition `The term foobar is used as metasyntactic variables and placeholder names in computer programming`
+
+```adoc
+:glossarist-dataset: dataset:./path/to/glossarist-dataset
+
+=== Section
+glossarist::render[dataset, foobar]
+```
+
+then the output will be
+
+```adoc
+=== Section
+==== entity
+concrete or abstract thing that exists, did exist, or can possibly exist, including associations among these things
+```
+
+### Rendering all terms from loaded dataset
+
+This will render all the concepts from the [loaded dataset](#loading-dataset) using [default template for rendering concepts](#default-template-for-rendering-concepts)
+
+#### Syntax
+
+`glossarist::import[<dataset name>]`
+
+
+### Rendering bibliography for a single term in the dataset
+
+This will render a bibliography for a single term in the [loaded dataset](#loading-dataset) using the [default template for bibliography](#default-template-for-bibliography)
+
+#### Syntax
+
+`glossarist::render_bibliography_entry[<dataset name>, <term>]`
+
+#### Example
+
+Suppose we have a concept `foo` with the ref `ISO/TS 14812:2022`, then we can render the bibliography for this like
+
+```adoc
+:glossarist-dataset: dataset:./path/to/glossarist-dataset
+
+glossarist::render_bibliography_entry[dataset, foo]
+```
+
+then the output will be
+
+```adoc
+* [[[ISO_TS_14812_2022,ISO/TS 14812:2022]]]
+```
+
+### Rendering bibliography for all terms in the dataset
+
+This will render all the bibliographies for the given dataset
+
+#### Syntax
+
+`glossarist::render_bibliography[<dataset name>]`
+
+#### Example
+
+Suppose we have following concepts in dataset
+
+- `foo` with ref `ISO/TS 14812:2022`
+- `bar` with ref `ISO/TS 14812:2023`
+
+then we can render the bibliography for this like
+
+```adoc
+:glossarist-dataset: dataset:./path/to/glossarist-dataset
+
+glossarist::render_bibliography[dataset]
+```
+
+then the output will be
+
+```adoc
+* [[[ISO_TS_14812_2022,ISO/TS 14812:2022]]]
+* [[[ISO_TS_14812_2023,ISO/TS 14812:2023]]]
+```
+
+
+### Default template for rendering concepts
+
+```adoc
+==== {{ concept.term }}
+<type>:[designation for the type]
+
+{{ dataset[<concept name>]['eng'].definition[0].content }}
+
+{% for example in <dataset name>[<concept name>]['eng'].examples %}
+[example]
+{{ example.content }}
+
+{% endfor %}
+
+{% for note in <dataset name>[<concept name>]['eng'].notes %}
+[NOTE]
+====
+{{ note.content }}
+====
+
+{% endfor %}
+
+{% for source in <dataset name>[<concept name>]['eng'].sources %}
+[.source]
+<<{{ source.origin.ref | replace: ' ', '_' | replace: '/', '_' | replace: ':', '_' }},{{ source.origin.clause }}>>
+
+{% endfor %}
+```
+
+#### Example
+
+```adoc
+==== foobar
+admitted:[E]
+
+The term foobar is used as metasyntactic variables and placeholder names in computer programming
+
+[example]
+example for the term
+
+[NOTE]
+====
+note for the term
+====
+
+[.source]
+<<ISO_TS_14812_2022,foo_bar_id>>
+```
+
+### Default template for bibliography
+
+```adoc
+* [[[{{ source.origin.ref | replace: ' ', '_' | replace: '/', '_' | replace: ':', '_' }},{{ source.origin.clause }},{{source.origin.ref}}]]]
+```
+
 
 ## Development
 

data/lib/liquid/drops/concepts_drop.rb

@@ -32,25 +32,20 @@ module Liquid
 
       def filtered_concepts(concepts_collection, filters)
         concept_filters = filters.dup
-        language_filter = concept_filters.delete('lang')
-        sort_filter = concept_filters.delete('sort_by')
-        group_filter = concept_filters.delete('group')
+        language_filter = concept_filters.delete("lang")
+        sort_filter = concept_filters.delete("sort_by")
+        group_filter = concept_filters.delete("group")
 
         concepts = concepts_collection.map do |concept|
           filtered_concept = concept.to_h["data"]
           filtered_concept["term"] = concept.default_designation
 
           filtered_concept = filtered_concept.merge(
-            extract_localized_concepts(
-              concept,
-              language_filter,
-            ),
+            extract_localized_concepts(concept, language_filter),
           )
 
           if retain_concept?(filtered_concept, concept_filters)
             filtered_concept
-          else
-            nil
           end
         end.compact
 
@@ -62,13 +57,13 @@ module Liquid
         localized_concepts = {}
 
         if !languages || languages.empty?
-          concept.localized_concepts.each do |lang, localized_concept_uuid|
+          concept.localized_concepts.each do |lang, _localized_concept_uuid|
             localized_concepts[lang] = concept.localizations[lang].to_h["data"]
           end
         else
           languages.split(",").each do |lang|
-            localization = concept.localizations[lang]&.to_h&.dig("data")
-            localized_concepts[lang] = localization if localization
+            localization = concept.localizations[lang]&.to_h&.dig("data") and
+              localized_concepts[lang] = localization
           end
         end
 
@@ -81,10 +76,8 @@ module Liquid
           if fields.last.start_with?("start_with")
             value = fields.last.gsub(/start_with\(([^\)]*)\)/, '\1')
             fields = fields[0..-2]
-
-            unless filtered_concept.dig(*fields).start_with?(value)
+            filtered_concept.dig(*fields).start_with?(value) or
               return false
-            end
           elsif filtered_concept.dig(*fields) != value
             return false
           end
@@ -96,7 +89,9 @@ module Liquid
       def apply_sort_filter(concepts, sort_by)
         return concepts unless sort_by
 
-        concepts.sort_by { |concept| concept.dig(*extract_nested_field_names(sort_by)) }
+        concepts.sort_by do |concept|
+          concept.dig(*extract_nested_field_names(sort_by))
+        end
       end
 
       def apply_group_filter(concepts, groups)
@@ -113,7 +108,7 @@ module Liquid
         name.split(".").map do |field|
           field_name = field.strip
 
-          field_name.match(/^\d+$/) ? field_name.to_i : field_name
+          /^\d+$/.match?(field_name) ? field_name.to_i : field_name
         end
       end
 

data/lib/metanorma/plugin/glossarist/dataset_preprocessor.rb

@@ -65,7 +65,7 @@ module Metanorma
         end
 
         def process(document, reader)
-          input_lines = reader.readlines.to_enum
+          input_lines = reader.lines.to_enum
 
           file_system = ::Liquid::LocalFileSystem.new(
             relative_file_path(document, ""),
@@ -74,9 +74,8 @@ module Metanorma
           @config[:file_system] = file_system
 
           processed_doc = prepare_document(document, input_lines)
-          Asciidoctor::Reader.new(
-            processed_doc.to_s.split("\n"),
-          )
+          Asciidoctor::PreprocessorReader.new(document,
+                                              processed_doc.to_s.split("\n"))
         end
 
         private
@@ -176,7 +175,7 @@ module Metanorma
           liquid_doc.add_content(
             dataset.concepts.map do |concept_name, _concept|
               concept_template(context_name, concept_name)
-            end.join("\n")
+            end.join("\n"),
           )
         end
 
@@ -187,7 +186,7 @@ module Metanorma
           liquid_doc.add_content(
             dataset.concepts.map do |_concept_name, concept|
               concept_bibliography(concept)
-            end.compact.sort.join("\n")
+            end.compact.sort.join("\n"),
           )
         end
 
@@ -196,7 +195,7 @@ module Metanorma
           concept = @datasets[dataset_name][concept_name]
 
           liquid_doc.add_content(
-            concept_bibliography(concept)
+            concept_bibliography(concept),
           )
         end
 
@@ -206,7 +205,7 @@ module Metanorma
 
             next if @rendered_bibliographies[ref]
 
-            @rendered_bibliographies[ref] = ref.gsub(/[ \/:]/, '_')
+            @rendered_bibliographies[ref] = ref.gsub(/[ \/:]/, "_")
             "* [[[#{@rendered_bibliographies[ref]},#{ref}]]]"
           end.compact.join("\n")
 

data/lib/metanorma/plugin/glossarist/version.rb

@@ -1,7 +1,7 @@
 module Metanorma
   module Plugin
     module Glossarist
-      VERSION = "0.1.8"
+      VERSION = "0.2.0".freeze
     end
   end
 end

data/metanorma-plugin-glossarist.gemspec

@@ -1,4 +1,4 @@
-require_relative 'lib/metanorma/plugin/glossarist/version'
+require_relative "lib/metanorma/plugin/glossarist/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "metanorma-plugin-glossarist"
@@ -14,8 +14,10 @@ Gem::Specification.new do |spec|
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-glossarist
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-29 00:00:00.000000000 Z
+date: 2024-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor