unitsml 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3125feede7c0e09e2760c586f23b5faed651a41cd69e6a515b37628dcbfb6461
-  data.tar.gz: 834148b38b404bff32cda0ba16c948f5a505fe4f217cbc2c5815ce3da00f25b9
+  metadata.gz: 595f12d3478d434cc3c1ef1c1f1a4098b76b58fa7f0d278161303962b464c62c
+  data.tar.gz: 1a506fc8ee2ba7ce2dadfe29126c2117381cd0cd178288ce17076b542f2f2c1b
 SHA512:
-  metadata.gz: 1128ead5ecc9efa1fdfa66aa2edcb53a644384d78d4702079e9f00ce1da9ac9eb9167f21de63779ef25bc41ad72484cc75839591acc8c0ff115a9e1cb7e10214
-  data.tar.gz: c69cdf9204c9dcf431c605ac0686cba8b7e1f7c36c5263b9086b2763812e4745da29636e2f5b63b320ec6d22749cb159c8e71c84bff6675db95ea926ed15e1b6
+  metadata.gz: 4cd31af2b06a97774ac9c4ff957c76d4e704672d47b6477eb97145a5164afa1bc41b856fe35661adde71b96295038897c4ff6549af9f0311448d3ec2545a5457
+  data.tar.gz: 6e44d3fc983c0cd348529f8061677d4f0d76d586372c00b96530955d231982a125c15b7e3f93893f2183ca4cca98a11f69c37ec7a89884b1fb4c4a4e6e1a0ff4

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2021-2025, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/docs/README.adoc

