rsyntaxtree 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 231de78b2e34e37f4a5bbccd641839e8cf5ae1babc2d8d4362d86dcf782d28b4
-  data.tar.gz: a4d04e71e6587592540400aa9a7e23d9dadae0d19912078d5d6cc5ebd65c117d
+  metadata.gz: 8c57f743f27cc6830495cfe9da3ce4483fec13491af8e80d4437357cc9c37968
+  data.tar.gz: d051b212a5abe64711fd42622bce06cea77c1e8bfc78a8315dfc1246f0dc22d0
 SHA512:
-  metadata.gz: f97797690b6d8e0ad8404c00a10c061c89d2213e582915a33fc9d739305d5fb10cdd0afde6bffe0b16f504b5d5854d7dcb0249f50a22b10599638fb22180aed3
-  data.tar.gz: 7f5814cc9bf0875b21982cf6c143397d467fb900a7973c8f6213934387ba4f80e0605ddccec63f02bc7bacc6d182a9da1bda3237f909414ba4c64f63a1da1d12
+  metadata.gz: e214718246e31cf0d42a03f91ee4b7e714cf1576f3f60fb70b6d0fb9d2d22a24e2b04e832d9e8be2df0b664b5506bf8a0994f659384a85469a4023535409c615
+  data.tar.gz: 5f7638450414b9cb53ac9fe2cdc08e7776af24ea50a0de75166dfbb3d47b9d4a27ab1d45a026012ef6bd9fdcc76400b1cf88f7df5095dac20cd78c629c3ccc33

data/.dockerignore

@@ -0,0 +1,5 @@
+# The image needs the working tree, not the repository: without this, ADD .
+# copies .git into every image — hundreds of megabytes of history, including
+# refs that exist only on the build machine.
+.git
+pkg

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [2.3.0] - 2026-09-01
+
+### Added
+- `RSTError::CODES` lists every error code the library can report. A program
+  keyed by code — one that translates the diagnosis, or tallies what kinds of
+  mistake a writer makes — needs the whole set rather than the codes it has
+  happened to see, and until now that set could only be recovered by reading
+  five files and the repair table. The list only grows: a published code is
+  not renamed or removed.
+
+### Fixed
+- Whitespace alone is an empty input rather than a defect in the library. It
+  reached the drawing, which walked off the end of an empty tree and reported
+  `internal_error`, telling the caller that their own fixable input was the
+  library's fault.
+- A bracketless input of a single character draws. The tokenizer counted its
+  cursor as exhausted one character early, so `A`, and `<>` once it is one
+  whitespace block, produced no tokens at all — though the manual has always
+  said a label on its own draws as one leaf.
+
+## [2.2.0] - 2026-09-01
+
+### Changed
+- Validation reports every error of a stage, not just the first one found.
+  An input with three bad labels lists all three in the `errors` array of
+  the JSON diagnosis, so one round of fixes covers them. The stages are
+  ordered — options, bracket structure, labels, whole-tree checks — and a
+  mistake stops the later stages, with a `note` saying that fixing what is
+  listed may reveal more; nothing is reported whose appearance is an
+  artifact of an earlier mistake. Duplicate failures collapse to one entry
+  and the list stops at twenty. The schema is unchanged
+  (`rsyntaxtree.error/1`): the same array, more of it.
+
+### Added
+- `RSGenerator.diagnose(text, options)` returns the full diagnosis as a
+  hash — what `--validate` prints — for programmatic callers.
+  `check_data` keeps its contract of raising the first error.
+
 ## [2.1.0] - 2026-08-29
 
 ### Changed
@@ -79,9 +117,8 @@ looking at what was left. Every figure in the gallery draws exactly as it did.
 
 ### Added
 - `shear`: the drawn figure tilts by the given angle (degrees, positive
-  leaning the top to the right) and lies on a plane drawn behind it, so the
-  lean reads as a surface seen at an angle rather than as a mistake. The
-  whole picture shears as one affine piece — layout untouched, region
+  leaning the top to the right) and lies on a plane drawn behind it, which
+  shows the tilt as a surface. The whole picture shears as one affine piece — layout untouched, region
   shades coming out parallelograms on their own, and nothing able to newly
   touch or cross. The plane is fill without an edge — a region shade is
   bounded because it marks one part of a figure off from the rest, and a
