unitsml 0.4.7 → 0.6.0

data/docs/README.adoc

@@ -69,7 +69,7 @@ unit.to_s # => "m"
 unit.to_xml
 # =>
 <Unit xmlns="https://schema.unitsml.org/unitsml/1.0" xml:id="U_NISTu1" dimensionURL="#NISTd1">
-  <UnitSystem name="SI" type="SI_derived" xml:lang="en-US"/>
+  <UnitSystem name="SI" type="SI_derived" xml:lang="en"/>
   <UnitName xml:lang="en">meter</UnitName>
   <UnitSymbol type="HTML">m</UnitSymbol>
   <UnitSymbol type="MathMl">
@@ -102,7 +102,7 @@ unit.to_s # => "um"
 unit.to_xml
 # =>
 <Unit xmlns="https://schema.unitsml.org/unitsml/1.0" xml:id="U_um" dimensionURL="#NISTd1">
-  <UnitSystem name="SI" type="SI_derived" xml:lang="en-US"/>
+  <UnitSystem name="SI" type="SI_derived" xml:lang="en"/>
   <UnitName xml:lang="en">um</UnitName>
   <UnitSymbol type="HTML">&micro;m</UnitSymbol>
   <UnitSymbol type="MathMl"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
@@ -169,6 +169,104 @@ unit.to_unicode    # Unicode representation
 unit.to_xml        # XML (in UnitsML) representation
 ----
 
+==== Explicit parenthesis
+
+When converting units to formats like MathML or LaTeX, you can specify whether
+to use explicit parentheses for clarity in complex expressions.
+
+A pair of parentheses is typically used for two purposes:
+
+. For grouping to indicate operator precedence in mathematical expressions. When
+expressing units, most of the time, parentheses are used to indicate operator
+precedence, parentheses are only kept in cases where it indicates precedence.
+When parentheses are not needed for precedence, such as in the expression
+`(m/s)`, the parentheses can be removed whilch simplifies the expression into
+`m/s`.
+
+. For indicating that an expression is a compound unit. These parentheses are
+explicit parentheses that cannot be removed without changing the meaning of the
+expression.
+
+UnitsML Ruby provides an option `explicit_parenthesis` to control the inclusion
+of parentheses in the output.
+
+In an expression:
+
+* `(...)` is considered an implicit parenthesis for grouping and operator
+precedence and can be removed without changing the meaning of the expression.
+
+* `((...))` is considered an explicit parenthesis, which indicates that the
+parentheses need to be preserved in the output regardless of operator
+precedence.
+
+The `explicit_parenthesis` option allows you to control how parentheses are
+considered in the output formats. It can be set to `true` or `false`.
+
+Syntax for using `explicit_parenthesis` is as follows:
+
+[source,ruby]
+----
+unit.to_asciimath(explicit_parenthesis: true) # or false
+unit.to_mathml(explicit_parenthesis: true) # or false
+unit.to_latex(explicit_parenthesis: true) # or false
+----
+
+When `explicit_parenthesis` is set to:
+
+`true`:: (default) the usage of `(...)` and `((...))` is differentiated as
+implicit and explicit parentheses, respectively.
+
+`false`:: all parentheses are treated as grouping parentheses, there is no
+difference between `(...)` and `((...))`.
+
+
+.By default `explicit_parenthesis` is `true` and double parentheses are considered explicit parentheses
+[example]
+====
+[source, ruby]
+----
+Unitsml.parse("((m/s))").to_asciimath
+> "(m/s^-1)" # Only one of the two pairs of parentheses are included in the output
+----
+====
+
+If an extra pair of parentheses is included, it will be considered as grouping
+parentheses and will not be included in the Unitsml::Formula or the output.
+
+.By default `explicit_parenthesis` is `true` and double parentheses are considered explicit parentheses
+[example]
+====
+[source, ruby]
+----
+Unitsml.parse("(((m/s)))").to_asciimath
+> "(m/s^-1)" # the third pair of parentheses are ignored as grouping parentheses
+Unitsml.parse("(((((m/s)))))").to_asciimath
+> "((m/s^-1))" # the fifth pair of parentheses are ignored as grouping parentheses
+----
+
+[source,ruby]
+----
+unit = Unitsml.parse("((m/s))")
+unit.to_asciimath # equivalent to (explicit_parenthesis: true) => "(m/s^-1)"
+unit = Unitsml.parse("((m/s))*((m/s))")
+unit.to_asciimath(explicit_parenthesis: true) # "(m/s^-1)*(m/s^-1)"
+----
+====
+
+When `explicit_parenthesis` is `false`, all parentheses are treated as grouping parentheses
+and therefore will be reduced to only the necessary parentheses for operator precedence.
+
+.When `explicit_parenthesis` is `false`, all parentheses are treated as grouping parentheses
+[example]
+====
+[source,ruby]
+----
+unit = Unitsml.parse("(m/s)")
+unit.to_asciimath(explicit_parenthesis: false) # => "m/s"
+unit = Unitsml.parse("((m/s))*((m/s))")
+unit.to_asciimath(explicit_parenthesis: false) # "m/s^-1*m/s^-1"
+----
+====
 
 
 == Installation