@@ -1,6 +1,175 @@
-= unitsml-ruby
+= UnitsML in Ruby
+
+https://github.com/unitsml/unitsml-ruby[image:https://img.shields.io/github/stars/unitsml/unitsml-ruby.svg?style=social[GitHub Stars]]
+https://github.com/unitsml/unitsml-ruby[image:https://img.shields.io/github/forks/unitsml/unitsml-ruby.svg?style=social[GitHub Forks]]
+image:https://img.shields.io/github/license/unitsml/unitsml-ruby.svg[License]
+image:https://img.shields.io/github/actions/workflow/status/unitsml/unitsml-ruby/rake.yml?branch=main[Build Status]
+image:https://img.shields.io/gem/v/unitsml.svg[RubyGems Version]
+
+== Purpose
+
+UnitsML is a markup language for representing units of measurement in a
+machine-readable format.
+
+It is designed to be used in various applications, including scientific
+computing, data analysis, and engineering.
+
+The UnitsML Ruby library provides the following components:
+
+XML syntax for:
+
+* representing units and quantity information
+Composite units
+
+* Parser for the UnitsML  parser - Parses UnitsML expressions.
+* Unit Converter - Converts units between formats.
+* Formatter - Formats units for display in various formats.
+
+
+The UnitsML Ruby library is a gem for parsing, manipulating, and converting unit expressions based on the Units Markup Language (UnitsML) specification. This library provides functionality to handle units of measurement in a standardized way across different formats.
+
+
+== Structure
+
+The UnitsML Ruby library consists of several key components:
+
+* Parser: Parses string expressions into structured data
+* Transform: Transforms parsed data into domain objects
+* Formula: Represents compound unit expressions
+* Unit: Represents individual units
+* Prefix: Represents unit prefixes (k, m, μ, etc.)
+* Dimension: Represents physical dimensions
+
+The library also includes the full https://github.com/unitsml/unitsdb[UnitsDB]
+units database, which contains standard units, prefixes, and dimensions.
+
+
+== Usage
+
+=== AsciiUnits
+
+The UnitsML Ruby library supports AsciiUnits, a text-based syntax for
+representing units of measurement in a compact and human-readable format.
+
+The UnitsML Ruby library supports all available units defined in the official
+UnitsDB database.
+
+=== Basic units
+
+A basic unit is a unit that has an entry in the UnitsDB database
+with a unique identifier.
+
+Basic units are represented in the library as `Unitsml::Unit` objects.
+
+[source,ruby]
+----
+require 'unitsml'
+unit = Unitsml.parse("m") # Parse a unit expression
+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"/>
+  <UnitName xml:lang="en">meter</UnitName>
+  <UnitSymbol type="HTML">m</UnitSymbol>
+  <UnitSymbol type="MathMl">
+    <math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
+      <mi mathvariant="normal">m</mi>
+    </math>
+  </UnitSymbol>
+</Unit>
+
+<Dimension xmlns="https://schema.unitsml.org/unitsml/1.0" xml:id="NISTd1">
+  <Length symbol="L" powerNumerator="1"/>
+</Dimension>
+----
+
+
+=== Prefixed units
+
+A prefixed unit is a unit that has a prefix (like kilo, milli, micro, etc.)
+that modifies its value.
+
+Prefixed units are represented in the library as `Unitsml::Prefix` objects.
+
+The library supports the full range of prefixes defined in the UnitsDB database.
+
+[source,ruby]
+----
+require 'unitsml'
+unit = Unitsml.parse("um") # Parse a unit expression
+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"/>
+  <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">
+  <mi mathvariant='normal'>µm</mi>
+</math>
+</UnitSymbol>
+  <RootUnits>
+    <EnumeratedRootUnit unit="meter" prefix="u"/>
+  </RootUnits>
+</Unit>
+
+<Prefix xmlns="https://schema.unitsml.org/unitsml/1.0" prefixBase="10" prefixPower="-6" xml:id="NISTp10_-6">
+  <PrefixName xml:lang="en">micro</PrefixName>
+  <PrefixSymbol type="ASCII">u</PrefixSymbol>
+  <PrefixSymbol type="unicode">μ</PrefixSymbol>
+  <PrefixSymbol type="LaTeX">$mu$</PrefixSymbol>
+  <PrefixSymbol type="HTML">&micro;</PrefixSymbol>
+</Prefix>
+
+<Dimension xmlns="https://schema.unitsml.org/unitsml/1.0" xml:id="NISTd1">
+  <Length symbol="L" powerNumerator="1"/>
+</Dimension>
+----
+
+Prefixed units: mm, kg, μm
+
+
+=== Creating composite units
+
+A composite unit is a unit that is derived from two or more basic units
+conjoined by multiplication or division.
+
+Composite units are created using the `Unitsml.parse` method.
+
+Compound units with operations: kg*s^-2
+Units with powers: C^3
+Square roots: sqrt(Hz)
+Units with prefixes: m/s, m^2/s^2
+
+
+=== Format representation
+
+The library supports representation of UnitsML-encoded units in various formats.
+
+These formats include:
+
+* MathML
+* LaTeX
+* AsciiMath
+* HTML
+* Unicode
+* XML (in UnitsML)
+
+Units can be converted to multiple formats as follows:
+
+[source,ruby]
+----
+unit = Unitsml.parse("m/s")
+unit.to_mathml     # MathML representation
+unit.to_latex      # LaTeX representation
+unit.to_asciimath  # AsciiMath representation
+unit.to_html       # HTML representation
+unit.to_unicode    # Unicode representation
+unit.to_xml        # XML (in UnitsML) representation
+----
+
 
-Gem-wrapper for unitsdb
 
 == Installation
 
@@ -13,42 +182,127 @@ gem 'unitsml'
 
 And then execute:
 
-[source,sh]
+[source,console]
 ----
 $ bundle install
 ----
 
-Or install it yourself as:
+Or install it yourself with:
 
-[source,sh]
+[source,console]
 ----
 $ gem install unitsml
 ----
 
 == Usage
 
-=== Unit lookup
+*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
 
 [source,ruby]
 ----
-Unitsml.find_unit(ascii: 'mL') # Unitsml::Unit (with unit attributes)
+require 'unitsml'
+
+Unitsml.parse("mm*kg/s^2") # Parse a unit expression
+----
+
+=== Format Conversions
+
+Units can be converted to different formats:
+
+[source,ruby]
+----
+unit = Unitsml.parse("m/s") # Create a unit example
+
+# Convert to different formats
+unit.to_mathml
+unit.to_latex
+unit.to_asciimath
+unit.to_html
+unit.to_unicode
+unit.to_xml
+----
+
+=== Extenders
+
+An `Extender` is the symbol between units (like multiplication or division):
+
+[[example]]
+[source, ruby]
+----
+formula = Unitsml.parse("m*m") # the '*' is the extender
+formula.to_mathml
+----
+
+[source,xml]
+----
+<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
+  <mi mathvariant="normal">m</mi>
+  <mo>&#x22c5;</mo>
+  <mi mathvariant="normal">m</mi>
+</math>
+----
+
+The output of extenders can be customized by passing the `multiplier` argument:
+
+[[example]]
+
+[source, ruby]
 ----
