lutaml-model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 223c53c673e167e5bf85d7eec79a95011e37db1e07849a6a005d935bd5586c0f
+  data.tar.gz: 4adc0dc4bc3d30b15c7901b2b997c3e4ff24ff9d92896020d038e443dda99925
+SHA512:
+  metadata.gz: 34a4d857e96d2955581a6df37c0aff10466edb1eb57293d6a818c62b998ba2244609ac9963d676ff789c0c2e08593296bd96bf7d8c6bd628ff867718e9f8e31a
+  data.tar.gz: a0e0c005f90ce0d029f119f1d2013da1b2ea7d61e8a8f149c46fce3c6bbfea79237d90cb9b8fc4a5eed7ef40939f2b4a35d121ab2be034b04a897103e78b7c0e

data/.github/workflows/main.yml

@@ -0,0 +1,27 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby:
+          - '3.2.2'
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run the default task
+      run: bundle exec rake

data/.github/workflows/rake.yml

@@ -0,0 +1,15 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: rake
+
+on:
+  push:
+    branches: [ master, main ]
+    tags: [ v* ]
+  pull_request:
+
+jobs:
+  rake:
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    secrets:
+      pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      next_version:
+        description: |
+          Next release version. Possible values: x.y.z, major, minor, patch or pre|rc|etc
+        required: true
+        default: 'skip'
+  repository_dispatch:
+    types: [ do-release ]
+
+jobs:
+  release:
+    uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
+    with:
+      next_version: ${{ github.event.inputs.next_version }}
+    secrets:
+      rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
+      pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,12 @@
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+
+# local repo-specific modifications
+# ...
+
+AllCops:
+  TargetRubyVersion: 2.6
+  NewCops: enable
+  Exclude:
+    - 'lib/sts/mapper.rb'
+    - 'vendor/**/*'

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at ronald.tse@ribose.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in lutaml-model.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"

data/README.adoc