@@ -196,7 +294,9 @@ $ gem install unitsml
 
 == Usage
 
-*UnitsML* Ruby provides functionality to represent and convert units between different formats including *MathML*, *LaTeX*, *AsciiMath*, *HTML*, *Unicode*, and *XML*(*Unitsml* schema based elements).
+*UnitsML* Ruby provides functionality to represent and convert units between
+different formats including *MathML*, *LaTeX*, *AsciiMath*, *HTML*, *Unicode*,
+and *XML*(*Unitsml* schema based elements).
 
 === Basic Usage
 
@@ -275,7 +375,9 @@ repository.
 
 == Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec spec` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
 
 === Submodules
 

data/lib/unitsml/dimension.rb

@@ -9,63 +9,59 @@ module Unitsml
       @power_numerator = power_numerator
     end
 
-    def ==(object)
-      self.class == object.class &&
-        dimension_name == object&.dimension_name &&
-        power_numerator == object&.power_numerator
+    def ==(other)
+      self.class == other.class &&
+        dimension_name == other&.dimension_name &&
+        power_numerator == other&.power_numerator
     end
 
     def dim_instance
-      @dim ||= Unitsdb.dimensions.find_parsables_by_id(dimension_name)
+      @dim_instance ||= Unitsdb.dimensions.find_parsables_by_id(dimension_name)
     end
 
     def dim_symbols
-      dim_instance.send(@dim.processed_keys.last).dim_symbols.first
-    end
-
-    def to_mathml(_)
-      # MathML key's value in unitsdb/dimensions.yaml file includes mi tags only.
-      value = ::Mml::Mi.from_xml(dim_symbols.mathml)
-      method_name = power_numerator ? :msup : :mi
-      if power_numerator
-        value = ::Mml::Msup.new(
-          mrow_value: [
-            ::Mml::Mrow.new(mi_value: [value]),
-            ::Mml::Mrow.new(
-              mn_value: [::Mml::Mn.new(value: power_numerator)],
-            ),
-          ]
-        )
-      end
+      dim_instance.send(dim_instance.processed_keys.last).symbols.first
+    end
+
+    def to_mathml(options)
+      # MathML key's value in unitsdb/dimensions.yaml
+      # file includes mi tags only.
+      value = ::Mml::V4::Mi.from_xml(dim_symbols.mathml)
+      method_name = if power_numerator
+                      value = msup_tag(value, options)
+                      :msup
+                    else
+                      :mi
+                    end
       { method_name: method_name, value: value }
     end
 
-    def to_latex(_)
-      power_numerator_generic_code(:latex)
+    def to_latex(options)
+      power_numerator_generic_code(:latex, options)
     end
 
-    def to_asciimath(_)
-      power_numerator_generic_code(:ascii)
+    def to_asciimath(options)
+      power_numerator_generic_code(:ascii, options)
     end
 
-    def to_unicode(_)
-      power_numerator_generic_code(:unicode)
+    def to_unicode(options)
+      power_numerator_generic_code(:unicode, options)
     end
 
-    def to_html(_)
+    def to_html(options)
       value = dim_symbols.html
-      value = "#{value}<sup>#{power_numerator}</sup>" if power_numerator
+      value = "#{value}#{html_numerator_conversion(options)}" if power_numerator
       value
     end
 
     def generate_id
-      "#{dimension_name.split('_').last}#{power_numerator}"
+      "#{dimension_name.split('_').last}#{power_numerator&.raw_value}"
     end
 
     def to_xml(_)
       attributes = {
         symbol: dim_instance.processed_symbol,
-        power_numerator: power_numerator || 1,
+        power_numerator: power_numerator&.raw_value || 1
       }
       Model::DimensionQuantities.const_get(modelize(element_name)).new(attributes)
     end
@@ -75,20 +71,38 @@ module Unitsml
     end
 
     def modelize(value)
-      value&.split("_")&.map(&:capitalize)&.join
+      value&.split('_')&.map(&:capitalize)&.join
     end
 
     private
 
-    def power_numerator_generic_code(method_name)
+    def html_numerator_conversion(options)
+      "<sup>#{power_numerator.to_html(options)}</sup>"
+    end
+
+    def power_numerator_generic_code(method_name, options)
       value = dim_symbols.public_send(method_name)
       return value unless power_numerator
 
-      "#{value}^#{power_numerator}"
+      method_name = :asciimath if method_name == :ascii
+      "#{value}^#{power_numerator&.public_send(:"to_#{method_name}", options)}"
     end
 
     def element_name
       dim_instance.processed_keys.first
     end
+
+    def msup_tag(value, options)
+      mathml = power_numerator.to_mathml(options)
+      msup = ::Mml::V4::Msup.new(
+        mrow_value: [::Mml::V4::Mrow.new(mi_value: [value])]
+      )
+      [mathml].flatten.each do |record|
+        record_values = msup.public_send("#{record[:method_name]}_value") || []
+        record_values += [record[:value]]
+        msup.public_send("#{record[:method_name]}_value=", record_values)
+      end
+      msup
+    end
   end
 end

data/lib/unitsml/errors/base_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Unitsml
+  module Errors
+    class BaseError < StandardError
+    end
+  end
+end

data/lib/unitsml/errors/plurimath_load_error.rb

@@ -2,7 +2,7 @@
 
 module Unitsml
   module Errors
-    class PlurimathLoadError < Unitsml::Error
+    class PlurimathLoadError < Unitsml::Errors::BaseError
       def to_s
         <<~MESSAGE
           [unitsml] Error: Failed to require 'plurimath'.

data/lib/unitsml/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Unitsml
+  module Errors
+    autoload :BaseError, 'unitsml/errors/base_error'
+    autoload :PlurimathLoadError, 'unitsml/errors/plurimath_load_error'
+  end
+end

data/lib/unitsml/extender.rb

@@ -8,22 +8,22 @@ module Unitsml
       @symbol = symbol
     end
 
-    def ==(object)
-      self.class == object.class &&
-        symbol == object&.symbol
+    def ==(other)
+      self.class == other.class &&
+        symbol == other&.symbol
     end
 
     def to_mathml(options)
-      rspace = "thickmathspace" if options[:multiplier] == :space
-      extender = multiplier(options[:multiplier] || "⋅", unicode: true)
+      rspace = 'thickmathspace' if options[:multiplier] == :space
+      extender = multiplier(options[:multiplier] || '⋅', unicode: true)
       {
         method_name: :mo,
-        value: ::Mml::Mo.new(value: extender, rspace: rspace),
+        value: ::Mml::V4::Mo.new(value: extender, rspace: rspace)
       }
     end
 
     def to_latex(options)
-      multiplier(options[:multiplier] || "/")
+      multiplier(options[:multiplier] || '/')
     end
 
     def to_asciimath(options)
@@ -31,12 +31,11 @@ module Unitsml
     end
 
     def to_html(options)
-      multiplier(options[:multiplier] || "⋅", unicode: true, html: true)
+      multiplier(options[:multiplier] || '⋅', unicode: true, html: true)
     end
 
     def to_unicode(options)
-      extender = options[:multiplier] ||
-                   symbol == "*" ? "·" : symbol
+      extender = options[:multiplier] || unicode_extender
       multiplier(extender)
     end
 
@@ -45,16 +44,22 @@ module Unitsml
     def multiplier(extender, unicode: false, html: false)
       case extender
       when :space
-        if html
-          " "
-        else
-          unicode ? "⁢" : " "
-        end
+        space_extender(html, unicode)
       when :nospace
-        unicode ? "⁢" : ""
+        unicode ? '⁢' : ''
       else
         unicode ? Utility.string_to_html_entity(extender) : extender
       end
     end
+
+    def space_extender(html, unicode)
+      return ' ' if html
+
+      unicode ? '⁢' : ' '
+    end
+
+    def unicode_extender
+      symbol == '*' ? '·' : symbol
+    end
   end
 end

data/lib/unitsml/fenced.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Unitsml
+  class Fenced
+    include FencedNumeric
+
+    attr_reader :open_paren, :value, :close_paren
+
+    def initialize(open_paren, value, close_paren)
+      @open_paren = open_paren
+      @value = value
+      @close_paren = close_paren
+    end
+
+    def ==(other)
+      self.class == other.class &&
+        open_paren == other&.open_paren &&
+        value == other&.value &&
+        close_paren == other&.close_paren
+    end
+
+    def to_asciimath(options = {})
+      fenced_conversion_for(lang: :asciimath, options: options)
+    end
+
+    def to_latex(options = {})
+      fenced_conversion_for(lang: :latex, options: options)
+    end
+
+    def to_mathml(options = {})
+      mathml = value.to_mathml(options)
+      return mathml unless options[:explicit_parenthesis]
+
+      fenced = ::Mml::V4::Mrow.new(mo_value: [::Mml::V4::Mo.new(value: open_paren)])
+      fenced.ordered = true
+      fenced.element_order ||= [xml_order_element('mo')]
+      [mathml].flatten.each { |record| add_math_element(fenced, record) }
+      fenced.mo_value << ::Mml::V4::Mo.new(value: close_paren)
+      fenced.element_order << xml_order_element('mo')
+      { method_name: :mrow, value: fenced }
+    end
+
+    def negative?
+      value.negative?
+    end
+
+    def update_negative_sign
+      value.update_negative_sign
+    end
+
+    def float_to_display
+      value.float_to_display
+    end
+
+    def raw_value
+      value.raw_value
+    end
+
+    def to_html(options = {})
+      fenced_conversion_for(lang: :html, options: options)
+    end
+
+    def to_unicode(options = {})
+      fenced_conversion_for(lang: :unicode, options: options)
+    end
+
+    def dimensions_extraction
+      case value
+      when Dimension
+        value
+      when Formula, Fenced
+        value.dimensions_extraction
+      end
+    end
+
+    private
+
+    def add_math_element(instance, child_hash)
+      method_name = child_hash[:method_name]
+      method_value = instance.public_send(:"#{method_name}_value") || []
+      method_value += Array(child_hash[:value])
+      instance.public_send(:"#{method_name}_value=", method_value)
+      instance.element_order << xml_order_element(method_name.to_s)
+    end
+
+    def xml_order_element(tag_name)
+      Lutaml::Xml::Element.new('Element', tag_name)
+    end
+
+    def fenced_conversion_for(lang:, options:)
+      lang_value = value.send(:"to_#{lang}", options)
+      return lang_value unless options[:explicit_parenthesis]
+
+      "#{open_paren}#{lang_value}#{close_paren}"
+    end
+  end
+end

data/lib/unitsml/fenced_numeric.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Unitsml
+  module FencedNumeric
+    def to_i
+      value.to_i
+    end
+
+    def to_f
+      value.to_f
+    end
+  end
+end

data/lib/unitsml/formula.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require "mml"
-require "htmlentities"
-require "unitsml/utility"
+require 'mml'
+require 'htmlentities'
 
 module Unitsml
   class Formula
@@ -20,25 +19,25 @@ module Unitsml
       @norm_text = norm_text
     end
 
-    def ==(object)
-      self.class == object.class &&
-        value == object&.value &&
-        explicit_value == object&.explicit_value &&
-        root == object.root
+    def ==(other)
+      self.class == other.class &&
+        value == other&.value &&
+        explicit_value == other&.explicit_value &&
+        root == other.root
     end
 
     def to_mathml(options = {})
       if root
-        update_options(options)
+        options = update_options(options)
         nullify_mml_models if plurimath_available?
-        math = ::Mml::MathWithNamespace.new(display: "block")
+        math = ::Mml::V4::Math.new(display: 'block')
         math.ordered = true
         math.element_order ||= []
         value.each { |instance| process_value(math, instance.to_mathml(options)) }
-
-        generated_math = math.to_xml.gsub(/&amp;(.*?)(?=<\/)/, '&\1')
+        generated_math = math.to_xml.gsub(%r{&amp;(.*?)(?=</)}, '&\1')
         reset_mml_models if plurimath_available?
-        generated_math
+
+        generated_math.force_encoding('UTF-8')
       else
         value.map { |obj| obj.to_mathml(options) }
       end
@@ -61,7 +60,7 @@ module Unitsml
     end
 
     def to_xml(options = {})
-      update_options(options)
+      options = update_options(options)
       if (dimensions_array = extract_dimensions(value)).any?
         dimensions(sort_dims(dimensions_array), options)
       elsif @orig_text.match(/-$/)
@@ -79,18 +78,29 @@ module Unitsml
       Plurimath::Math.parse(to_mathml(options), :mathml)
     end
 
+    def dimensions_extraction
+      extract_dimensions(value)
+    end
+
     private
 
     def extract_dimensions(formula)
       formula.each_with_object([]) do |term, dimensions|
-        if term.is_a?(Dimension)
+        case term
+        when Dimension
           dimensions << term
-        elsif term.is_a?(Sqrt) && term.value.is_a?(Dimension)
-          sqrt_term = term.value.dup
-          sqrt_term.power_numerator = "0.5"
-          dimensions << sqrt_term
-        elsif term.is_a?(Formula)
+        when Sqrt
+          if term.value.is_a?(Dimension)
+            sqrt_term = term.value.dup
+            sqrt_term.power_numerator = Number.new('0.5')
+            dimensions << sqrt_term
+          elsif term.value.is_a?(Fenced)
+            dimensions.concat(Array(term.value.dimensions_extraction))
+          end
+        when Formula
           dimensions.concat(extract_dimensions(term.value))
+        when Fenced
+          dimensions.concat(Array(term.dimensions_extraction))
         end
       end
     end
@@ -106,26 +116,28 @@ module Unitsml
           next unless term.value.is_a?(Unit)
 
           units_arr << term.value
+        when Fenced
+          units_arr.concat(extract_units([term.value]))
         end
       end
     end
 
     def units(options)
       all_units = extract_units(value)
-      norm_text = Utility.postprocess_normtext(all_units)
+      norm_text = all_units.map(&:xml_postprocess_name).join('*')
       dims = Utility.units2dimensions(extract_units(value))
       [
         Utility.unit(all_units, self, dims, norm_text, explicit_value&.dig(:name), options),
         Utility.prefixes(all_units, options),
         *unique_dimensions(dims, norm_text),
-        Utility.quantity(norm_text, explicit_value&.dig(:quantity)),
+        Utility.quantity(norm_text, explicit_value&.dig(:quantity))
       ].join
     end
 
     def unique_dimensions(dims, norm_text)
       [
         Utility.dimension(norm_text),
-        Utility.dimension_components(dims),
+        Utility.dimension_components(dims)
       ].uniq
     end
 
@@ -133,31 +145,31 @@ module Unitsml
       dim_id = dims.map(&:generate_id).join
       attributes = { id: "D_#{dim_id}" }
       dims.each { |dim| attributes.merge!(dim.xml_instances_hash(options)) }
-      Model::Dimension.new(attributes).to_xml
+      Model::Dimension.new(attributes).to_xml.force_encoding('UTF-8')
     end
 
     def sort_dims(values)
-      dims_hash = Utility::Dim2D
+      dims_hash = Utility::DIM2D
       values.sort do |first, second|
         dims_hash.dig(first.dimension_name, :order) <=> dims_hash.dig(second.dimension_name, :order)
       end
     end
 
     def prefixes(options)
-      norm_text = @norm_text&.split("-")&.first
-      prefix_object = Unit.new("", prefix: Prefix.new(norm_text))
+      norm_text = @norm_text&.split('-')&.first
+      prefix_object = Unit.new('', prefix: Prefix.new(norm_text))
       [
         Utility.prefixes([prefix_object], options),
         Utility.dimension(norm_text),
-        Utility.quantity(norm_text, explicit_value&.dig(:quantity)),
+        Utility.quantity(norm_text, explicit_value&.dig(:quantity))
       ].join
     end
 
     def ensure_plurimath_defined!
       return if plurimath_available?
 
-      require "plurimath"
-    rescue LoadError => e
+      require 'plurimath'
+    rescue LoadError
       raise Errors::PlurimathLoadError
     end
 
@@ -166,7 +178,7 @@ module Unitsml
       method_value = math_instance.public_send(:"#{method_name}_value") || []
       method_value += Array(child_hash[:value])
       math_instance.public_send(:"#{method_name}_value=", method_value)
-      math_instance.element_order << Lutaml::Model::Xml::Element.new("Element", method_name.to_s)
+      math_instance.element_order << Lutaml::Xml::Element.new('Element', method_name.to_s)
     end
 
     def plurimath_available?
@@ -180,7 +192,7 @@ module Unitsml
     end
 
     def reset_mml_models
-      ::Mml::Configuration.custom_models = Plurimath::Mathml::Parser::CONFIGURATION
+      ::Mml::V4::Configuration.custom_models = Plurimath::Mathml::Parser::CONFIGURATION
     end
 
     def process_value(math, mathml_instances)
@@ -196,7 +208,8 @@ module Unitsml
       return options unless root
 
       multiplier = options[:multiplier] || explicit_value&.dig(:multiplier)
-      options.merge(multiplier: multiplier).compact
+      explicit_parenthesis = options.key?(:explicit_parenthesis) ? options[:explicit_parenthesis] : true
+      options.merge(multiplier: multiplier, explicit_parenthesis: explicit_parenthesis).compact
     end
   end
 end