+formula = Unitsml.parse("m/m")
+formula.to_asciimath(multiplier: "·") # the '·' is the extender for the output
+> "m·m^-1"
+----
+
+The `multiplier` argument is supported in all supported conversions.
+
+==== Supported multipliers
+
+The `multiplier` argument supports following types of input:
+
+* `:space` - Represents multiplication with a space
+* `:nospace` - Represents multiplication with no space
+* Custom symbols - Like "·", "/", "*", "aA", "12", etc.
+
+=== Plurimath support
+
+This gem requires the *Plurimath* gem to provide `to_plurimath` method
+functionality. You need to explicitly install it, please follow the installtion
+instructions in the
+https://github.com/plurimath/plurimath?tab=readme-ov-file#installation[*Plurimath*]
+repository.
 
 == Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake 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.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to https://rubygems.org[rubygems.org].
+=== Submodules
 
-== Contributing
+When developing or contributing to *UnitsML Ruby*, you'll need to ensure the
+submodules are available. After cloning the repository, verify that the
+submodules exist in the directory.
 
-Bug reports and pull requests are welcome on GitHub at `https://github.com/unitsml/unitsml-ruby`. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the https://github.com/unitsml/unitsml-ruby/blob/master/docs/CODE_OF_CONDUCT.adoc[code of conduct].
+If not, populate the submodules by running:
 
+[source,console]
+----
+$ git submodule update --init --recursive
+----
 
-== License
+*`unitsdb`* is the only submodule required in this gem for now.
 
-The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT license].
 
 == Code of Conduct
 
-Everyone interacting in the Unitsml project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the https://github.com/unitsml/unitsml-ruby/blob/master/docs/CODE_OF_CONDUCT.adoc[code of conduct].
+Everyone interacting in the Unitsml project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the
+https://github.com/unitsml/unitsml-ruby/blob/master/docs/CODE_OF_CONDUCT.adoc[code of conduct].
+
+
+== License and Copyright
+
+This project is licensed under the BSD 2-clause License.
+
+See the link:LICENSE.md[] file for details.
+
+Copyright Ribose.

data/lib/unitsml/formula.rb

@@ -3,6 +3,7 @@
 require "mml"
 require "htmlentities"
 require "unitsml/utility"
+
 module Unitsml
   class Formula
     attr_accessor :value, :explicit_value, :root
@@ -33,17 +34,11 @@ module Unitsml
         math = ::Mml::MathWithNamespace.new(display: "block")
         math.ordered = true
         math.element_order ||= []
-        value.each do |instance|
-          processed_instance = instance.to_mathml(options)
-          case processed_instance
-          when Array
-            processed_instance.each { |hash| add_math_element(math, hash) }
-          when Hash
-            add_math_element(math, processed_instance)
-          end
-        end
+        value.each { |instance| process_value(math, instance.to_mathml(options)) }
+
+        generated_math = math.to_xml.gsub(/&amp;(.*?)(?=<\/)/, '&\1')
         reset_mml_models if plurimath_available?
-        math.to_xml.gsub(/&amp;(.*?)(?=<\/)/, '&\1')
+        generated_math
       else
         value.map { |obj| obj.to_mathml(options) }
       end
@@ -171,11 +166,13 @@ 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::XmlAdapter::Element.new("Element", method_name.to_s)
+      math_instance.element_order << Lutaml::Model::Xml::Element.new("Element", method_name.to_s)
     end
 
     def plurimath_available?
-      Object.const_defined?(:Plurimath)
+      Object.const_defined?(:Plurimath) &&
+        Plurimath.const_defined?(:Math) &&
+        Plurimath.const_defined?(:Mathml)
     end
 
     def nullify_mml_models
@@ -186,6 +183,15 @@ module Unitsml
       ::Mml::Configuration.custom_models = Plurimath::Mathml::Parser::CONFIGURATION
     end
 
