unitsml 0.4.6 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa7225e4922a972e29d438320d23fce921f62c550553a9eb24bb6bb501b7eb22
-  data.tar.gz: f96fd6719ff152b0d853c20e80a7bfa2ce389715d49a90adf282cc0dcb5781c7
+  metadata.gz: edaa6904f430d793ab777f84d10c89925006c07654d769932ac17eb34e826e93
+  data.tar.gz: d5883a47de366c89c8e3d603aa9bfc99f307e94d73285bddcec426a34f6e963d
 SHA512:
-  metadata.gz: 1b5a62abd80dd0c28a2168e5318f0bb80c68a5e894ed90f62097e3a9b9ad742c450c7f4e1815e8171d414cc2795ebba54d444a2929a7207f021da2594f3f232e
-  data.tar.gz: c73a55849dd8ecf6c3534ccb54d099fbbfd5eb683359f7b4c094df13b9372cdbc60969f7d8ec1bb9829646ee33be564abc45c7b5a924fa97dcb42d29e1747808
+  metadata.gz: 46d962a6cb805be3f839125dc3bbab75913e0bac277800f808908f6de81d117c54fbd163418ef35b546834b8d0d9640290664d2ceb9658aea6638c6e86b29a5d
+  data.tar.gz: 7d628fe1043c6dfc29b7e03844f1d2fbff50078afe344d0089682417dd441504aac9792dc6ff16cf7f340e4899e5d963375d341d7c553b0681e81d428022648b

data/docs/README.adoc

@@ -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

@@ -20,7 +20,7 @@ module Unitsml
     end
 
     def dim_symbols
-      dim_instance.send(@dim.processed_keys.last).dim_symbols.first
+      dim_instance.send(@dim.processed_keys.last).symbols.first
     end
 
     def to_mathml(_)

data/lib/unitsml/fenced.rb

@@ -0,0 +1,77 @@
+module Unitsml
+  class Fenced
+    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 ==(object)
+      self.class == object.class &&
+        open_paren == object&.open_paren &&
+        value == object&.value &&
+        close_paren == object&.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::Mrow.new(mo_value: [::Mml::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::Mo.new(value: close_paren)
+      fenced.element_order << xml_order_element("mo")
+      { method_name: :mrow, value: fenced }
+    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::Model::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/formula.rb

@@ -29,7 +29,7 @@ module Unitsml
 
     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.ordered = true
@@ -61,7 +61,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 +79,28 @@ 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)
           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?(Sqrt)
+          if term.value.is_a?(Dimension)
+            sqrt_term = term.value.dup
+            sqrt_term.power_numerator = "0.5"
+            dimensions << sqrt_term
+          elsif term.value.is_a?(Fenced)
+            dimensions.concat(Array(term.value.dimensions_extraction))
+          end
         elsif term.is_a?(Formula)
           dimensions.concat(extract_dimensions(term.value))
+        elsif term.is_a?(Fenced)
+          dimensions.concat(Array(term.dimensions_extraction))
         end
       end
     end
@@ -106,13 +116,15 @@ 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),
@@ -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

data/lib/unitsml/intermediate_exp_rules.rb

