rsyntaxtree 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38f3abe8841c2097201c6120f900a0d9eb99fb8bea9c6dc8388ac38a8e0df2c7
-  data.tar.gz: d22ebd93a2a2ed135e4afcc21797f4f057a3b5d340fdfd265a7f5490ccc642fb
+  metadata.gz: 6afa75eb042fe177454d387fa097c74fb6b44fd317ae709f91495f2f9b8df269
+  data.tar.gz: 60e201c577b1cf02d12f6506b10e62b1b21e419d6d37955e4a69a338b28bfd90
 SHA512:
-  metadata.gz: b3c9dc57831246bdd189e92998ba8325606635669e4e63839509d84db3e21911d0eb928f615b2d2d0f5d9ed6e711c2fed3785d3f1453988deef333a5e513ec48
-  data.tar.gz: eea07050d7df010b52615c475d4681749420c7b16687169c9e5ae3de5fbc6683daf939b9c17795442ed2589ad08dfddd745ad41b6d169f5238f521eaab638d3b
+  metadata.gz: 27d3c6eaf4e9d892238f41c7cce05bea11a639351069e80e130af6ad809916e89794dd41bbaf32b407c8560e49b8dc45c243fe7724d4aa36a3a1ce727dc61321
+  data.tar.gz: c3744c0b738859a27699dc444f9d27d3169b5d8ee91bd04be2d9296deca560050f9f7cce8db69b7cb980342ef94a1dd2f29e627030b04f7de990cb4adf0850f9

data/.gitattributes

@@ -0,0 +1,10 @@
+# Text files are stored with LF and checked out with LF, whatever the
+# editor on the machine does. Two of the documentation pages had drifted
+# to CRLF, which turned a three-line edit into a whole-file diff.
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.gif binary
+*.pdf binary
+*.gem binary

data/.gitignore

@@ -20,3 +20,6 @@ tags
 .solargraph.yml
 
 CLAUDE.md
+
+# git filter-branch leaves this behind; it is machinery, not source.
+.git-rewrite/

data/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## [1.11.0] - 2026-08
+
+Every input the tool accepts now draws, and every input it refuses says why.
+Line thickness follows the type size, so figures drawn at any font size keep
+the same balance between text and rules — existing figures come out about a
+fifth lighter than before.
+
+### Added
+- `--validate` checks input without drawing or writing a file, reporting a
+  machine-readable diagnosis on stdout and the verdict in the exit code.
+- `--notation` prints a short reference for the notation, which now ships
+  with the gem.
+- Errors carry a code, the offending label and an offset inside it, a
+  one-line fix, and whether rewriting the input could help. The message text
+  is unchanged. Each cause is confirmed by applying its fix and parsing
+  again, so a named cause is one whose fix is known to work.
+- A label may be nothing but a matrix: `[#(HEAD\tnoun#)]` had no spelling
+  before, since the enclosure rule took the `#` first.
+- `-f tikz` on the command line, which the documentation had offered while
+  the CLI rejected it. TikZ output also carries the line width, which it
+  had been accepting and dropping.
+- A gallery figure and a heading of its own for levelling the terminals with
+  `<>` joints.
+
+### Changed
+- Line width is a fraction of the font size rather than an absolute number.
+  `1` is five per cent of the type size at any size, and the scale runs from
+  `0.5` to `3.0` in halves where it ran `1` to `5` and meant `2` to `6`.
+  Lines were two units wide whatever the type size, which read as heavily as
+  a serif stem at 16 point and heavier still below that, and nothing thinner
+  was available.
+- On/off options accept every spelling of off. `mirror: "no"` reversed the
+  tree and `transparent: "0"` cut the background away, because anything but
+  `"off"` and `"false"` was read as on.
+- Option values are checked against the values the option takes. A value
+  nobody defines was taken and read as something else — `direction:
+  "left-to-right"` laid the tree out top to bottom. The CLI has always
+  refused these; the library did not, which left the web interface and other
+  programmatic callers unguarded.
+- Colour names are checked against the CSS colour names. A name nobody
+  defines passed validation and drew black.
+- Penn Treebank input converts in the library, not only in the CLI. Other
+  callers got no conversion and no error: `(S (NP the dog))` drew as one
+  leaf containing that text.
+- Font sizes go down to 6, which the web interface has always offered while
+  the documentation said 8.
+
+### Fixed
+- Validation accepted input that drawing then refused: a movement path with
+  one end, a tree too wide for a raster surface, a colour spec that fails
+  only when the label is parsed. It now generates the drawing and discards
+  it, going as far as the requested format can still refuse.
+- A malformed colour was reported as an unclosed enclosure, sending the
+  writer to fix a `#` that was never the problem.
+- A left-to-right matrix drew its brackets on top of the attribute names.
+- Text in front of a tree crashed symmetrization, and an empty argument was
+  read as a path to the current directory.
+- Overline was documented as missing from PNG output. It has been there.
+
 ## [1.10.0] - 2026-08
 
 A transitional release ahead of 2.0, which drops JPG/GIF output and the