@@ -0,0 +1,380 @@
+= LutaML Ruby modeller: `Lutaml::Model`
+
+https://github.com/lutaml/lutaml-model[image:https://img.shields.io/github/stars/lutaml/lutaml-model.svg?style=social[GitHub Stars]]
+https://github.com/lutaml/lutaml-model[image:https://img.shields.io/github/forks/lutaml/lutaml-model.svg?style=social[GitHub Forks]]
+image:https://img.shields.io/github/license/lutaml/lutaml-model.svg[License]
+image:https://img.shields.io/github/actions/workflow/status/lutaml/lutaml-model/test.yml?branch=main[Build Status]
+image:https://img.shields.io/gem/v/lutaml-model.svg[RubyGems Version]
+
+== What is Lutaml::Model
+
+Lutaml::Model is a lightweight library for serializing and deserializing Ruby
+objects to and from various formats such as JSON, XML, YAML, and TOML. It uses
+an adapter pattern to support multiple libraries for each format, providing
+flexibility and extensibility for your data modeling needs.
+
+The name "LutaML" comes from the Latin word "Lutum," which means clay, and "ML"
+for Markup Language. Just as clay can be molded and modeled into beautiful and
+practical end products, the Lutaml::Model gem is used for data modeling,
+allowing you to shape and structure your data into useful forms.
+
+
+
+NOTE: Lutaml::Model is designed to be compatible with the Shale data modeling
+API. Shale is an amazing Ruby data modeller. Lutaml::Model is meant to address
+needs that are not currently addresed by Shale.
+
+== Introduction to Data Modeling
+
+Data modeling is the process of creating a data model for the data to be stored
+in a database or used in an application. It helps in defining the structure,
+relationships, and constraints of the data, making it easier to manage and use.
+
+Lutaml::Model simplifies data modeling in Ruby by allowing you to define models
+with attributes and serialize/deserialize them to/from various formats
+seamlessly.
+
+== Features
+
+* Define models with attributes and types
+* Serialize and deserialize models to/from JSON, XML, YAML, and TOML
+* Support for multiple libraries (e.g., `toml-rb`, `tomlib`)
+* Configurable adapters for different serialization formats
+* Support for collections and default values
+* Custom serialization/deserialization methods
+* XML namespaces and mappings
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'lutaml-model'
+----
+
+And then execute:
+
+[source,shell]
+----
+bundle install
+----
+
+Or install it yourself as:
+
+[source,shell]
+----
+gem install lutaml-model
+----
+
+== Writing a Data Model in Ruby
+
+To define a model, inherit from `Lutaml::Model::Serializable` and use the `attribute` class method to define attributes.
+
+[source,ruby]
+----
+require 'lutaml/model'
+
+class Kiln < Lutaml::Model::Serializable
+  attribute :brand, Lutaml::Model::Type::String
+  attribute :capacity, Lutaml::Model::Type::Integer
+  attribute :temperature, Lutaml::Model::Type::Integer
+end
+----
+
+== Translating a Data Model into Different Serialization Models
+
+Lutaml::Model allows you to translate a data model into various serialization
+formats including XML, JSON, YAML, and TOML.
+
+=== XML: Element, Attribute, Namespaces
+
+Define XML mappings using `map_element`, `map_attribute`, and `map_content`.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, Lutaml::Model::Type::String
+  attribute :value, Lutaml::Model::Type::Integer
+
+  xml do
+    root 'example'
+    map_element 'name', to: :name
+    map_attribute 'value', to: :value
+  end
+end
+----
+
+=== Key Value Data Models: JSON, YAML, TOML
+
+Define key-value data models like JSON, YAML, and TOML using the `map` method.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, Lutaml::Model::Type::String
+  attribute :value, Lutaml::Model::Type::Integer
+
+  json do
+    map 'name', to: :name
+    map 'value', to: :value
+  end
+
+  yaml do
+    map 'name', to: :name
+    map 'value', to: :value
+  end
+
+  toml do
+    map 'name', to: :name
+    map 'value', to: :value
+  end
+end
+----
+
+== Develop Serialization and Deserialization Mappings
+
+Lutaml::Model supports various methods for defining serialization and deserialization mappings.
+
+=== XML (`map_element`, `map_attribute`, `map_content`)
+
+Use `map_element` to map XML elements, `map_attribute` to map XML attributes, and `map_content` to map text content within an XML element.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, Lutaml::Model::Type::String
+  attribute :description, Lutaml::Model::Type::String
+
+  xml do
+    root 'example'
+    map_element 'name', to: :name
+    map_content to: :description
+  end
+end
+----
+
+=== JSON (`map` method)
+
+Use the `map` method to define JSON mappings.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, Lutaml::Model::Type::String
+  attribute :value, Lutaml::Model::Type::Integer
+
+  json do
+    map 'name', to: :name
+    map 'value', to: :value
+  end
+end
+----
+
+=== YAML
+
+Use the `map` method to define YAML mappings.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, Lutaml::Model::Type::String
+  attribute :value, Lutaml::Model::Type::Integer
+
+  yaml do
+    map 'name', to: :name
+    map 'value', to: :value
+  end
+end
+----
+
+=== TOML
+
+Use the `map` method to define TOML mappings.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, Lutaml::Model::Type::String
+  attribute :value, Lutaml::Model::Type::Integer
+
+  toml do
+    map 'name', to: :name
+    map 'value', to: :value
+  end
+end
+----
+
+== Attribute Collections Using the `collection` Option
+
+You can define attributes as collections (arrays or hashes) to store multiple values.
+
+[source,ruby]
+----
+class Studio < Lutaml::Model::Serializable
+  attribute :location, Lutaml::Model::Type::String
+  attribute :potters, Lutaml::Model::Type::String, collection: true
+end
+----
+
+== Attribute Defaults Using the `default` Option
+
+Specify default values for attributes using the `default` option.
+
+[source,ruby]
+----
+class Glaze < Lutaml::Model::Serializable
+  attribute :color, Lutaml::Model::Type::String, default: -> { 'Clear' }
+  attribute :temperature, Lutaml::Model::Type::Integer, default: -> { 1050 }
+end
+----
+
+== Attribute Delegation Using the `delegate` Option
+
+Delegate attribute mappings to nested objects using the `delegate` option.
+
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, Lutaml::Model::Type::String
+  attribute :glaze, Glaze
+
+  json do
+    map 'type', to: :type
+    map 'color', to: :color, delegate: :glaze
+  end
+end
+----
+
+== Attribute Serialization with Custom `from` and `to` Methods
+
+Define custom methods for specific attribute mappings using the `with:` key for each serialization mapping block.
+
+[source,ruby]
+----
+class CustomCeramic < Lutaml::Model::Serializable
+  attribute :name, Lutaml::Model::Type::String
+  attribute :size, Lutaml::Model::Type::Integer
+
+  json do
+    map 'name', to: :name, with: { to: :name_to_json, from: :name_from_json }
+    map 'size', to: :size
+  end
+
+  def name_to_json(model, value)
+    "Masterpiece: #{value}"
+  end
+
+  def name_from_json(model, doc)
+    doc['name'].sub('Masterpiece: ', '')
+  end
+end
+----
+
+== Using XML Namespaces
+
+Define XML namespaces for your models to handle namespaced XML elements.
+
+=== XML Namespace on Element
+
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, Lutaml::Model::Type::String
+  attribute :glaze, Lutaml::Model::Type::String
+
+  xml do
+    root 'Ceramic'
+    namespace 'http://example.com/ceramic'
+    map_element 'Type', to: :type
+    map_element 'Glaze', to: :glaze
+  end
+end
+----
+
+=== XML Namespace on Attribute
+
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, Lutaml::Model::Type::String
+  attribute :glaze, Lutaml::Model::Type::String
+
+  xml do
+    root 'Ceramic'
+    map_element 'Type', to: :type
+    map_element 'Glaze', to: :glaze
+    map_attribute 'xmlns', to: :namespace, namespace: 'http://example.com/ceramic'
+  end
+end
+----
+
+=== XML Namespace with `inherit` Option
+
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, Lutaml::Model::Type::String
+  attribute :glaze, Lutaml::Model::Type::String
+
+  xml do
+    root 'Ceramic'
+    namespace 'http://example.com/ceramic', prefix: 'cera'
+    map_element 'Type', to: :type, namespace: :inherit
+    map_element 'Glaze', to: :glaze
+  end
+end
+----
+
+== Adapters
+
+Lutaml::Model uses an adapter pattern to support multiple libraries for each serialization format.
+
+=== XML: Nokogiri, Oga, Ox
+
+[source,ruby]
+----
+require 'lutaml/model'
+require 'lutaml/model/xml_adapter/nokogiri_adapter'
+require 'lutaml/model/xml_adapter/ox_adapter'
+require 'lutaml/model/xml_adapter/oga_adapter'
+
+Lutaml::Model::Config.configure do |config|
+  config.xml_adapter = Lutaml::Model::XmlAdapter::NokogiriAdapter
+  # Or use OxAdapter or OgaAdapter
+end
+----
+
+=== JSON: `JSON` and `MultiJson`
+
+[source,ruby]
+----
+require 'lutaml/model'
+require 'lutaml/model/json_adapter/standard'
+require 'lutaml/model/json_adapter/multi_json'
+
+Lutaml::Model::Config.configure do |config|
+  config.json_adapter = Lutaml::Model::JsonAdapter::StandardDocument
+  # Or use MultiJsonDocument
+end
+----
+
+=== TOML: `Tomlib` and `Toml-rb`
+
+[source,ruby]
+----
+require 'lutaml/model'
+require 'lutaml/model/toml_adapter/toml_rb_adapter'
+require 'lutaml/model/toml_adapter/tomlib_adapter'
+
+Lutaml::Model::Config.configure do |config|
+  config.toml_adapter = Lutaml::Model::TomlAdapter::TomlRbDocument
+  # Or use TomlibDocument
+end
+----
+
+== License and Copyright
+
+This project is licensed under the BSD 2-clause License - see the LICENSE file for details.
+
+This project is maintained by Ribose.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "lutaml/model"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/lutaml/model/attribute.rb