@@ -0,0 +1,35 @@
+module Unitsml
+  module IntermediateExpRules
+    include Parslet
+
+    # Rules for slashed number
+    rule(:slashed_number_int_exp) { slashed_number | (str("(") >> slashed_number >> str(")")) }
+
+    # Rules for prefixes_units
+    rule(:prefixes_units_int_exp) { prefixes_units | (str("(") >> prefixes_units_named_exp.as(:intermediate_exp) >> str(")") >> extended_prefixed_units.maybe) }
+    rule(:extended_prefixed_units) { extender >> prefixes_units_int_exp.as(:sequence) }
+    rule(:prefixes_units_named_exp) do
+      prefixes_units |
+        ((str("(").as(:open_parenthesis) >> prefixes_units_int_exp.as(:int_exp) >> str(")").as(:close_parenthesis)).as(:intermediate_exp) >> extended_prefixed_units.maybe)
+    end
+
+    # Rules for dimension_rules
+    rule(:dimension_rules_int_exp) { dimension_rules | (str("(") >> dimension_rules_named_exp.as(:intermediate_exp) >> str(")") >> extended_dimension_rules.maybe) }
+    rule(:extended_dimension_rules) { extender >> dimension_rules_int_exp.as(:sequence) }
+    rule(:dimension_rules_named_exp) do
+      dimension_rules |
+        ((str("(").as(:open_parenthesis) >> dimension_rules_int_exp.as(:int_exp) >> str(")").as(:close_parenthesis)).as(:intermediate_exp) >> extended_dimension_rules.maybe)
+    end
+
+    # Rules for dimensions
+    rule(:sqrt_dimensions) { str("sqrt(") >> dimensions_int_exp.as(:sqrt) >> str(")") }
+    rule(:powered_dimensions) { dimensions >> power.maybe }
+    rule(:dimensions_int_exp) { powered_dimensions | (str("(") >> dimensions_named_exp.as(:intermediate_exp) >> str(")")) }
+    rule(:dimensions_named_exp) { powered_dimensions | (str("(").as(:open_parenthesis) >> dimensions_int_exp.as(:int_exp) >> str(")").as(:close_parenthesis)) }
+
+    # Rules for sequence
+    rule(:sqrt_sequence) { str("sqrt(") >> sequence_int_exp.as(:sqrt) >> str(")") }
+    rule(:sequence_int_exp) { sequence | (str("(") >> sequence_named_exp.as(:intermediate_exp)>> str(")")) }
+    rule(:sequence_named_exp) { sequence | (str("(").as(:open_parenthesis) >> sequence_int_exp.as(:int_exp) >> str(")").as(:close_parenthesis)) }
+  end
+end

data/lib/unitsml/parse.rb

@@ -2,9 +2,12 @@
 
 require "parslet"
 require "unitsml/unitsdb"
+require_relative "intermediate_exp_rules"
 module Unitsml
   class Parse < Parslet::Parser
-    rule(:power)  { str("^") >> intermediate_exp(slashed_number) }
+    include IntermediateExpRules
+
+    rule(:power)  { str("^") >> slashed_number_int_exp }
     rule(:hyphen) { str("-") }
     rule(:number) { hyphen.maybe >> match(/[0-9]/).repeat(1) }
 
@@ -32,24 +35,24 @@ module Unitsml
     end
 
     rule(:prefixes_units) do
-      (sqrt(sequence) >> extend_exp(prefixes_units)) |
-        (str("1").as(:units) >> extend_exp(prefixes_units)) |
-        (unit_and_power >> extender >> intermediate_exp(prefixes_units).as(:sequence)) |
-        unit_and_power |
-        (single_letter_prefixes >> unit_and_power >> extender >> intermediate_exp(prefixes_units).as(:sequence)) |
-        (single_letter_prefixes >> unit_and_power) |
-        (double_letter_prefixes >> unit_and_power >> extender >> intermediate_exp(prefixes_units).as(:sequence)) |
-        (double_letter_prefixes >> unit_and_power)
+      (sqrt_sequence >> extended_prefixed_units.maybe) |
+        (str("1").as(:units) >> extended_prefixed_units.maybe) |
+        (unit_and_power >> extended_prefixed_units) |
+        unit_and_power >> (str(")").present? | any.absent?) |
+        (double_letter_prefixes >> unit_and_power >> extended_prefixed_units) |
+        (double_letter_prefixes >> unit_and_power) |
+        (single_letter_prefixes >> unit_and_power >> extended_prefixed_units) |
+        (single_letter_prefixes >> unit_and_power)
     end
 
     rule(:dimension_rules) do
-      (sqrt(intermediate_exp(dimensions >> power.maybe)) >> extend_exp(dimension_rules)) |
-        (dimensions >> power.maybe >> extend_exp(dimension_rules))
+      (sqrt_dimensions >> extended_dimension_rules.maybe) |
+        (powered_dimensions >> extended_dimension_rules.maybe)
     end
 
     rule(:expression) do