data/CITATION.cff

@@ -11,8 +11,8 @@ repository-code: "https://github.com/yohasebe/rsyntaxtree"
 # Concept DOI: always resolves to the latest archived version on Zenodo
 doi: "10.5281/zenodo.21916150"
 license: MIT
-version: 1.10.0
-date-released: 2026-08-19
+version: 1.11.0
+date-released: 2026-08-20
 keywords:
   - linguistics
   - syntax tree

data/README.md

@@ -170,7 +170,8 @@ Usage:
 | `-f, --format` | Output format: png, svg, pdf, lsif, tikz (jpg and gif are deprecated) | `png` |
 | `-l, --leafstyle` | Leaf style: auto, triangle, bar, nothing | `auto` |
 | `-n, --fontstyle` | Font style: sans, serif, cjk, mono | `sans` |
-| `-s, --fontsize` | Font size: 8-26 | `16` |
+| `-s, --fontsize` | Font size: 6-26 | `16` |
+| `-i, --linewidth` | Line width relative to the font size: 0.5-3.0 (`1` = 5% of the font size) | `1.0` |
 | `-c, --color` | Color mode: modern, traditional, gray (black text, grey lines), off | `modern` |
 | `-p, --polyline` | Polyline connectors: on, off | `off` |
 | `-d, --direction` | Tree layout direction: ttb, ltr | `ttb` |
@@ -178,6 +179,8 @@ Usage:
 | `--hspacing` | Horizontal spacing factor, all layout modes (0.5-3.0) | `1.0` |
 | `--hyphen` | How a hyphen reads: markup (`-underline-`) or literal | `markup` |
 | `-m, --mirror` | Flip the tree horizontally (RTL convention): on, off | `off` |
+| `--validate` | Check the input without drawing: a JSON diagnosis on stdout, the verdict in the exit code | |
+| `--notation` | Print a short reference for the notation | |
 
 Run `rsyntaxtree -h` for the full list of options.
 

data/Rakefile

@@ -32,7 +32,12 @@ end
 
 Rake::Task["build"].enhance([:normalize_permissions])
 
-desc "Generate SVG and PNG example images locally"
+# For trying something out. It does NOT reproduce the committed gallery:
+# fontconfig resolves a family to whatever this machine has, so the same input
+# measures differently here than in the image the figures were drawn with. Run
+# over docs/assets it rewrites every PNG and about half the SVGs, none of it an
+# intended change. Use docker_generate to update the gallery.
+desc "Generate SVG and PNG example images locally (not for updating the gallery)"
 task :generate do
     require_relative "dev/generate_examples"
 end
@@ -47,7 +52,9 @@ task :docker_build do
     `docker build ./ -t rsyntaxtree_devel`
 end
 
-desc "Generate SVG and PNG example images using Docker image"
+# The gallery is drawn here and nowhere else, so that a figure depends on the
+# input and the options rather than on the fonts of whoever regenerated it.
+desc "Generate SVG and PNG example images using Docker image (the gallery)"
 task :docker_generate do
     docpath = File.expand_path(File.join(__dir__, "docs"))
     `docker build ./ -t rsyntaxtree_devel`

data/bin/rsyntaxtree

@@ -3,32 +3,37 @@
 
 require 'optimist'
 require 'yaml'
+require 'json'
 
 require_relative '../lib/rsyntaxtree'
 require_relative '../lib/rsyntaxtree/utils'
 require_relative '../lib/rsyntaxtree/format_converter'
 