@@ -0,0 +1,26 @@
+# lib/lutaml/model/attribute.rb
+module Lutaml
+  module Model
+    class Attribute
+      attr_reader :name, :type, :options
+
+      def initialize(name, type, options = {})
+        @name = name
+        @type = type
+        @options = options
+      end
+
+      def collection?
+        options[:collection] || false
+      end
+
+      def default
+        options[:default].is_a?(Proc) ? options[:default].call : options[:default]
+      end
+
+      def render_nil?
+        options.fetch(:render_nil, false)
+      end
+    end
+  end
+end

data/lib/lutaml/model/config.rb

@@ -0,0 +1,14 @@
+# lib/lutaml/model/config.rb
+module Lutaml
+  module Model
+    module Config
+      extend self
+
+      attr_accessor :xml_adapter, :json_adapter, :yaml_adapter, :toml_adapter
+
+      def configure
+        yield self
+      end
+    end
+  end
+end

data/lib/lutaml/model/json_adapter/multi_json.rb

@@ -0,0 +1,20 @@
+# lib/lutaml/model/json_adapter/multi_json.rb
+require "multi_json"
+require_relative "../json_adapter"
+
+module Lutaml
+  module Model
+    module JsonAdapter
+      class MultiJsonDocument < Document
+        def self.parse(json)
+          data = MultiJson.load(json)
+          new(data)
+        end
+
+        def to_json(*args)
+          MultiJson.dump(to_h, *args)
+        end
+      end
+    end
+  end
+end