prosereflect 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b4932ddc045360d00a528353acb8c741642588d3c0d180e62752d4090f47d28d
+  data.tar.gz: 646f972a327d8a8a735904bc31f64f2778232e077e6b1fcf6e888b1d6452ac25
+SHA512:
+  metadata.gz: fd539de5ef42d23b9d1cb4ab07a6dc2f6ea0466e02230016b09ce6f6c90dc6ab947ceaa82ee5f0058030cb0fee82484d6a676ad5841b8d6207d45dec717f785a
+  data.tar.gz: 38e6f185405e0dd9fdd56aa9821253442f545aac7944c54e909a6e5c5ee430c7d610caac53d4d32e4de1fd5ebb7b125822e1465ce3d01e8aa745621efaae603e

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,25 @@
+# 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).
+          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
+        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,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -0,0 +1,228 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-05-12 01:22:35 UTC using RuboCop version 1.75.5.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'bin/extract-ituob-amendments.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment.
+Layout/CommentIndentation:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLineAfterGuardClause:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
+Layout/EmptyLineBetweenDefs:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLines:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: empty_lines, empty_lines_except_namespace, empty_lines_special, no_empty_lines, beginning_only, ending_only
+Layout/EmptyLinesAroundClassBody:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, AllowedPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'bin/extract-ituob-amendments.rb'
+    - 'e118_amendment.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Lint/ScriptPermission:
+  Exclude:
+    - 'debug_loading.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect, ContextCreatingMethods, MethodCreatingMethods.
+Lint/UselessAccessModifier:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 5
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 98
+
+# Offense count: 23
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 201
+
+# Offense count: 4
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 30
+
+# Offense count: 6
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 47
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 32
+
+# Offense count: 9
+# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
+# SupportedStyles: snake_case, normalcase, non_integer
+# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
+Naming/VariableNumber:
+  Exclude:
+    - 'e118_entry.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'bin/extract-ituob-amendments.rb'
+
+# Offense count: 11
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'e118_amendment.rb'
+    - 'e118_entry.rb'
+    - 'lib/prosereflect/document.rb'
+    - 'lib/prosereflect/hard_break.rb'
+    - 'lib/prosereflect/node.rb'
+    - 'lib/prosereflect/paragraph.rb'
+    - 'lib/prosereflect/parser.rb'
+    - 'lib/prosereflect/table.rb'
+    - 'lib/prosereflect/table_cell.rb'
+    - 'lib/prosereflect/table_row.rb'
+    - 'lib/prosereflect/text.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: always, always_true, never
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - '**/*.arb'
+    - 'bin/extract-ituob-amendments.rb'
+
+# Offense count: 7
+# This cop supports safe autocorrection (--autocorrect).
+Style/IfUnlessModifier:
+  Exclude:
+    - 'e118_amendment.rb'
+    - 'e118_entry.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, MinBodyLength, AllowConsecutiveConditionals.
+# SupportedStyles: skip_modifier_ifs, always
+Style/Next:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 9
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
+# SupportedStyles: predicate, comparison
+Style/NumericPredicate:
+  Exclude:
+    - 'spec/**/*'
+    - 'e118_amendment.rb'
+    - 'e118_entry.rb'
+    - 'lib/prosereflect/table.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/ParallelAssignment:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantSelf:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: implicit, explicit
+Style/RescueStandardError:
+  Exclude:
+    - 'bin/extract-ituob-amendments.rb'
+
+# Offense count: 4
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: ConvertCodeThatCanStartToReturnNil, AllowedMethods, MaxChainLength.
+# AllowedMethods: present?, blank?, presence, try, try!
+Style/SafeNavigation:
+  Exclude:
+    - 'e118_amendment.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/SlicingWithRange:
+  Exclude:
+    - 'lib/prosereflect/table.rb'
+
+# Offense count: 38
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'Gemfile'
+    - 'Rakefile'
+    - 'bin/console'
+    - 'bin/extract-ituob-amendments.rb'
+    - 'lib/prosereflect.rb'
+    - 'lib/prosereflect/version.rb'
+    - 'prosereflect.gemspec'
+
+# Offense count: 7
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/ZeroLengthPredicate:
+  Exclude:
+    - 'e118_amendment.rb'
+    - 'e118_entry.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 153

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# 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, caste, color, 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 email 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
+[INSERT CONTACT METHOD].
+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.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in prosereflect.gemspec
+gemspec
+
+gem 'rake'
+gem 'rspec'
+gem 'rubocop'

data/README.adoc