@@ -227,9 +264,8 @@ looking at what was left. Every figure in the gallery draws exactly as it did.
 - Derivations. A derivation puts the words first and the result last, and
   joins what each step combines with one rule drawn across all of it rather
   than with a line to each daughter. `derivation` draws the rules and
-  `direction: btt` turns the tree over; together they give the format
-  categorial grammar is written in, and `derivation` on its own marks the
-  spans of an ordinary tree. The name of each step rides in the label after a
+  `direction: btt` turns the tree over; together they draw a CCG derivation,
+  and `derivation` on its own marks the spans of an ordinary tree. The name of each step rides in the label after a
   column break and is set beside the end of its rule. A derivation runs down
   the page and is drawn with its rules, so `direction: ltr` and hiding the
   default connectors are refused rather than approximated.
@@ -361,15 +397,15 @@ RMagick dependency.
   rule that work never uses.
 - A matrix nested in a label, written between `#(` and `#)`. The value of an
   attribute can be another attribute-value matrix, to any depth, which is what
-  a feature path such as SYNSEM | LOCAL | CATEGORY | HEAD needs and what HPSG,
-  SBCG and LFG are written in. The nested matrix draws its own brackets and
+  a feature path such as SYNSEM | LOCAL | CATEGORY | HEAD needs, and what
+  HPSG and LFG are written in. The nested matrix draws its own brackets and
   lays out its own columns, and the rows after it clear its full height.
 - `\t` in a label cuts the line into cells. Every line is cut at the same
   points and each column is drawn at the width of its widest cell, so the
   parts line up down the label. Together with the bracket enclosure and the
   horizontal rule this gives attribute-value matrices — the feature structures