-      intermediate_exp(prefixes_units) |
-        intermediate_exp(dimension_rules) |
+      prefixes_units_int_exp |
+        dimension_rules_int_exp |
         single_letter_prefixes >> hyphen |
         double_letter_prefixes >> hyphen
     end
@@ -63,17 +66,5 @@ module Unitsml
         expression | str(expr_string).as(file_name.to_sym)
       end
     end
-
-    def sqrt(rule)
-      str("sqrt(") >> rule.as(:sqrt) >> str(")")
-    end
-
-    def extend_exp(rule)
-      (extender >> intermediate_exp(rule).as(:sequence)).maybe
-    end
-
-    def intermediate_exp(rule)
-      rule | (str("(") >> rule >> str(")"))
-    end
   end
 end

data/lib/unitsml/parser.rb

@@ -6,7 +6,7 @@ module Unitsml
 
     def initialize(text)
       @regexp = %r{(quantity|name|symbol|multiplier):\s*}
-      @text = text&.match(/unitsml\((.*)\)/) ? Regexp.last_match[1] : text
+      @text = extract_equation(text)
       @orig_text = @text
       @text = @text.gsub("−", "-")
       post_extras
@@ -15,7 +15,7 @@ module Unitsml
     def parse
       nodes = Parse.new.parse(text)
       transformed = Transform.new.apply(nodes)