+# "png, jpg, gif, pdf, svg, lsif, or tikz" — built once from the library's
+# own list so the three places that name the formats cannot drift apart.
+FORMAT_LIST_MESSAGE = FORMATS.join(", ").sub(/, ([^,]+)\z/, ', or \1')
+
 # Valid configuration keys and their validators
 CONFIG_VALIDATORS = {
   outdir: ->(v) { FileTest.directory?(v) ? nil : "must be an existing directory path" },
   outfilename: ->(v) { v.is_a?(String) ? nil : "must be a string" },
-  format: ->(v) { /\A(png|jpg|gif|pdf|svg|lsif)\z/ =~ v.to_s ? nil : "must be png, jpg, gif, pdf, svg, or lsif" },
-  leafstyle: ->(v) { /\A(auto|triangle|bar|nothing)\z/ =~ v.to_s ? nil : "must be auto, triangle, bar, or nothing" },
-  fontstyle: ->(v) { /\A(sans|serif|cjk|mono)\z/ =~ v.to_s ? nil : "must be sans, serif, cjk, or mono" },
-  fontsize: ->(v) { v.is_a?(Integer) && v >= 8 && v <= 26 ? nil : "must be in the range of 8-26" },
-  linewidth: ->(v) { v.is_a?(Integer) && v >= 1 && v <= 5 ? nil : "must be in the range of 1-5" },
+  format: ->(v) { FORMATS.include?(v.to_s) ? nil : "must be #{FORMAT_LIST_MESSAGE}" },
+  leafstyle: ->(v) { OPTION_VALUES[:leafstyle].include?(v.to_s) ? nil : "must be auto, triangle, bar, or nothing" },
+  fontstyle: ->(v) { OPTION_VALUES[:fontstyle].include?(v.to_s) ? nil : "must be sans, serif, cjk, or mono" },
+  fontsize: ->(v) { v.is_a?(Integer) && v >= 6 && v <= 26 ? nil : "must be in the range of 6-26" },
+  linewidth: ->(v) { v.is_a?(Numeric) && v >= 0.5 && v <= 3.0 ? nil : "must be in the range of 0.5-3.0" },
   vheight: ->(v) { v.is_a?(Numeric) && v >= 0.5 && v <= 5.0 ? nil : "must be in the range of 0.5-5.0" },
-  color: ->(v) { /\A(modern|traditional|gray|grey|on|off|true|false)\z/ =~ v.to_s ? nil : "must be modern, traditional, gray, or off" },
+  color: ->(v) { OPTION_VALUES[:color].include?(v.to_s) ? nil : "must be modern, traditional, gray, or off" },
   symmetrize: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
   transparent: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
   polyline: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
   hide_default_connectors: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
   mirror: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
-  tidy: ->(v) { /\A(off|symmetric|low|medium|high|on|compact|true|false)\z/ =~ v.to_s ? nil : "must be off, symmetric, low, medium, or high" },
+  tidy: ->(v) { OPTION_VALUES[:tidy].include?(v.to_s) ? nil : "must be off, symmetric, low, medium, or high" },
   hspacing: ->(v) { v.is_a?(Numeric) && v >= 0.5 && v <= 3.0 ? nil : "must be in the range of 0.5-3.0" },
   tidy_spacing: ->(v) { v.is_a?(Numeric) && v >= 0.5 && v <= 3.0 ? nil : "must be in the range of 0.5-3.0" },
-  direction: ->(v) { /\A(ttb|ltr)\z/ =~ v.to_s ? nil : "must be ttb or ltr" },
-  hyphen: ->(v) { /\A(markup|literal)\z/ =~ v.to_s ? nil : "must be markup or literal" }
+  direction: ->(v) { OPTION_VALUES[:direction].include?(v.to_s) ? nil : "must be ttb or ltr" },
+  hyphen: ->(v) { OPTION_VALUES[:hyphen].include?(v.to_s) ? nil : "must be markup or literal" }
 }.freeze
 
 # Validate configuration and return errors/warnings
@@ -102,11 +107,11 @@ opts = Optimist.options do
 
   opt :outdir, "Output directory", default: "./", short: :o
   opt :outfilename, "Output file base name", default: "syntree", short: :u
-  opt :format, "Output format: png, jpg, gif, pdf, svg, or lsif", default: "png", short: :f
+  opt :format, "Output format: #{FORMAT_LIST_MESSAGE}", default: "png", short: :f
   opt :leafstyle, "visual style of tree leaves: auto, triangle, bar, or nothing", default: "auto", short: :l
   opt :fontstyle, "Font style: sans, serif, cjk, mono", default: "sans", short: :n
-  opt :fontsize, "Size: 8-26", default: 16, short: :s
-  opt :linewidth, "Size: 1-5", default: 1, short: :i
+  opt :fontsize, "Size: 6-26", default: 16, short: :s
+  opt :linewidth, "Size: 0.5-3.0", default: 1.0, short: :i
   opt :vheight, "Connector Height: 0.5-5.0", default: 2.0, short: :v
   opt :color, "Color text and bars: modern, traditional, gray, or off", default: "modern", short: :c
   opt :symmetrize, "DEPRECATED alias of --tidy symmetric: on or off", default: "off", short: :y
@@ -119,25 +124,27 @@ opts = Optimist.options do
   opt :tidy_spacing, "DEPRECATED alias of --hspacing: 0.5-3.0", default: 1.0, short: :none
   opt :direction, "Tree layout direction: ttb (top-to-bottom) or ltr (left-to-right)", default: "ttb", short: :d
   opt :hyphen, "How a hyphen in a label reads: markup (-underline-) or literal (a hyphen; \-underline\- then underlines)", default: "markup", short: :none
