rsyntaxtree 1.13.2 → 2.0.0

data/lib/rsyntaxtree/element.rb

@@ -13,7 +13,7 @@ require_relative "color_names"
 
 module RSyntaxTree
   class Element
-    attr_accessor :rule_name, :id, :parent, :type, :level, :width, :height, :content, :content_width, :text_width, :content_height, :horizontal_indent, :vertical_indent, :triangle, :enclosure, :children, :font, :fontsize, :contains_phrase, :path, :color, :raw_content, :region, :region_color
+    attr_accessor :ink_top, :ink_bottom, :rule_name, :label_with_rule_name, :id, :parent, :type, :level, :width, :height, :content, :content_width, :text_width, :content_height, :horizontal_indent, :vertical_indent, :triangle, :enclosure, :children, :font, :fontsize, :contains_phrase, :path, :color, :raw_content, :region, :region_color
 
     # names_a_rule says the content is a mother's label rather than a leaf's
     # text. Only a mother has a step under it for a name to sit beside, and a
@@ -42,7 +42,11 @@ module RSyntaxTree
       @fontset = fontset
       @fontsize = fontsize
       # In a derivation the label may carry the name of the rule that produced
-      # it, written after a column break: `S/NP\t\>B`. The name belongs beside
+      # it, written after a column break: `S/NP\t>B`. The name is taken out
+      # before the label is read as markup, so it is drawn exactly as written —
+      # `>` and `<` need no escaping there, and escaping them puts the backslash
+      # in the figure. (This example carried one, which is the opposite of what
+      # the gallery's derivations do.) The name belongs beside
       # the rule rather than beside the result, so it comes out of the label
       # here, before the label is measured, and BaseGraph draws it at the end
       # of the rule.
@@ -51,6 +55,11 @@ module RSyntaxTree
         name = at && content[(at + 2)..].to_s.strip
         if name && !name.empty?
           @rule_name = name
+          # Kept whole, because whether this node has daughters — and so
+          # whether it names a rule at all — is not known until the tree
+          # is built. StringParser puts the label back if it turns out
+          # there was no step for the name to belong to.
+          @label_with_rule_name = content
           content = content[0...at]
         end
       end
@@ -300,6 +309,10 @@ module RSyntaxTree
           row_holds_text = content[:elements].any? do |e|
             (e[:decoration] & [:box, :circle, :bar]).empty? && !e[:text].to_s.strip.empty?
           end
+          # True until something is drawn in the current column. A tabstop
+          # opens the next one, so a block that starts a column is at the
+          # start of a cell however many columns came before it.
+          cell_start = true
           content[:elements].each do |e|
             # A nested matrix is measured by the same code one level down, and
             # reports the size of the block it will occupy in this row: its own
@@ -308,7 +321,18 @@ module RSyntaxTree
               inner = measure_lines(e[:matrix], nested: true)
               e[:matrix_width] = inner[:width]
               e[:matrix_height] = inner[:height]
-              e[:width] = inner[:width] + matrix_bracket_room * 2
+              # A block that opens a cell needs nothing in front of it: the
+              # column it starts is already held clear. One that follows
+              # something in the same cell — the tag on a shared value, as in
+              # AGR |1| [ ... ] — was drawn with its bracket on the ink before
+              # it, because a run is spaced for the glyph that comes next and
+              # a bracket is not a glyph.
+              # As much room in front of the bracket as the bracket keeps
+              # inside it, so the two sides of it look alike. Half as much
+              # left it looking crowded from the outside.
+              e[:matrix_lead] = cell_start ? 0 : matrix_bracket_room
+              cell_start = false
+              e[:width] = inner[:width] + matrix_bracket_room * 2 + e[:matrix_lead]
               # Two separate allowances. The block is padded inside its own
               # brackets, above and below, and that padding is part of the row.
               # The gap that keeps the block clear of the rows either side is
@@ -326,6 +350,14 @@ module RSyntaxTree
               next
             end
 