-      formula_value = transformed.is_a?(Formula) ? transformed.value : Array(transformed)
+      formula_value = transformed.is_a?(Formula) ? transformed.value : [transformed].flatten
       formula = Formula.new(
         formula_value,
         explicit_value: @extras_hash,
@@ -28,21 +28,28 @@ module Unitsml
       formula
     end
 
-    def update_units_exponents(array, inverse)
+    def update_units_exponents(array, inverse, sqrt = false)
       array.each do |object|
         if object.is_a?(Sqrt)
           object = object.value
-          object.power_numerator = "0.5"
+          if object.respond_to?(:power_numerator)
+            object.power_numerator = "0.5"
+          else
+            update_units_exponents([object], inverse, true)
+          end
         end
 
         case object
         when Unit
+          next object.power_numerator = "0.5" if sqrt
           next unless inverse
 
           exponent = inverse ? "-#{object&.power_numerator || '1'}" : object.power_numerator
           object.power_numerator = exponent&.sub(/^--+/, "")
+        when Dimension then object.power_numerator = "0.5" if sqrt
         when Extender then inverse = !inverse if ["/", "//"].any?(object.symbol)
         when Formula then update_units_exponents(object.value, inverse)
+        when Fenced then update_units_exponents([object.value], inverse, sqrt)
         end
       end
     end
@@ -62,5 +69,13 @@ module Unitsml
       key, _, value = text&.partition(":")
       @extras_hash[key&.to_sym] ||= value&.strip
     end
+
+    private
+
+    def extract_equation(text)
+      return text unless text&.start_with?("unitsml(")
+
+      text.delete_prefix("unitsml(").delete_suffix(")")
+    end
   end
 end

data/lib/unitsml/prefix.rb

@@ -20,21 +20,21 @@ module Unitsml
     end
 
     def id
-      @prefix.id
+      @id ||= prefix_instance.identifiers.find { |prefix| prefix.type == "nist" }&.id
     end
 
     def name
-      prefix_instance.name
+      @name ||= prefix_instance.names.find { |name| name.lang == "en" }.value
     end
 
-    def prefixes_symbols
-      prefix_instance.symbol
+    def prefix_symbols
+      prefix_instance.symbols.last
     end
 
     def to_mathml(_)
       symbol = Utility.string_to_html_entity(
         Utility.html_entity_to_unicode(
-          prefixes_symbols.html
+          prefix_symbols.html
         ),
       )
       return symbol unless only_instance
@@ -43,23 +43,23 @@ module Unitsml
     end
 
     def to_latex(_)
-      prefixes_symbols.latex
+      prefix_symbols.latex
     end
 
     def to_asciimath(_)
-      prefixes_symbols.ascii
+      prefix_symbols.ascii
     end
 
     def to_html(_)
-      prefixes_symbols.html
+      prefix_symbols.html
     end
 
     def to_unicode(_)
-      prefixes_symbols.unicode
+      prefix_symbols.unicode
     end
 
     def symbolid
-      prefixes_symbols.ascii if prefixes_symbols
+      prefix_symbols.ascii if prefix_symbols
     end
 
     def base

data/lib/unitsml/transform.rb

@@ -7,6 +7,7 @@ module Unitsml
     rule(units: simple(:unit))      { Unit.new(unit.to_s) }
     rule(prefixes: simple(:prefix)) { Prefix.new(prefix.to_s) }
     rule(dimensions: simple(:dimension)) { Dimension.new(dimension.to_s) }
+    rule(intermediate_exp: simple(:int_exp)) { int_exp }
 
     rule(units: simple(:unit),
          integer: simple(:integer)) do
@@ -30,6 +31,36 @@ module Unitsml
       Unit.new(unit.to_s, integer.to_s, prefix: prefix_obj)
     end
 
+    rule(open_parenthesis: simple(:open_paren),
+         int_exp: simple(:exp),
+         close_parenthesis: simple(:close_paren)) do
+      Fenced.new(open_paren.to_s, exp, close_paren.to_s)
+    end
+
+    rule(open_parenthesis: simple(:open_paren),
+         int_exp: simple(:exp),
+         close_parenthesis: simple(:close_paren),
+         sequence: sequence(:sequence)) do
+      Formula.new(
+        [
+          Fenced.new(open_paren.to_s, exp, close_paren.to_s),
+          sequence,
+        ],
+      )
+    end
+
+    rule(intermediate_exp: simple(:intermediate_exp),
+         extender: simple(:extender),
+         sequence: simple(:sequence)) do
+      Formula.new(
+        [
+          intermediate_exp,
+          Extender.new(extender.to_s),
+          sequence,
+        ],
+      )
+    end
+
     rule(prefixes: simple(:prefix),
          units: simple(:unit),
          integer: simple(:integer),

data/lib/unitsml/unit.rb

@@ -4,6 +4,8 @@ module Unitsml
   class Unit
     attr_accessor :unit_name, :power_numerator, :prefix
 
+    SI_UNIT_SYSTEM = %w[si_base si_derived_special si_derived_non_special].freeze
+
     def initialize(unit_name,
                    power_numerator = nil,
                    prefix: nil)
@@ -24,7 +26,7 @@ module Unitsml
     end
 
     def unit_symbols
-      unit_instance.unit_symbols.find { |symbol| symbol.id == unit_name }
+      unit_instance.symbols.find { |symbol| symbol.id == unit_name }
     end
 
     def numerator_value(mathml = true)
@@ -89,7 +91,7 @@ module Unitsml
     end
 
     def enumerated_name
-      unit_instance&.unit_name&.first
+      unit_instance.names.find { |name| name.lang == "en" }&.value
     end
 
     def prefix_name
@@ -97,15 +99,35 @@ module Unitsml
     end
 
     def system_type
-      unit_instance.unit_system.type
-    end
-
-    def system_name
-      unit_instance.unit_system.name
+      system_reference&.first&.id
     end
 
     def si_derived_bases
       unit_instance.si_derived_bases
     end
+
+    def xml_postprocess_name
+      "#{prefix_name}#{unit_name}#{display_exp}"
+    end
+
+    def si_system_type?
+      SI_UNIT_SYSTEM.include?(downcase_system_type)
+    end
+
+    def downcase_system_type
+      Lutaml::Model::Utils.snake_case(system_type)
+    end
+
+    private
+
+    def display_exp
+      return unless power_numerator
+
+      "^#{power_numerator}" if power_numerator != "1"
+    end
+
+    def system_reference
+      unit_instance.unit_system_reference
+    end
   end
 end