+  opt :validate, "Validate the input without drawing or writing a file: print a machine-readable diagnosis (JSON) to stdout and report the result in the exit code", short: :none
+  opt :notation, "Print the notation reference to stdout and exit", short: :none
   opt :help, "This is a custom help message", short: :h
 end
 
 Optimist.die :outdir, "must be an exsting directory path" unless FileTest.directory?(opts[:outdir])
-Optimist.die :direction, "must be ttb or ltr" unless /\A(ttb|ltr)\z/ =~ opts[:direction]
-Optimist.die :hyphen, "must be markup or literal" unless /\A(markup|literal)\z/ =~ opts[:hyphen]
-Optimist.die :format, "must be png, pdf, svg, or lsif" unless /\A(png|jpg|gif|pdf|svg|lsif)\z/ =~ opts[:format]
-Optimist.die :leafstyle, "must be auto, triangle, bar, or nothing" unless /\A(auto|triangle|bar|nothing)\z/ =~ opts[:leafstyle]
-Optimist.die :fontstyle, "must be sans, serif, cjk, or mono" unless /\A(sans|serif|cjk|mono)\z/ =~ opts[:fontstyle]
-Optimist.die :fontsize, "must be in the range of 8-26" unless opts[:fontsize] >= 8 && opts[:fontsize] <= 26
-Optimist.die :linewidth, "must be in the range of 1-5" unless opts[:linewidth] >= 1 && opts[:linewidth] <= 5
-Optimist.die :color, "must be either modern, traditional, gray, or off" unless /\A(modern|traditional|gray|grey|on|off|true|false)\z/ =~ opts[:color]
+Optimist.die :direction, "must be ttb or ltr" unless OPTION_VALUES[:direction].include?(opts[:direction])
+Optimist.die :hyphen, "must be markup or literal" unless OPTION_VALUES[:hyphen].include?(opts[:hyphen])
+Optimist.die :format, "must be #{FORMAT_LIST_MESSAGE}" unless FORMATS.include?(opts[:format])
+Optimist.die :leafstyle, "must be auto, triangle, bar, or nothing" unless OPTION_VALUES[:leafstyle].include?(opts[:leafstyle])
+Optimist.die :fontstyle, "must be sans, serif, cjk, or mono" unless OPTION_VALUES[:fontstyle].include?(opts[:fontstyle])
+Optimist.die :fontsize, "must be in the range of 6-26" unless opts[:fontsize] >= 6 && opts[:fontsize] <= 26
+Optimist.die :linewidth, "must be in the range of 0.5-3.0" unless opts[:linewidth] >= 0.5 && opts[:linewidth] <= 3.0
+Optimist.die :color, "must be either modern, traditional, gray, or off" unless OPTION_VALUES[:color].include?(opts[:color])
 Optimist.die :symmetrize, "must be either on or off" unless /\A(on|off|true|false)\z/ =~ opts[:symmetrize]
 Optimist.die :vheight, "must be in the range of 0.5-5.0" if opts[:vheight] < 0.5 || opts[:vheight] > 5.0
 Optimist.die :transparent, "must be either on or off" unless /\A(on|off|true|false)\z/ =~ opts[:transparent]
 Optimist.die :polyline, "must be either on or off" unless /\A(on|off|true|false)\z/ =~ opts[:polyline]
 Optimist.die :hide_default_connectors, "must be either on or off" unless /\A(on|off|true|false)\z/ =~ opts[:hide_default_connectors]
 Optimist.die :mirror, "must be either on or off" unless /\A(on|off|true|false)\z/ =~ opts[:mirror]
-Optimist.die :tidy, "must be off, symmetric, low, medium, or high" unless /\A(off|symmetric|low|medium|high|on|compact|true|false)\z/ =~ opts[:tidy]
+Optimist.die :tidy, "must be off, symmetric, low, medium, or high" unless OPTION_VALUES[:tidy].include?(opts[:tidy])
 Optimist.die :hspacing, "must be in the range of 0.5-3.0" if opts[:hspacing] < 0.5 || opts[:hspacing] > 3.0
 Optimist.die :tidy_spacing, "must be in the range of 0.5-3.0" if opts[:tidy_spacing] < 0.5 || opts[:tidy_spacing] > 3.0
 
@@ -164,7 +171,10 @@ if %w[jpg gif].include?(string_opts[:format])
   warn "Warning: #{string_opts[:format].upcase} output is deprecated and will be removed in RSyntaxTree 2.0. Use PNG instead."
 end
 