+    def process_value(math, mathml_instances)
+      case mathml_instances
+      when Array
+        mathml_instances.each { |hash| process_value(math, hash) }
+      when Hash
+        add_math_element(math, mathml_instances)
+      end
+    end
+
     def update_options(options)
       return options unless root
 

data/lib/unitsml/utility.rb

@@ -234,7 +234,7 @@ module Unitsml
         uniq_prefixes = units.map { |unit| unit.prefix }.compact.uniq {|d| d.prefix_name }
         uniq_prefixes.map do |prefix|
           prefix_attrs = { prefix_base: prefix&.base, prefix_power: prefix&.power, id: prefix&.id }
-          type_and_methods = { ASCII: :to_asciimath, unicode: :to_unicode, LaTex: :to_latex, HTML: :to_html }
+          type_and_methods = { ASCII: :to_asciimath, unicode: :to_unicode, LaTeX: :to_latex, HTML: :to_html }
           prefix_attrs[:name] = Model::Prefixes::Name.new(content: prefix&.name)
           prefix_attrs[:symbol] = type_and_methods.map do |type, method_name|
             Model::Prefixes::Symbol.new(

data/lib/unitsml/version.rb

@@ -1,3 +1,3 @@
 module Unitsml
-  VERSION = "0.4.3"
+  VERSION = "0.4.5"
 end

data/lib/unitsml.rb

@@ -36,3 +36,8 @@ Unitsdb::Config.models = {
   dimension_quantity: Unitsml::Unitsdb::DimensionQuantity,
 }
 require "unitsdb"
+
+DEFAULT_XML_ADAPTER = RUBY_ENGINE == "opal" ? :oga :  :ox
+Lutaml::Model::Config.xml_adapter_type = DEFAULT_XML_ADAPTER
+# TODO: Remove Moxml adapter assignment when Lutaml::Model utilizes Moxml completely
+Moxml::Config.default_adapter = DEFAULT_ADAPTER

data/unitsml.gemspec

@@ -1,34 +1,34 @@
 require_relative 'lib/unitsml/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "unitsml"
+  spec.name          = 'unitsml'
   spec.version       = Unitsml::VERSION
-  spec.authors       = ["Ribose Inc."]
-  spec.email         = ["open.source@ribose.com"]
+  spec.authors       = ['Ribose Inc.']
+  spec.email         = ['open.source@ribose.com']
 
-  spec.summary       = "Gem-wrapper for working with unitsdb"
-  spec.description   = "Gem-wrapper for working with unitsdb"
+  spec.summary       = 'UnitsML in Ruby'
+  spec.description   = 'Library to work with UnitsML in Ruby'
 
-  spec.homepage      = "https://github.com/unitsml/unitsml-ruby"
-  spec.license       = "BSD-2-Clause"
+  spec.homepage      = 'https://github.com/unitsml/unitsml-ruby'
+  spec.license       = 'BSD-2-Clause'
 
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
 
-  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata['homepage_uri'] = spec.homepage
 
   # 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
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.files += Dir.glob('unitsdb/**/*')
 
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib", "unitsdb/**/*.yaml"]
+  spec.require_paths = ['lib', 'unitsdb/**/*.yaml']
 
-  spec.add_dependency "htmlentities"
-  spec.add_dependency "mml"
-  spec.add_dependency "parslet"
-  spec.add_dependency "unitsdb"
+  spec.add_dependency 'htmlentities'
+  spec.add_dependency 'mml'
+  spec.add_dependency 'parslet'
+  spec.add_dependency 'unitsdb'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unitsml
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 2025-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: htmlentities
@@ -66,7 +66,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Gem-wrapper for working with unitsdb
+description: Library to work with UnitsML in Ruby
 email:
 - open.source@ribose.com
 executables: []
@@ -81,7 +81,7 @@ files:
 - ".gitmodules"
 - ".rspec"
 - Gemfile
-- LICENSE.txt
+- LICENSE.md
 - Rakefile
 - bin/console
 - bin/setup
@@ -163,5 +163,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Gem-wrapper for working with unitsdb
+summary: UnitsML in Ruby
 test_files: []

data/LICENSE.txt

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2021 Тараскин Михаил
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.