-  of HPSG, SBCG and LFG — without spacing each row by hand, which is how the
-  gallery's HPSG example used to do it.
+  of HPSG, LFG and the like — without spacing each row by hand, which is how
+  the gallery's HPSG example used to do it.
 - `color: gray`, a scheme that keeps node and leaf labels black and draws the
   connectors, triangles and movement paths in grey. It is for diagrams whose
   links outnumber their labels — an ontology, a network of constructions —

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+
+# 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 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 <yohasebe@gmail.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.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/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to RSyntaxTree
+
+This page explains how to report a problem, propose a change, and get a
+development environment running.
+
+## Reporting bugs
+
+Open an issue at <https://github.com/yohasebe/rsyntaxtree/issues> with:
+
+- the input text (the bracket notation) and the options you used
+- what you expected and what you got — for drawing problems, attach the image
+- your platform and how you run RSyntaxTree (gem, Docker, or the
+  [web interface](https://yohasebe.com/rsyntaxtree))
+
+If the input fails to draw, include the output of:
+
+```bash
+rsyntaxtree --validate "your input here"
+```
+
+It reports the problem in a structured form that is usually enough to
+diagnose the issue.
+
+## Suggesting features
+
+Open an issue describing what you want to draw and, ideally, a hand-drawn or
+published example of the intended output. The
+[gallery](https://yohasebe.github.io/rsyntaxtree/examples) shows the range of
+figures the notation covers today; a suggestion that names the linguistic
+framework it serves is easier to evaluate than one described purely in terms
+of graphics.
+
+Not every good idea belongs in RSyntaxTree. The project deliberately keeps
+the notation small, so proposals are weighed against what they add for
+users who do not need them.
+
+## Setting up for development
+
+System libraries first (Pango for text measurement, librsvg for rasterizing):
+
+```bash
+# Debian/Ubuntu
+apt install libpango1.0-dev librsvg2-dev libgirepository1.0-dev gobject-introspection
+
+# macOS
+brew install pkg-config pango librsvg gobject-introspection
+```
+
+The tests measure text with the Noto fonts, so install them too — the
+[Fonts](https://yohasebe.github.io/rsyntaxtree/documentation#fonts) section
+of the manual lists the package names for each platform.
+
+Then:
+
+```bash
+git clone https://github.com/yohasebe/rsyntaxtree.git
+cd rsyntaxtree
+bundle install
+bundle exec rake test
+```
+
+The tests should pass before and after your change.
+
+## Making changes
+
+- Every behavioral change needs a test that fails without it.
+- The committed gallery figures are generated inside Docker
+  (`rake docker_build && rake docker_generate`) so that font differences
+  between machines do not rewrite them. Do not regenerate them with a local
+  `rake generate`; if your change intentionally alters figures, say so in
+  the pull request and the maintainer will regenerate them.
+- The manual lives in `docs/documentation.md` (English) and
+  `docs/documentation_ja.md` (Japanese). If your change affects the
+  notation or an option, update at least the English manual; the reference
+  the gem installs (`lib/rsyntaxtree/notation_core.md`) and the LLM payload
+  (`rake llm_payload`) must be regenerated when examples or the manual
+  change — the test suite tells you when they are stale.
+
+## Pull requests
+
+Fork, branch, and open a pull request against `master`. A good pull request
+explains the problem before the solution and stays small enough to review.
+CI runs the test suite on Linux and an installation check on macOS; both
+must pass.
+
+## Questions
+
+For anything that does not fit an issue, contact the maintainer:
+Yoichiro Hasebe <yohasebe@gmail.com>.

data/README.md

@@ -135,23 +135,17 @@ See [Fonts](https://yohasebe.github.io/rsyntaxtree/documentation#install-fonts-f
 gem install rsyntaxtree
 ```
 
-### macOS Installation Notice
-
-**Important for macOS users:** If you encounter build errors for native extensions (`gobject-introspection`, `cairo-gobject`, `gio2`), run the following commands before installing RSyntaxTree:
-
-```bash
-gem install gobject-introspection -- --with-ldflags="-Wl,-undefined,dynamic_lookup"
-gem install cairo-gobject -- --with-ldflags="-Wl,-undefined,dynamic_lookup"
-gem install gio2 -- --with-ldflags="-Wl,-undefined,dynamic_lookup"
-```
-
-Then install RSyntaxTree:
-
-```bash
-gem install rsyntaxtree
-```
-
-Alternatively, use the [Docker image](https://hub.docker.com/r/yohasebe/rsyntaxtree) or the [web interface](https://yohasebe.com/rsyntaxtree).
+### macOS
+
+With the libraries in place (`brew install pkg-config pango librsvg
+gobject-introspection`), a plain `gem install rsyntaxtree` builds the native
+extensions without further options — CI verifies this on every change. If an
+older setup still fails to build `gobject-introspection`, `cairo-gobject` or
+`gio2`, install those three first with
+`-- --with-ldflags="-Wl,-undefined,dynamic_lookup"` appended, then install
+RSyntaxTree; or skip the build entirely with the
+[Docker image](https://hub.docker.com/r/yohasebe/rsyntaxtree) or the
+[web interface](https://yohasebe.com/rsyntaxtree).
 
 ## Usage
 

data/bin/rsyntaxtree

@@ -214,12 +214,9 @@ data = RSyntaxTree::FormatConverter.to_bracket(data) if data
 # Validate without drawing or writing anything: the diagnosis goes to stdout
 # as JSON and the exit code carries the verdict.
 if opts[:validate]
-  diagnosis = begin
-    RSyntaxTree::RSGenerator.check_data(data, string_opts)
-    { "schema" => "rsyntaxtree.error/1", "ok" => true }
-  rescue RSTError => e
-    { "schema" => "rsyntaxtree.error/1" }.merge(e.to_h)
-  end
+  diagnosis = { "schema" => "rsyntaxtree.error/1" }.merge(
+    RSyntaxTree::RSGenerator.diagnose(data, string_opts)
+  )
   puts JSON.pretty_generate(diagnosis)
   exit(diagnosis["ok"] ? 0 : 1)
 end

data/lib/rsyntaxtree/notation_examples.md

@@ -1,4 +1,4 @@
-RSyntaxTree examples: 80 trees, every one verified to draw.
+RSyntaxTree examples: 81 trees, every one verified to draw.
 
 Each is the input behind a figure in the gallery at https://yohasebe.github.io/rsyntaxtree/examples.
 The settings line names the options the gallery records for that figure;
@@ -2586,30 +2586,56 @@ VAL\t#(SPR\t⟨<>⟩#)#)#)
   VAL\t#(SPR\t⟨<>*NP*<>⟩#)#)#) [barks]]]
 ```
 
-## 085 — A tree on a tilted plane
+## 085 — A tree on a tilted plane, with a movement path
 
 Category: General
 Settings: fontstyle=noto-serif shear=20 vheight=1.0
 
 ```
-[S
-  [NP
-    [D the]
-    [N man]
-  ]
-  [VP
-    [V put]
-    [NP
-      [D the]
-      [N book]
-    ]
-    [PP
-      [P on]
+[CP
+  [NP what+>1]
+  [C'
+    [C did]
+    [TP
       [NP
         [D the]
-        [N table]
+        [N man]
+      ]
+      [VP
+        [V'
+          [V put]
+          [NP *t*+1]
+        ]
+        [PP
+          [P on]
+          [NP
+            [D the]
+            [N table]
+          ]
+        ]
       ]
     ]
   ]
 ]
 ```
+
+## 086 — Feature structures on a tilted plane
+
+Category: General
+Settings: color=none fontstyle=noto-serif leafstyle=nothing shear=20 vheight=1.5
+
+```
+[#(*phrase*\
+---\
+SYN\t#(HEAD\t|1|#)#)
+  [#(*word*\
+  ---\
+  SYN\t#(HEAD\t#(*noun*\
+  ---\
+  AGR\t|2|#(NUM\t*pl*#)#)#)#) [dogs]]
+  [#(*word*\
+  ---\
+  SYN\t#(HEAD\t|1|#(*verb*\
+  ---\
+  AGR\t|2|#)#)#) [bark]]]
+```

data/lib/rsyntaxtree/string_parser.rb

@@ -15,9 +15,23 @@ require_relative 'utils'
 module RSyntaxTree
   class StringParser
     attr_accessor :data, :elist, :pos, :id, :level
+    attr_reader :collected_errors
 
-    def initialize(str, fontset, fontsize, global)
+    # In collect mode, reporting stops here but the walk does not: labels
+    # past this many failures are still checked (the tree must stay whole)
+    # without adding to the list.
+    COLLECTED_ERRORS_LIMIT = 20
+
+    # What stands in for a label that would not parse, when collecting.
+    # Any label that always parses will do; what matters is that it keeps
+    # the tree's shape.
+    PLACEHOLDER_LABEL = "x"
+
+    def initialize(str, fontset, fontsize, global, collect_errors: false)
       @global = global
+      @collect_errors = collect_errors
+      @collected_errors = []
+      @more_errors = false
       # Clean up the data a little to make processing easier
       # repeated newlines => a newline
       string = str.gsub(/[\n\r]+/m, "\n")
@@ -50,7 +64,12 @@ module RSyntaxTree
     end
 
     def self.valid?(data)
-      raise RSTError.new(+"Error: input text is empty", code: :empty_input, retryable: false) if data.empty?
+      # Whitespace alone is an empty input, not a tree with one blank label:
+      # nothing survives the parse, and what used to happen is that the
+      # drawing walked off the end of an empty element list and reported a
+      # defect in the library for what the caller could see and fix. A space
+      # meant as a label is written <>, which is not whitespace here.
+      raise RSTError.new(+"Error: input text is empty", code: :empty_input, retryable: false) if data.strip.empty?
 
       if /\[\s*\]/m =~ data
         raise RSTError.new(+"Error: inside the brackets is empty", code: :empty_brackets,
@@ -113,6 +132,41 @@ module RSyntaxTree
       restore_rule_names_without_a_rule
     end
 
+    def more_errors?
+      @more_errors
+    end
+
+    # One element, or its recorded failure. Outside collect mode this is
+    # exactly the Element.new it wraps. In collect mode an RSTError is
+    # recorded and a placeholder element stands in, so the walk continues
+    # and every bad label is seen. The placeholder keeps the tree's shape —
+    # parenthood, childlessness, level — which is all a later label's
+    # verdict can depend on; what it cannot keep (a path marker the broken
+    # label carried) only matters to the whole-tree checks, and those do
+    # not run while collected errors stand.
+    def element_or_recorded_failure(id, parent, level, names_a_rule = false)
+      yield
+    rescue RSTError => e
+      raise unless @collect_errors
+
+      record_failure(e)
+      Element.new(id, parent, PLACEHOLDER_LABEL, level, @fontset, @fontsize, @global, names_a_rule)
+    end
+
+    # The same mistake in two copies of a label is one thing to fix, so a
+    # failure is recorded once per (code, label, position). Past the limit
+    # the list stops growing and only the fact that there was more is kept.
+    def record_failure(error)
+      key = [error.code, error.label, error.position]
+      return if @collected_errors.any? { |c| [c.code, c.label, c.position] == key }
+
+      if @collected_errors.length >= COLLECTED_ERRORS_LIMIT
+        @more_errors = true
+      else
+        @collected_errors << error
+      end
+    end
+
     # A rule name names the step that produced a node from its daughters. A node
     # with no daughters is the product of no step, so what looked like a name is
     # a column of the label like any other, and it goes back.
@@ -128,8 +182,17 @@ module RSyntaxTree
         next unless e.children.empty?
         next if e.label_with_rule_name.nil?
 
-        restored = Element.new(e.id, e.parent, e.label_with_rule_name,
-                               e.level, @fontset, @fontsize, @global)
+        # In collect mode the failed restoration is recorded and the element
+        # kept as it is; the tree stays whole either way.
+        restored = begin
+          Element.new(e.id, e.parent, e.label_with_rule_name,
+                      e.level, @fontset, @fontsize, @global)
+        rescue RSTError => err
+          raise unless @collect_errors
+
+          record_failure(err)
+          next
+        end
         restored.children = e.children
         restored.type = e.type
         @elist.elements[i] = restored
@@ -146,7 +209,11 @@ module RSyntaxTree
       token = ""
       i = 0
 
-      return "" if (@pos + 1) >= data.length
+      # The cursor is exhausted when it reaches the end, not one before it:
+      # counting from @pos + 1 skipped the last character, so an input of a
+      # single character — "A", or "<>" once it is one whitespace block —
+      # produced no tokens at all and drew from an empty element list.
+      return "" if @pos >= data.length
 
       escape = false
       while ((@pos + i) < data.length) && !gottoken
@@ -226,7 +293,9 @@ module RSyntaxTree
           # Check for escaped square brackets
           if token =~ /\A\\\[/ || token =~ /\A\\\]/
             # Treat escaped brackets as regular text
-            element = Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            element = element_or_recorded_failure(@id, parent, @level) do
+              Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            end
             @id += 1
             @elist.add(element)
           else
@@ -241,7 +310,7 @@ module RSyntaxTree
               tl = token_r.length
               parts[1] = token_r[spaceat, tl - spaceat].join
 
-              element = begin
+              element = element_or_recorded_failure(@id, parent, @level, true) do
                 Element.new(@id, parent, parts[0], @level, @fontset, @fontsize, @global, true)
               rescue RSTError => e
                 # The first raw space splits a token into the node's label
@@ -277,11 +346,15 @@ module RSyntaxTree
               @elist.add(element)
               newparent = element.id
 
-              element = Element.new(@id, @id - 1, parts[1], @level + 1, @fontset, @fontsize, @global)
+              element = element_or_recorded_failure(@id, @id - 1, @level + 1) do
+                Element.new(@id, @id - 1, parts[1], @level + 1, @fontset, @fontsize, @global)
+              end
               @id += 1
             else
               joined = token_r.join
-              element = Element.new(@id, parent, joined, @level, @fontset, @fontsize, @global, true)
+              element = element_or_recorded_failure(@id, parent, @level, true) do
+                Element.new(@id, parent, joined, @level, @fontset, @fontsize, @global, true)
+              end
               @id += 1
               newparent = element.id
             end
@@ -291,7 +364,9 @@ module RSyntaxTree
           end
         else
           if token.strip != ""
-            element = Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            element = element_or_recorded_failure(@id, parent, @level) do
+              Element.new(@id, parent, token, @level, @fontset, @fontsize, @global)
+            end
             @id += 1
             @elist.add(element)
           end

data/lib/rsyntaxtree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RSyntaxTree
-  VERSION = "2.1.0"
+  VERSION = "2.3.0"
 end

data/lib/rsyntaxtree.rb

@@ -133,20 +133,70 @@ class RSTError < StandardError
     super(msg.gsub(WHITESPACE_BLOCK, "<>"))
   end
 
+  # Every code an error from this library can carry. Consumers dispatch on
+  # these — a translation keyed by code, a harness counting what kinds of
+  # mistake occur — and both need to know the whole set, not only the codes
+  # they have happened to see: a kind of mistake nobody made is not the same
+  # as a kind that cannot happen. Until this list existed the set was only
+  # discoverable by reading five files and a repair table.
+  #
+  # Written out rather than computed, because it is a contract and a contract
+  # should be readable at a glance and visible in a diff. A test keeps it
+  # honest by finding the codes the library actually raises and comparing.
+  #
+  # The list grows and does not churn: a code once published is not renamed
+  # or removed, so a consumer keyed by code — a translation table, a tally of
+  # what kinds of mistake a writer makes — only ever has entries to add.
+  #
+  # Eight are named by the repair table, which diagnoses a label by rewriting
+  # it and asking the parser whether the rewrite reads: angle_brackets,
+  # bare_hyphen, incomplete_path, invalid_color, rule_name_without_derivation,
+  # stray_triangle, unclosed_markup, unclosed_matrix. invalid_markup is where
+  # a label lands whose mistake no single rewrite fits, which in practice
+  # means more than one. unknown_color and label_split are mistakes inside a
+  # label too, found before the repair table is reached.
+  CODES = %i[
+    angle_brackets
+    bare_hyphen
+    empty_brackets
+    empty_input
+    incomplete_path
+    internal_error
+    invalid_color
+    invalid_markup
+    invalid_option
+    label_split
+    path_multiple_ends
+    path_single_end
+    result_too_big
+    rule_name_without_derivation
+    stray_triangle
+    unbalanced_brackets
+    unclosed_markup
+    unclosed_matrix
+    unknown_color
+  ].freeze
+
   # Where the notation is written down. A hint repairs the mistake in front of
   # it and says nothing about the rest, which is enough for a reader who knows
   # the notation and not enough for one who was guessing at it. Given once, at
   # the top, rather than repeated on every error.
   REFERENCE = "rsyntaxtree --notation, or https://yohasebe.github.io/rsyntaxtree/llms-full.txt"
 
+  # One error as the hash the JSON diagnosis carries; to_h wraps a single
+  # one and diagnose collects many.
+  def error_entry
+    { "code" => code.to_s,
+      "message" => message,
+      "label" => label,
+      "position" => position,
+      "hint" => hint,
+      "retryable" => retryable }.compact
+  end
+
   def to_h
     { "ok" => false,
-      "errors" => [{ "code" => code.to_s,
-                     "message" => message,
-                     "label" => label,
-                     "position" => position,
-                     "hint" => hint,
-                     "retryable" => retryable }.compact],
+      "errors" => [error_entry],
       "reference" => REFERENCE }
   end
 end
@@ -185,13 +235,13 @@ module RSyntaxTree
 
         if REMOVED_OPTIONS.key?(key)
           raise RSTError.new(+"Error: option '#{key}' was removed in RSyntaxTree 2.0",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "Use #{REMOVED_OPTIONS[key]} instead.",
                              retryable: false)
         end
         if OPTION_VALUES.key?(key) && !OPTION_VALUES[key].include?(value.to_s)
           raise RSTError.new(+"Error: invalid value for option '#{key}': #{value.inspect}",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "'#{key}' must be one of: #{OPTION_VALUES[key].join(', ')}.",
                              retryable: false)
         end
@@ -202,14 +252,14 @@ module RSyntaxTree
         if NUMERIC_RANGES.key?(key) && !value.is_a?(Numeric) &&
            value.to_s.strip !~ /\A-?(\d+(\.\d+)?|\.\d+)\z/
           raise RSTError.new(+"Error: invalid value for option '#{key}': #{value.inspect}",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "'#{key}' takes a number.",
                              retryable: false)
         end
         if NUMERIC_RANGES.key?(key) && !NUMERIC_RANGES[key].cover?(value.to_f)
           range = NUMERIC_RANGES[key]
           raise RSTError.new(+"Error: invalid value for option '#{key}': #{value.inspect}",
-                             code: :invalid_option,
+                             code: :invalid_option, label: key.to_s,
                              hint: "'#{key}' must be in the range of #{range.begin}-#{range.end}.",
                              retryable: false)
         end
@@ -288,7 +338,7 @@ module RSyntaxTree
                               else
                                 unless COLOR_NAMES.include?(v.downcase) || v =~ /\A#(\h{3}|\h{6})\z/
                                   raise RSTError.new(+"Error: invalid value for option 'shear_plane': #{value.inspect}",
-                                                     code: :invalid_option,
+                                                     code: :invalid_option, label: "shear_plane",
                                                      hint: "'shear_plane' is on, off, a colour name, " \
                                                            "or a hex colour of 3 or 6 digits.",
                                                      retryable: false)
@@ -333,7 +383,7 @@ module RSyntaxTree
       # the combination is refused rather than approximated.
       if @params[:derivation] == true && @params[:direction] == "ltr"
         raise RSTError.new(+"Error: a derivation cannot be drawn left to right",
-                           code: :invalid_option,
+                           code: :invalid_option, label: "derivation",
                            hint: "A derivation runs down the page. Use direction ttb or btt, " \
                                  "or turn derivation off.",
                            retryable: false)
@@ -346,7 +396,7 @@ module RSyntaxTree
       # them. Refused for the same reason as left to right.
       if @params[:derivation] == true && @params[:hide_default_connectors] == true
         raise RSTError.new(+"Error: a derivation's rules cannot be hidden",
-                           code: :invalid_option,
+                           code: :invalid_option, label: "derivation",
                            hint: "The rules are what a derivation is drawn with, not a " \
                                  "connector added to it. Turn off hide default connectors, " \
                                  "or turn derivation off.",
@@ -429,8 +479,21 @@ module RSyntaxTree
       !OFF.include?(value.to_s.strip.downcase)
     end
 
+    # Whether the input is nothing to draw. Whitespace alone counts: it
+    # leaves no label behind, and reporting it as a defect in the library
+    # told the caller their own fixable input was our fault. Asked without
+    # strip when the bytes are not valid UTF-8, because strip raises there
+    # and that input is not blank — it is malformed, which the caller
+    # learns further down.
+    def self.blank?(text)
+      s = text.to_s
+      return true if s.empty?
+
+      s.valid_encoding? && s.strip.empty?
+    end
+
     def self.check_data(text, params = {})
-      raise RSTError.new(+"Error: input text is empty", code: :empty_input, retryable: false) if text.to_s == ""
+      raise RSTError.new(+"Error: input text is empty", code: :empty_input, retryable: false) if blank?(text)
 
       begin
         StringParser.valid?(text)
@@ -448,6 +511,101 @@ module RSyntaxTree
       end
     end
 
+    # Every option error at once. The constructor is the only judge of an
+    # option, and its rules are not written out a second time here: it
+    # stops at its first complaint, so it is asked again with the option
+    # it complained about set aside, until it accepts what is left or
+    # names nothing to set aside. Each round removes one option, so the
+    # loop is as bounded as the option list.
+    def self.option_errors(params)
+      remaining = params.reject { |k, _| k.to_sym == :data }
+      errors = []
+      loop do
+        begin
+          new(remaining.merge(data: "[A a]"))
+          break
+        rescue RSTError => e
+          errors << e
+          key = e.label
+          break if key.nil? || remaining.keys.none? { |k| k.to_s == key }
+
+          remaining = remaining.reject { |k, _| k.to_s == key }
+        end
+      end
+      errors
+    end
+
+    # Parse in collect mode: every label that will not parse, and every
+    # rule name that turns out to have no rule behind it, recorded instead
+    # of raised. The walk is the real one — the same tokens, the same
+    # judgments — so what this reports and what drawing rejects cannot
+    # drift apart. Returns the errors and whether the list was cut short.
+    def collect_input_errors
+      sp = StringParser.new(@params[:data].gsub('&', '&amp;'), @params[:fontset],
+                            @params[:fontsize], @global, collect_errors: true)
+      sp.parse
+      [sp.collected_errors, sp.more_errors?]
+    end
+
+    NOTE_OPTIONS = "Not every option could be read, so the input itself has " \
+                   "not been checked yet; fixing the options may reveal more."
+    NOTE_STRUCTURE = "The bracket structure could not be read, so the labels " \
+                     "have not been checked yet; fixing it may reveal more."
+    NOTE_LABELS = "Whole-tree checks (paths, output limits) run only once " \
+                  "every label reads, so fixing these may reveal more."
+    NOTE_TRUNCATED = " Only the first #{StringParser::COLLECTED_ERRORS_LIMIT} " \
+                     "problems are listed."
+
+    # The whole diagnosis at once, as the hash the CLI prints: every error
+    # of the first stage that finds any, not just the first error found.
+    # Stages are ordered so that nothing is reported whose appearance is an
+    # artifact of an earlier mistake — a missing bracket shifts every token
+    # after it, an unreadable hyphen option changes what counts as markup —
+    # and when a stage stops the walk, the note says that fixing what is
+    # listed may reveal more. check_data keeps its contract (raise the
+    # first error) for callers that want a verdict rather than a list.
+    def self.diagnose(text, params = {})
+      errors = []
+      note = nil
+      if blank?(text)
+        errors << RSTError.new(+"Error: input text is empty", code: :empty_input, retryable: false)
+      else
+        begin
+          errors = option_errors(params)
+          if errors.any?
+            note = NOTE_OPTIONS
+          else
+            StringParser.valid?(text)
+            gen = new(params.merge(data: text))
+            collected, truncated = gen.collect_input_errors
+            if collected.any?
+              errors = collected
+              note = NOTE_LABELS
+              note += NOTE_TRUNCATED if truncated
+            else
+              gen.validate!
+            end
+          end
+        rescue RSTError => e
+          errors << e
+          note = NOTE_STRUCTURE if %i[empty_brackets unbalanced_brackets].include?(e.code)
+        rescue StandardError => e
+          # The same promise check_data makes: a defect anywhere in here —
+          # the option probing included — is still a verdict of "no", in
+          # the same shape, not a backtrace.
+          errors << RSTError.new(+"Error: input could not be processed (#{e.class})",
+                                 code: :internal_error, retryable: false)
+        end
+      end
+
+      return { "ok" => true } if errors.empty?
+
+      result = { "ok" => false, "errors" => errors.map(&:error_entry) }
+      result["note"] = note if note
+      result["reference"] = RSTError::REFERENCE
+      result
+    end
+
     # Generate, and throw the result away. Parsing alone leaves out the
     # checks that only happen once the tree is laid out — a movement path
     # with one end, a line with three — so validation that stopped at the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsyntaxtree
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Yoichiro Hasebe
@@ -115,8 +115,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".dockerignore"
 - CHANGELOG.md
 - CITATION.cff
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE
 - README.md
 - bin/rsyntaxtree