-data = if ARGV[0] && File.exist?(File.expand_path(ARGV[0]))
+# An argument names a file only if it really is one: File.exist? on an
+# expanded empty string answers for the current directory, and reading that
+# as the tree ended the run with a Ruby error.
+data = if ARGV[0] && !ARGV[0].empty? && File.file?(File.expand_path(ARGV[0]))
          File.read ARGV[0]
        elsif ARGV[0]
          ARGV[0]
@@ -177,8 +187,26 @@ data = if ARGV[0] && File.exist?(File.expand_path(ARGV[0]))
 # Auto-convert Penn TreeBank format to bracket notation
 data = RSyntaxTree::FormatConverter.to_bracket(data) if data
 
+if opts[:notation]
+  puts File.read(File.expand_path("../lib/rsyntaxtree/notation_core.md", __dir__))
+  exit 0
+end
+
+# 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
+  puts JSON.pretty_generate(diagnosis)
+  exit(diagnosis["ok"] ? 0 : 1)
+end
+
 begin
-  RSyntaxTree::RSGenerator.check_data(data)
+  RSyntaxTree::RSGenerator.check_data(data, string_opts)
 rescue RSTError => e
   warn e
   exit 1
@@ -189,7 +217,7 @@ begin
   rsg = RSyntaxTree::RSGenerator.new(string_opts)
   ext = string_opts[:format]
   outfilename = string_opts[:outfilename] || "syntree"
-  file_ext = ext == "lsif" ? "lsif.json" : ext
+  file_ext = FORMAT_EXTENSIONS[ext] || ext
   filepath = File.expand_path(string_opts[:outdir]) + "/#{outfilename}.#{file_ext}"
   draw_method = "draw_#{ext}"
   output = rsg.send(draw_method)

data/lib/rsyntaxtree/base_graph.rb

@@ -241,6 +241,11 @@ module RSyntaxTree
       target = @element_list.get_id(id)
       if target.children.empty?
         parent = @element_list.get_id(target.parent)
+        # A childless element with no parent is a root standing alone —
+        # text in front of the tree makes one. It has no siblings to match
+        # widths with, so its own width is already the answer.
+        return target.width if parent.nil?
+
         accum_array = []
         parent.children.each do |c|
           accum_array << @element_list.get_id(c).width
@@ -416,7 +421,7 @@ module RSyntaxTree
       x0 = node.horizontal_indent
       x1 = node.horizontal_indent + node.content_width
       if [:brackets, :rectangle, :brectangle].include?(node.enclosure)
-        ext = @global[:h_gap_between_nodes] / 2 + ((@linewidth || 1) + BLINE_SCALING)
+        ext = @global[:h_gap_between_nodes] / 2 + @global[:stroke_bold]
         x0 -= ext
         x1 += ext
       end

data/lib/rsyntaxtree/color_names.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+#==========================
+# color_names.rb
+#==========================
+#
+# The color names a label may use: the CSS Color 4 named colors plus
+# "transparent", which is what librsvg accepts when it paints. Validation
+# checks a name against this list because an unknown name does not fail —
+# it silently comes out black, which breaks the promise that what
+# validates also draws. The list is a fixed web standard, so it is
+# embedded rather than asked from an outside source that cannot answer
+# (fontconfig has no color names, and librsvg never rejects one).
+module RSyntaxTree
+  COLOR_NAMES = [
+    "aliceblue", "antiquewhite", "aqua", "aquamarine", "azure", "beige",
+    "bisque", "black", "blanchedalmond", "blue", "blueviolet", "brown",
+    "burlywood", "cadetblue", "chartreuse", "chocolate", "coral", "cornflowerblue",
+    "cornsilk", "crimson", "cyan", "darkblue", "darkcyan", "darkgoldenrod",
+    "darkgray", "darkgreen", "darkgrey", "darkkhaki", "darkmagenta", "darkolivegreen",
+    "darkorange", "darkorchid", "darkred", "darksalmon", "darkseagreen", "darkslateblue",
+    "darkslategray", "darkslategrey", "darkturquoise", "darkviolet", "deeppink", "deepskyblue",
+    "dimgray", "dimgrey", "dodgerblue", "firebrick", "floralwhite", "forestgreen",
+    "fuchsia", "gainsboro", "ghostwhite", "gold", "goldenrod", "gray",
+    "green", "greenyellow", "grey", "honeydew", "hotpink", "indianred",
+    "indigo", "ivory", "khaki", "lavender", "lavenderblush", "lawngreen",
+    "lemonchiffon", "lightblue", "lightcoral", "lightcyan", "lightgoldenrodyellow", "lightgray",
+    "lightgreen", "lightgrey", "lightpink", "lightsalmon", "lightseagreen", "lightskyblue",
+    "lightslategray", "lightslategrey", "lightsteelblue", "lightyellow", "lime", "limegreen",
+    "linen", "magenta", "maroon", "mediumaquamarine", "mediumblue", "mediumorchid",
+    "mediumpurple", "mediumseagreen", "mediumslateblue", "mediumspringgreen", "mediumturquoise", "mediumvioletred",
+    "midnightblue", "mintcream", "mistyrose", "moccasin", "navajowhite", "navy",
+    "oldlace", "olive", "olivedrab", "orange", "orangered", "orchid",
+    "palegoldenrod", "palegreen", "paleturquoise", "palevioletred", "papayawhip", "peachpuff",
+    "peru", "pink", "plum", "powderblue", "purple", "rebeccapurple",
+    "red", "rosybrown", "royalblue", "saddlebrown", "salmon", "sandybrown",
+    "seagreen", "seashell", "sienna", "silver", "skyblue", "slateblue",
+    "slategray", "slategrey", "snow", "springgreen", "steelblue", "tan",
+    "teal", "thistle", "tomato", "transparent", "turquoise", "violet",
+    "wheat", "white", "whitesmoke", "yellow", "yellowgreen",
+  ].freeze
+end