+            # A tabstop opens the next column; anything else puts ink in the
+            # one being filled.
+            if e[:decoration].to_a.include?(:tabstop)
+              cell_start = true
+            elsif !e[:text].to_s.empty?
+              cell_start = false
+            end
+
             text = e[:text]
             # Handle escaped square brackets
             text = text.gsub('\\[', '[')

data/lib/rsyntaxtree/lsif_graph.rb

@@ -291,12 +291,18 @@ module RSyntaxTree
               connector_height: @params[:vheight],
               horizontal_spacing: @params[:hspacing] || 1.0,
               line_width: @params[:linewidth],
-              # The layout scale the figure was drawn on. symmetrize is kept
-              # for readers of older files; tidy: "symmetric" supersedes it.
+              # The layout scale the figure was drawn on. Files written
+              # before 2.0 carry a separate symmetrize flag beside it; the
+              # scale is what it meant, and it is all that is written now.
               tidy: @params[:tidy] || "off",
-              symmetrize: @params[:symmetrize],
               mirror: @params[:mirror] == true,
               direction: @params[:direction] || "ttb",
+              # Degrees, positive leaning the top right. The geometry below
+              # is the unsheared layout — the shear is applied at render — so
+              # a reader who wants the drawn look applies it, and one who
+              # wants the layout ignores it.
+              shear: (@params[:shear] || 0).to_f,
+              vmargin: (@params[:vmargin] || 0.4).to_f,
               # Which of the two readings of a hyphen the input was parsed
               # under. The input is recorded verbatim above, and the same
               # string means different things under the two, so a reader

data/lib/rsyntaxtree/markup_parser.rb

@@ -5,8 +5,13 @@ require 'parslet'
 class MarkupParser < Parslet::Parser
   rule(:cr) { str('\\n') }
   rule(:eof) { any.absent? }
-  rule(:border) { match('[^\-]').absent? >> str('-').repeat(3).as(:border) >> (eof | cr) }
-  rule(:bborder) { match('[^=]').absent? >> str('=').repeat(3).as(:bborder) >> (eof | cr) }
+  rule(:border) { rule_line >> (eof | cr) }
+  rule(:bborder) { double_rule_line >> (eof | cr) }
+  # The rule itself, without what ends the line. A matrix ends its rows on
+  # its own closing delimiter as well as on a line break, so it supplies its
+  # own terminator; folding one in here would have the two consume it twice.
+  rule(:rule_line) { match('[^\-]').absent? >> str('-').repeat(3).as(:border) }
+  rule(:double_rule_line) { match('[^=]').absent? >> str('=').repeat(3).as(:bborder) }
 
   rule(:brectangle) { str('###') }
   rule(:rectangle) { str('##') }
@@ -15,7 +20,14 @@ class MarkupParser < Parslet::Parser
 
   # Color specification: @colorname: or @#hexcode:
   rule(:color_name) { match('[a-zA-Z]').repeat(1) }
-  rule(:color_hex) { str('#') >> match('[0-9a-fA-F]').repeat(3, 6) }
+  # Three digits or six, which is what every message about colour in this
+  # codebase already says. The rule used to be written as "three to six", so
+  # four and five passed the parser, passed the validator (which does not look
+  # at a value beginning with '#' at all), and went into the SVG — where
+  # librsvg cannot read them and draws the label black, with nothing reported.
+  # Six first: on a six-digit value the three-digit branch matches and then
+  # the ':' is not there to be found.
+  rule(:color_hex) { str('#') >> (match('[0-9a-fA-F]').repeat(6, 6) | match('[0-9a-fA-F]').repeat(3, 3)) }
   rule(:color_spec) { str('@') >> (color_hex | color_name).as(:color_value) >> str(':') }
 
   # Region shade: '%' marks the node so that the whole subtree it governs
@@ -72,7 +84,7 @@ class MarkupParser < Parslet::Parser
   # bare brackets would be read as tree structure and bare parentheses appear
   # in labels too often to claim.
   rule(:matrix) { str('#(') >> matrix_line.repeat(1).as(:matrix) >> str('#)') }