@@ -0,0 +1,268 @@
+= prosereflect gem: Library for ProseMirror documents
+
+image:https://img.shields.io/gem/v/prosereflect.svg["Gem Version", link="https://rubygems.org/gems/prosereflect"]
+image:https://github.com/metanorma/prosereflect/actions/workflows/rake.yml/badge.svg["Build Status", link="https://github.com/metanorma/prosereflect/actions/workflows/rake.yml"]
+image:https://img.shields.io/github/issues-pr-raw/metanorma/prosereflect.svg["Pull Requests", link="https://github.com/metanorma/prosereflect/pulls"]
+image:https://img.shields.io/github/commits-since/metanorma/prosereflect/latest.svg["Commits since latest",link="https://github.com/metanorma/prosereflect/releases"]
+
+== Purpose
+
+`prosereflect` is a Ruby gem for working with the document structure used by the https://prosemirror.net/[ProseMirror rich text editor].
+
+It provides a set of models and utilities for parsing, manipulating, and
+accessing the hierarchical document tree structure represented in ProseMirror's
+JSON/YAML format. This allows for convenient traversal and extraction of content
+from rich text documents.
+
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'prosereflect'
+----
+
+And then execute:
+
+[source,shell]
+----
+$ bundle install
+----
+
+Or install it yourself as:
+
+[source,shell]
+----
+$ gem install prosereflect
+----
+
+== Usage
+
+=== Parsing ProseMirror documents
+
+==== From YAML
+
+[source,ruby]
+----
+require 'prosereflect'
+
+# Parse from YAML string or file
+yaml_content = File.read('document.yaml')
+document = Prosereflect::Parser.parse_document(yaml_content)
+
+# Access the document structure
+document.content.each do |node|
+  # Work with nodes
+end
+----
+
+==== From JSON
+
+[source,ruby]
+----
+require 'prosereflect'
+
+# Parse from JSON string or file
+json_content = File.read('document.json')
+document = Prosereflect::Parser.parse_document(json_content)
+----
+
+=== Navigating the document
+
+[source,ruby]
+----
+# Get all tables in the document
+tables = document.tables
+
+# Get all paragraphs
+paragraphs = document.paragraphs
+
+# Access the first table
+first_table = document.first_table
+
+# Access header row and data rows in a table
+header = first_table.header_row
+data_rows = first_table.data_rows
+
+# Access cells in a table
+cell = first_table.cell_at(0, 0)  # First data row, first column
+----
+
+=== Accessing content
+
+[source,ruby]
+----
+# Get text content from a paragraph
+paragraph = document.paragraphs.first
+text = paragraph.text_content
+
+# Get text content from a table cell
+cell = document.tables.first.cell_at(0, 0)
+cell_text = cell.text_content
+
+# Get cell content as separate lines
+lines = cell.lines
+----
+
+=== Finding nodes
+
+[source,ruby]
+----
+# Find the first node of a specific type
+table = document.find_first('table')
+paragraph = document.find_first('paragraph')
+
+# Find all nodes of a specific type
+tables = document.find_all('table')
+text_nodes = document.find_all('text')
+
+# Find child nodes of a specific type
+table_cells = table.find_children('table_cell')
+----
+
+== Data model
+
+The prosereflect gem represents the document structure as a hierarchy of node
+objects.
+
+[source]
+----
++-------------------+
+|      Document     |
+|                   |
+| +content          |
++--------+----------+
+         |
+         | 1..*
++--------v----------+
+|        Node       |
+|                   |
+| -type             |
+| -attrs            |
+| -marks            |
+| +content          |
++-------------------+
+         |
+    +----+----+---------------------+
+    |         |                     |
++---v---+ +---v----------+  +-------v--------+
+|Table  | |  Paragraph   |  |     Text       |
+|       | |              |  |                |
++---+---+ +--------------+  +----------------+
+    |
+    |
++---v-----------+
+|   TableRow    |
+|               |
++---+-----------+
+    |
++---v-----------+
+|   TableCell   |
+|               |
++---------------+
+----
+
+== Classes
+
+=== Node
+
+Base class for all node types.
+
+`type`:: The node type (e.g., "doc", "paragraph", "text", "table")
+`content`:: A collection of child nodes
+`attrs`:: Attributes specific to the node type
+`marks`:: Formatting marks applied to the node
+
+=== Document
+
+Top-level container representing a ProseMirror document.
+
+`content`:: A collection of top-level nodes in the document
+
+=== Paragraph
+
+Represents a paragraph of text.
+
+`text_content`:: Returns the combined text content of all child text nodes
+
+=== Text
+
+Represents a text node.
+
+`text`:: The text content of the node
+
+=== Table
+
+Represents a table structure.
+
+`rows`:: All table rows
+`header_row`:: The first row (assumed to be the header)
+`data_rows`:: All rows except the header
+`cell_at(row_index, col_index)`:: Access a specific cell by position
+
+=== TableRow
+
+Represents a row in a table.
+
+`cells`:: All cells in the row
+
+=== TableCell
+
+Represents a cell in a table.
+
+`paragraphs`:: All paragraphs in the cell
+`text_content`:: All text content combined
+`lines`:: Text content split into separate lines
+
+
+== Development
+
+=== Adding test fixtures
+
+The repository includes a utility script `bin/extract-ituob-amendments.rb` to
+extract ProseMirror content from the ITU Operational Bulletin for test fixtures.
+
+Syntax:
+
+[source,shell]
+----
+$ bin/extract-ituob-amendments.rb {filename} {issue_number}
+----
+
+Where,
+
+`{filename}`:: The amendments YAML file to extract from. The script expects the
+`{filename}` file in the format used by the ITU Operational Bulletin data
+repository: https://github.com/ituob/itu-ob-data/
+`{issue_number}`:: The issue number to use in the generated file names.
+
+This command:
+
+. Extract ProseMirror content from the specified amendments file
+. Generate both YAML and JSON files in the current directory
+. Name files according to the pattern `ituob-<issue_number>-<publication>.<format>`
+
+These generated files can be moved to `spec/fixtures/ituob-<issue_number>/` to use in tests.
+
+
+[example]
+====
+[source,shell]
+----
+$ bin/extract-ituob-amendments.rb amendments.yaml 1000
+----
+====
+
+
+
+== Copyright
+
+This gem is developed, maintained and funded by
+https://www.ribose.com[Ribose Inc.]
+
+== License
+
+The gem is available as open source under the terms of the
+https://opensource.org/licenses/BSD-2-Clause[2-Clause BSD License].