data/lib/rsyntaxtree/element.rb

@@ -9,6 +9,7 @@
 
 require_relative "markup_parser"
 require_relative "utils"
+require_relative "color_names"
 
 module RSyntaxTree
   class Element
@@ -37,22 +38,23 @@ module RSyntaxTree
       @fontsize = fontsize
       @raw_content = content.sub(/\^?(?:\+-?>?<?\d+)+\^?\z/, '')
 
-      parsed = Markup.parse(@global[:literal_hyphen] ? swap_hyphen_markup(content) : content)
+      parsed = Markup.parse(prepare_markup(content))
 
       if parsed[:status] == :success
         results = parsed[:results]
       else
         error_text = +"Error: input text contains an invalid string"
         error_text += "\n > " + content
-        raise RSTError, error_text
+        raise RSTError.new(error_text, **markup_failure_details(content, parsed[:charpos]))
       end
       @content = results[:contents]
-      @paths = results[:paths]
       @enclosure = results[:enclosure]
       @triangle = results[:triangle]
       @color = results[:color]
       @region = results[:region]
       @region_color = results[:region_color]
+      validate_color!(@color, content)
+      validate_color!(@region_color, content)
 
       @contains_phrase = false
       setup
@@ -81,13 +83,19 @@ module RSyntaxTree
     # alone: a line of nothing but hyphens is the horizontal rule, and the dash
     # in a path suffix (+-1, +->2) is what makes that path dashed. Swapping
     # those turned a rule into the text "---" without a word of complaint.
-    def swap_hyphen_markup(text)
+    # Split a label into lines with the trailing path markers detached, so
+    # hyphen handling can spare the two places a run of hyphens means
+    # something else: a `---` rule line of its own, and the `+-2` markers
+    # at the end. Shared by swap_hyphen_markup and escape_hyphens.
+    def self.hyphen_safe_lines(text)
       path = text[/\^?(?:\+-?>?<?\d+)+\^?\z/]
       body = path ? text[0...-path.length] : text
-      swapped = body.split('\n', -1).map do |line|
-        /\A-{3,}\z/.match?(line) ? line : swap_hyphens(line)
-      end.join('\n')
-      swapped + path.to_s
+      [body.split('\n', -1), path.to_s]
+    end
+
+    def swap_hyphen_markup(text)
+      lines, path = Element.hyphen_safe_lines(text)
+      lines.map { |line| /\A-{3,}\z/.match?(line) ? line : swap_hyphens(line) }.join('\n') + path
     end
 
     def swap_hyphens(text)
@@ -98,6 +106,114 @@ module RSyntaxTree
       text.gsub('\\-', placeholder).gsub("-", '\\-').gsub(placeholder, "-")
     end
 