-  rule(:matrix_line) { matrix_markup.repeat(1).as(:line) >> (cr | str('#)').present?) }
+  rule(:matrix_line) { (rule_line | double_rule_line | matrix_markup.repeat(1).as(:line)) >> (cr | str('#)').present?) }
   rule(:matrix_markup) { (matrix | tabstop | matrix_text | decoration | shape | bstroke) }
   # Text inside a matrix stops at the closing delimiter as well.
   rule(:matrix_text) { (escaped | (str('#)').absent? >> non_escaped)).repeat(1).as(:text) }

data/lib/rsyntaxtree/notation_core.md

@@ -1,52 +1,118 @@
-RSyntaxTree notation, in brief.
+RSyntaxTree notation, on one page.
 
 A tree is labeled brackets: [S [NP the cat] [VP sat]]. The label follows the
-opening bracket; children follow the label.
-
-Within a label:
-- `\n` breaks a line; `\t` separates columns, and every line is cut at the
-  same points, so the columns line up down the label. (`\t` is the two
-  characters backslash and t, not a real tab.)
-- `#label` draws square brackets around the whole label; `##label` a
-  rectangle. `#( ... #)` nests a matrix inside a label, to any depth.
-- `*italic*`, `**bold**`, `x_sub_`, `x__super__`, `|x|` in a box, `{x}` in a
-  circle, `---` a horizontal rule.
-- `+n` on two nodes links them with a movement arrow; `+>n` puts the
-  arrowhead on that end.
-
-Four traps, because these characters already mean something:
-- `<` and `>` are never angle brackets in this notation: `<>` is one space,
-  `<3>` is three. Wherever linguistics uses angle brackets — a list ⟨NP⟩,
-  an argument structure like 'hand⟨SUBJ,OBJ⟩', anything — write the
-  characters ⟨ and ⟩ themselves (U+27E8 and U+27E9):
-  SPR\t⟨<>NP<>⟩    PRED\t'hand⟨SUBJ,OBJ⟩'
-- `-` opens and closes an underline, so a bare hyphen in ANY word is an
-  error: V-bar, f-structure, HEAD-DTR. Write `V'`, or escape the hyphen:
-  `V\-bar`, `f\-structure`, `HEAD\-DTR`.
-- A raw space is safe in a one-line label, and unreliable in a label that
-  has `\n` or `\t` in it: there it splits a value that carries markup, and
-  it breaks a matrix nested with `#( ... #)`. Since matrices are exactly the
-  multi-line case, write a space as `<>` inside any label with columns:
-  'a<>toy', not 'a toy'.
-- Parentheses are not brackets, and this is silent: `(S (NP ...))` raises no
-  error and draws one leaf with that text in it. Convert it first.
-
-An attribute-value matrix is columns plus an enclosure:
-
-    [#*word*\
-      HEAD\t*verb*\
-      SPR\t⟨<>NP<>⟩\
-      COMPS\t⟨<>⟩
-    ]
+opening bracket; children follow the label. Parentheses are read as Penn
+Treebank notation and converted: (S (NP the cat) (VP sat)) draws the same tree.
+
+## What already means something
+
+The characters that bite, first. A mistake the tool can see is refused with a
+hint; everything below is taken silently, and the figure that draws is not the
+figure that was meant.
+
+- `<>` is one space and `<3>` is three, everywhere — never angle brackets.
+  Where linguistics wants the brackets themselves, write ⟨ and ⟩ (U+27E8/9):
+  SPR\t⟨<>NP<>⟩, 'hand⟨SUBJ,OBJ⟩'. A label written <NP> is refused with this
+  advice; a stray <3> simply draws three spaces. No text face carries these
+  two characters, so whatever the machine falls back to draws them — they
+  will not quite match the letters beside them, and how far off they look
+  depends on the fonts installed.
+- A pair of hyphens underlines what stands between them: well-made-word draws
+  "made" underlined. (A lone hyphen is refused with a hint.) Write `\-` for a
+  hyphen — V\-bar, HEAD\-DTR — or set the hyphen option to literal.
+- A raw space is safe in a one-line label and unreliable in a label that has
+  `\n` or `\t` in it: there it can split a value that carries markup, and it
+  breaks a nested #( ... #) matrix. Inside any label with columns, write a
+  space as `<>`: 'a<>toy', not 'a toy'.
+- A straight apostrophe is typeset as the curly ’ (U+2019).
+- A backslash takes the character after it, whatever it is: \q draws q, and
+  C:\path draws C:path. A backslash itself is \\.
+- The prefixes of a label compose in one order, and only this one:
+  `^` → `#`/`##`/`###` → `%` → `@color:`. So ^#%@red:NP is read whole, while
+  @red:%NP leaves the % as a literal character and silently drops the shade.
+- A rule name (for derivations) is written after the label's last `\t`, as in
+  [S/NP\t>B ...], and needs the derivation option ON — with it off the name is
+  drawn as a column. The name is taken out before markup runs, so `>` and `<`
+  need no escaping there and `\>` would put the backslash in the figure. A
+  label that also carries `\n` keeps all its columns instead.
+
+## What there is
+
+Structure:
+
+| what                                   | how it is written |
+|----------------------------------------|-------------------|
+| a node with children                   | [S [NP the cat] [VP sat]] |
+| a phrase under one leaf (triangle)     | [NP a toy] — one word, forced: [NP ^cats] |
+| an invisible joint, to align leaves    | a label of only <>, as in [X [<> [Y y]] [Z z]] |
+| a movement path (dashed)               | [S [NP a+1] [VP [V b] [NP c+1]]] |
+| the same, with an arrowhead            | write +>1 on the end the arrow points at |
+| an extra straight connector            | +-1 on two nodes; +->1 for an arrowhead |
 
-A value can be another matrix. Nest it with `#( ... #)`, never with square
-brackets — those are read as tree structure:
+Inside a label:
+
+| what                                   | how it is written |
+|----------------------------------------|-------------------|
+| italic, bold, both                     | *x*, **x**, ***x*** |
+| subscript, superscript                 | x_i_, x__2__ |
+| small capitals                         | H___EAD___ |
+| overline, underline, strikethrough     | =x=, -x-, ~x~ |
+| a line break; a blank line             | a\nb (or a\ b); \n\n |
+| columns, aligned down the label        | HEAD\t*verb*\nSPR\t⟨<>⟩ |
+| a horizontal rule across the label     | a line of --- (or === for a double rule) |
+| boxed, circled text                    | |1|, {2} — more than one character draws a capsule |
+| empty and hatched boxes and circles    | ||, {}, |/|, {/} |
+| bar and arrows as symbols              | --, ->, <-, <-> — bold with *...*, as in *->* |
+
+Around a label:
+
+| what                                   | how it is written |
+|----------------------------------------|-------------------|
+| square brackets, rectangle, bold       | #NP, ##NP, ###NP |
+| a feature matrix as a value            | #(HEAD\tnoun#), nested to any depth |
+| a whole label that is one matrix       | [#(CAT\tS#) [#(CAT\tNP#) Kim] [#(CAT\tVP#) sleeps]] |
+| a region shade behind the subtree      | %NP, coloured: %@blue:NP |
+| a colour                               | @red:NP, @#3af:NP, @#33aaff:NP (3 or 6 hex digits) |
+
+An attribute-value matrix is columns plus an enclosure, and a value can be
+another matrix — nested with #( ... #), never with square brackets, which are
+read as tree structure:
 
     [#PRED\t'hand⟨SUBJ,OBJ⟩'\
       TENSE\tpast\
       SUBJ\t#(PRED\t'David'#)
     ]
 
-A movement arrow links the two nodes that carry the same number:
+Options (the command line spells them --like-this):
+
+| option     | what it decides |
+|------------|-----------------|
+| format     | png, svg, pdf, tikz, lsif |
+| fontstyle  | sans, serif, mono, cjk |
+| fontsize   | 6–26 |
+| color      | modern, traditional, off, gray |
+| linewidth  | every line's weight, 0.5–3.0, as a ratio of the font size |
+| leafstyle  | auto, bar, nothing — what joins a node to its leaf |
+| direction  | ttb, ltr, btt |
+| mirror     | flip the finished layout, for RTL scripts |
+| tidy       | off, symmetric, low, medium, high — how tightly subtrees pack |
+| hspacing   | how far apart sisters sit, 0.5–3.0 |
+| vheight    | how far apart levels sit, 0.5–5.0 |
+| polyline   | draw each connector as two right angles rather than a slanted line |
+| hide_default_connectors | draw no parent-to-child lines, leaving only the ones written with +-n — how a lattice or a network is drawn |
+| transparent | leave the background clear instead of painting it white |
+| derivation | one rule across the daughters, categorial-grammar style |
+| hyphen     | markup (hyphens underline) or literal (hyphens are hyphens) |
+| shear      | tilt the drawn figure: degrees, −45 to 45, positive leans the top right |
+| shear_plane | the plane behind a sheared figure: on (grey), off, or a colour; never drawn on a transparent background |
+| vmargin    | clearance between a label and its connectors, 0.1–1.0, the same above and below |
+
+hspacing and vheight are named for the top-to-bottom layout, and follow the
+tree rather than the page: with direction ltr, sisters stack downwards and
+hspacing is what separates them, while vheight runs across.
+
+The full manual explains each of these with figures, and every example in the
+gallery is written out beside the figure it draws:
 
-    [S [NP what+>1] [VP [V see] [NP+1 t]]]
+    https://yohasebe.github.io/rsyntaxtree/documentation
+    https://yohasebe.github.io/rsyntaxtree/examples

data/lib/rsyntaxtree/notation_examples.md

@@ -1,4 +1,4 @@
-RSyntaxTree examples: 76 trees, every one verified to draw.
+RSyntaxTree examples: 80 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;
@@ -8,10 +8,10 @@ here through the same parser that draws it, so each one is accepted.
 Notation reference: rsyntaxtree --notation
 Check an input without drawing: rsyntaxtree --validate "[S [NP a] [VP b]]"
 
-What the option names on a settings line mean is not in this file, nor in
-the reference, which leaves the options out on purpose. For those, see
-`rsyntaxtree --help` or the manual: https://yohasebe.github.io/rsyntaxtree/documentation. Everything at
-once, this file and the manual together: https://yohasebe.github.io/rsyntaxtree/llms-full.txt
+What the option names on a settings line mean: one line each at the end
+of the reference (`rsyntaxtree --notation`), the full story in the manual
+at https://yohasebe.github.io/rsyntaxtree/documentation. Everything at once, this file and the manual
+together: https://yohasebe.github.io/rsyntaxtree/llms-full.txt
 
 
 ## 000 — RSyntaxTree basic example
@@ -2521,3 +2521,95 @@ Source: Steedman 2000
       [(S\\NP)/NP hates]]]
   [NP London]]
 ```
+
+## 082 — Indo-European language family
+
+Category: Historical Linguistics
+Settings: direction=ltr fontstyle=noto-serif hspacing=0.5 polyline=on vheight=5.0
+
+```
+[Proto\-Indo\-European
+  [%@#4a7c59:Italic
+    [Latin
+      [Western [*Spanish*] [*Portuguese*] [*French*]]
+      [Eastern [*Italian*] [*Romanian*]]]]
+  [%@#3d6b9e:Germanic
+    [West [*English*] [*German*] [*Dutch*]]
+    [North [*Swedish*] [*Icelandic*]]]
+  [%@#b5651d:Balto\-Slavic
+    [Slavic [*Russian*] [*Polish*] [*Czech*]]
+    [Baltic [*Lithuanian*] [*Latvian*]]]
+  [%@#8e4585:Indo\-Iranian
+    [Indo\-Aryan [*Hindi*] [*Bengali*]]
+    [Iranian [*Persian*] [*Pashto*]]]
+  [%@#7a6a9b:Hellenic [Ancient<>Greek [*Greek*]]]
+  [%@#2f7d7d:Celtic [*Irish*] [*Welsh*]]]
+```
+
+## 083 — Type-driven semantic composition
+
+Category: Formal Semantics
+Settings: color=none fontstyle=noto-serif leafstyle=nothing
+
+```
+[S\n*t*\n**love**(**m**)(**j**)
+  [DP\n*e*\n**j** [*John*]]
+  [VP\n⟨*e*,*t*⟩\nλ*x*.**love**(**m**)(*x*)
+    [V\n⟨*e*,⟨*e*,*t*⟩⟩\nλ*y*λ*x*.**love**(*y*)(*x*) [*loves*]]
+    [DP\n*e*\n**m** [*Mary*]]]]
+```
+
+## 084 — Typed feature structures with structure sharing
+
+Category: Formal Grammar
+Settings: color=none fontstyle=noto-serif leafstyle=nothing
+
+```
+[#(*phrase*\
+---\
+SYN\t#(HEAD\t|1|\
+VAL\t#(SPR\t⟨<>⟩#)#)#)
+  [#(*phrase*\
+  ---\
+  SYN\t#(HEAD\t#(*noun*\
+  ---\
+  AGR\t|2|#(*3sing*\
+  ---\
+  PER\t3\
+  NUM\t*sg*#)#)\
+  VAL\t#(SPR\t⟨<>⟩#)#)#) [the<>dog]]
+  [#(*word*\
+  ---\
+  SYN\t#(HEAD\t|1|#(*verb*\
+  ---\
+  AGR\t|2|#)\
+  VAL\t#(SPR\t⟨<>*NP*<>⟩#)#)#) [barks]]]
+```
+
+## 085 — A tree on a tilted plane
+
+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]
+      [NP
+        [D the]
+        [N table]
+      ]
+    ]
+  ]
+]
+```

data/lib/rsyntaxtree/string_parser.rb

@@ -96,9 +96,44 @@ module RSyntaxTree
       end
     end
 
+    # Whether the raw space that split this token is what stopped it parsing.
+    # Asked of the parser rather than reasoned about: the whole token, with its
+    # spaces written as `<>`, either reads as one label or it does not.
+    def space_is_the_cause?(token, parent)
+      Element.new(-1, parent, token.gsub(" ", WHITESPACE_BLOCK), @level,
+                  @fontset, @fontsize, @global, true)
+      true
+    rescue StandardError
+      false
+    end
+
     def parse
       make_tree(0);
       @elist.set_hierarchy
+      restore_rule_names_without_a_rule
+    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.
+    #
+    # Whether a node will have daughters is not known where the label is read —
+    # they arrive as later tokens — so the label is read first and put right
+    # here, once the tree is built. Left alone, turning the option on deleted a
+    # column: `[A\tfoo]` drew "A foo" with derivation off and "A" with it on,
+    # and said nothing about the difference.
+    def restore_rule_names_without_a_rule
+      @elist.elements.each_with_index do |e, i|
+        next if e.rule_name.nil? || e.rule_name.empty?
+        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)
+        restored.children = e.children
+        restored.type = e.type
+        @elist.elements[i] = restored
+      end
     end
 
     def get_elementlist
@@ -215,7 +250,21 @@ module RSyntaxTree
                 # parse, the likeliest story is that the space belongs
                 # inside the label and cut a construct in two — say so,
                 # unless a more specific cause is already known.
-                raise e if e.code == :bare_hyphen
+                #
+                # Which story is right is not a thing to guess at: ask
+                # whether the space is the one that breaks it. Put the whole
+                # token back together with the spaces written as the notation
+                # writes them, and try again. If it parses, the space was
+                # cutting a construct in two and that is what to say. If it
+                # fails the same way, the space is a red herring and the cause
+                # already named is the one to keep.
+                #
+                # It used to keep :bare_hyphen and relabel every other cause,
+                # so one error said two things: the message naming an unknown
+                # colour while the code and the hint talked about spaces. A
+                # caller acting on the code — which is what these are for —
+                # was sent to fix what was not wrong.
+                raise e unless space_is_the_cause?(token_r.join, parent)
 
                 raise RSTError.new(e.message,
                                    code: :label_split,