+    # Escape the hyphens that open an underline. Shares its exemptions with
+    # swap_hyphen_markup through hyphen_safe_lines.
+    def self.escape_hyphens(text)
+      lines, path = hyphen_safe_lines(text)
+      lines.map { |line| /\A-{3,}\z/.match?(line) ? line : line.gsub(/(?<!\\)-/, '\\-') }.join('\n') + path
+    end
+
+    # What the markup parser is actually handed: under hyphen: literal a
+    # hyphen and its escape swap roles before parsing.
+    def prepare_markup(text)
+      @global[:literal_hyphen] ? swap_hyphen_markup(text) : text
+    end
+
+    # One candidate repair per way of getting the notation wrong, tried in
+    # order. Each is a whole edit of the label, not a pattern to recognise:
+    # the diagnosis below applies one and asks the parser whether the label
+    # now parses, so a cause is only ever reported when its fix is known to
+    # work. That keeps the list from drifting away from the grammar the way
+    # a set of hand-written patterns would — the grammar is the judge.
+    MARKUP_REPAIRS = [
+      # A malformed color spec ('@' then a bad name or a bad hex) leaves a
+      # bare '#' or '@' behind that the enclosure repair below would happily
+      # blame itself for. Tried first, so a color mistake is named as one.
+      [:invalid_color,
+       ->(s) { s.sub(/\A%?@(?:#[0-9a-zA-Z]+|[a-zA-Z]+)?:/, "") },
+       "A color is @name: with a CSS color name, or @#rgb: / @#rrggbb: with 3 or 6 hex digits (e.g. @blue:VP, @#3af:VP)."],
+      [:angle_brackets,
+       ->(s) { s.gsub(/(?<!\\)<([^<>]*[^<>\d][^<>]*)>/) { "〈#{$1}〉" } },
+       "'<' and '>' mark whitespace here, not a list. Write the angle bracket characters themselves: 〈NP〉, 'hand〈SUBJ,OBJ〉'."],
+      [:bare_hyphen,
+       ->(s) { Element.escape_hyphens(s) },
+       "A hyphen opens an underline. Escape it (e.g. f\\-structure, V\\-bar) or set the hyphen option to literal."],
+      # Every other repair leaves a label it has nothing to do with exactly
+      # as it was, and an unchanged label is not tried. Appending always
+      # changes one, so this one asks first whether there is an unclosed
+      # matrix at all: without that, a label of "^" parses once "#)" is
+      # stuck on the end, and would be reported as a matrix left open.
+      [:unclosed_matrix,
+       ->(s) { s.scan("#(").size > s.scan("#)").size ? s + "#)" : s },
+       "A matrix opened with '#(' is never closed with '#)'."],
+      # Neutralising every occurrence of one character, rather than adding a
+      # closing one, locates the culprit wherever it sits in the label — an
+      # opener left unclosed halfway down a matrix is not fixed by appending.
+      *{ "*" => "A '*' decoration (italic or bold) is never closed.",
+         "|" => "A '|' box is never closed.",
+         "_" => "A '_' subscript or superscript is never closed.",
+         "{" => "A '{...}' circle is never closed.",
+         "=" => "An '=' overline is never closed.",
+         "~" => "A '~' strikethrough is never closed.",
+         "#" => "A '#' enclosure is not one of #, ## or ###, or a matrix is left open.",
+         "<" => "'<' and '>' mark whitespace: <> is one space, <3> is three." }
+        .map { |ch, hint| [:unclosed_markup, ->(s) { s.gsub(/(?<!\\)#{Regexp.escape(ch)}/) { "\\#{ch}" } }, hint] },
+      [:stray_triangle,
+       ->(s) { s.sub(/\A\^+/, "^") }, "Only one '^' may prefix a label."],
+      [:incomplete_path,
+       ->(s) { s.sub(/(?<!\\)\+>?<?\z/, "") },
+       "A path marker needs a number: write +1, or +>1 for the arrowhead."]
+    ].freeze
+
+    # Turn a Markup.parse failure into structured error attributes: a code
+    # for machines, the label and the offset inside it for people, a fix
+    # that has been checked to work, and whether rewriting could help.
+    def markup_failure_details(label, charpos)
+      details = { label: label, position: charpos }
+
+      # Nothing left to parse: the raw spaces around it took the whole label
+      # away, one of them starting the split and the next ending it.
+      if label.strip.empty?
+        return details.merge(code: :label_split,
+                             hint: "Raw spaces left this label empty. Write a space inside a label as <> (e.g. 〈<>NP<>〉).",
+                             retryable: true)
+      end
+
+      MARKUP_REPAIRS.each do |code, repair, hint|
+        repaired = repair.call(label)
+        next if repaired == label
+        # Through the same preprocessing the real parse uses, or a label
+        # under hyphen: literal would be judged against a different string.
+        next unless Markup.parse(prepare_markup(repaired))[:status] == :success
+
+        return details.merge(code: code, hint: hint, retryable: true)
+      end
+
+      # No single repair worked. In practice this is where two mistakes in
+      # one label land — each of them one this could have named alone — so
+      # it is the most fixable bucket, not the least: still retryable, with
+      # a hint that admits no one cause was found rather than naming a wrong
+      # one. retryable: false is for what no rewriting reaches.
+      details.merge(code: :invalid_markup,
+                    hint: "No single cause fits, which usually means more than one mistake in this label. Check that *, _, =, ~, |, { and #(...#) are paired, that hyphens are escaped, and that 〈 〉 are the angle bracket characters.",
+                    retryable: true)
+    end
+
+    # A hex color is already constrained by the grammar; a named color is
+    # checked against the names librsvg can paint, because an unknown name
+    # does not fail downstream — it silently comes out black.
+    def validate_color!(color, content)
+      return if color.nil? || color.start_with?("#")
+      return if COLOR_NAMES.include?(color.downcase)
+
+      raise RSTError.new(+"Error: input text contains an unknown color '#{color}'" \
+                         "\n > #{content}",
+                         code: :unknown_color,
+                         label: content,
+                         hint: "Use a CSS color name or a hex code: @blue:VP, @#3af:VP, @#33aaff:VP.",
+                         retryable: true)
+    end
+
     def setup
       layout = measure_lines(@content)
       @text_width = layout[:width]

data/lib/rsyntaxtree/markup_parser.rb

@@ -79,8 +79,18 @@ class MarkupParser < Parslet::Parser
 
   rule(:markup) { (matrix | tabstop | text | decoration | shape | bstroke) }
 
+  # A label that is one whole matrix. The enclosure rules in :lines would
+  # eat the '#' of '#(' before the matrix rule could see it, so a matrix
+  # could only live inside a label, never be one. Trying this first is
+  # safe: a label starting '#(' that contains the closing '#)' could never
+  # parse before (a bare '#' is not consumable outside a matrix), so the
+  # only inputs this newly reaches are ones that used to fail. A matrix
+  # followed by anything but a path or the end does not match here and
+  # falls through to the enclosure reading, exactly as before.
+  rule(:whole_label_matrix) { matrix >> (str('+') | cr | eof).present? }
+
   rule(:line) { (cr.as(:extracr) | border | bborder | markup.repeat(1).as(:line) >> (cr | eof | str('+').present?)) }
-  rule(:lines) { triangle.maybe.as(:triangle) >> (brectangle | rectangle | brackets).maybe.as(:enclosure) >> region.maybe.as(:region) >> color_spec.maybe.as(:color) >> line.repeat(1) >> path.repeat(0).as(:paths) >> (cr | eof) }
+  rule(:lines) { triangle.maybe.as(:triangle) >> (whole_label_matrix.as(:whole_label_matrix) | ((brectangle | rectangle | brackets).maybe.as(:enclosure) >> region.maybe.as(:region) >> color_spec.maybe.as(:color) >> line.repeat(1))) >> path.repeat(0).as(:paths) >> (cr | eof) }
   root :lines
 end
 
@@ -177,9 +187,6 @@ module Markup
     rule(circle: subtree(:text)) {
       text[:decoration] << :circle; text
     }
-    rule(math: subtree(:text)) {
-      text[:decoration] << :math; text
-    }
     rule(border: simple(:border)) {
       { type: :border }
     }
@@ -199,15 +206,28 @@ module Markup
     }
   end
 
+  # Largest charpos anywhere in a parse-failure cause tree: the position
+  # the parser actually reached before giving up.
+  def deepest_charpos(cause, best = 0)
+    pos = cause.respond_to?(:pos) && cause.pos ? cause.pos.charpos : 0
+    best = [best, pos].max
+    cause.children&.each { |child| best = deepest_charpos(child, best) }
+    best
+  end
+
   def parse(txt)
     begin
       parsed = @parser.parse(txt)
-    rescue Parslet::ParseFailed
-      # puts e.parse_failure_cause.ascii_tree
-      return { status: :error, text: txt }
+    rescue Parslet::ParseFailed => e
+      # The cause is kept: the deepest node of the failure tree is where the
+      # parse actually got stuck, which is what structured errors report.
+      return { status: :error, text: txt, charpos: deepest_charpos(e.parse_failure_cause) }
     end
 
     applied = @evaluator.apply(parsed)
+    # A label holding a single named part (a whole-label matrix, nothing
+    # else) comes back as one hash, not a one-element array.
+    applied = [applied] unless applied.is_a?(Array)
 
     results = { enclosure: :none, triangle: false, paths: [], contents: [], color: nil, region: false, region_color: nil }
     applied.each do |h|
@@ -239,11 +259,13 @@ module Markup
         results[:color] = color_value
       end
       results[:contents] << h if h[:type] == :text || h[:type] == :border || h[:type] == :bborder
+      # A label that is one whole matrix arrives under its own key in the
+      # top-level hash; the matrix element becomes the label's only line.
+      results[:contents] << { type: :text, elements: [h[:whole_label_matrix]] } if h[:whole_label_matrix]
     end
     { status: :success, results: results }
   end
 
-  module_function :parse
+  module_function :parse, :deepest_charpos
 end
 
-# pp results = Markup.parse('^#\_\#\+あり\-がとう**_X_**\\n----\\n933\\n__|Y|__+>3+2+1343+>5464')