rsyntaxtree 1.13.2 → 2.0.0

data/lib/rsyntaxtree/svg_graph.rb

@@ -24,6 +24,10 @@ module RSyntaxTree
     # a darker shade of the same color — keeping the region clearly bounded on
     # a white page without a per-color "darker shade" lookup.
     REGION_STROKE_OPACITY = 0.55
+    # The plane a sheared figure lies on. Lighter than a region shade: a
+    # region marks part of a figure out from the rest, and the plane is
+    # behind all of it — at the region's own opacity the whole page darkens.
+    SHEAR_PLANE_FILL_OPACITY = 0.12
 
     attr_accessor :width, :height
 
@@ -41,11 +45,17 @@ module RSyntaxTree
       @fontstyle = params[:fontstyle]
       @polyline = params[:polyline] == true
       @direction = params[:direction] || "ttb"
+      # The angle arrives in degrees, positive leaning the top to the right.
+      # What the transform wants is the x-shift per unit of y, and y grows
+      # downward here, so the tangent changes sign on the way in.
+      @shear_deg = (params[:shear] || 0).to_f
+      @shear_k = (-Math.tan(@shear_deg * Math::PI / 180)).round(3)
+      @shear_plane = params[:shear_plane] || "on"
       @line_styles = "<line style='fill: none; stroke:#{@col_line}; stroke-width:#{@global[:stroke_normal]}; stroke-linejoin:round; stroke-linecap:round;' x1='X1' y1='Y1' x2='X2' y2='Y2' />\n"
       @polyline_styles = "<polyline style='stroke:#{@col_line}; stroke-width:#{@global[:stroke_normal]}; fill:none; stroke-linejoin:round; stroke-linecap:round;'
                             points='CHIX CHIY MIDX1 MIDY1 MIDX2 MIDY2 PARX PARY' />\n"
       @polygon_styles = "<polygon style='fill: none; stroke: #{@col_connector}; stroke-width:#{@global[:stroke_normal]}; stroke-linejoin:round;stroke-linecap:round;' points='X1 Y1 X2 Y2 X3 Y3' />\n"
-      @text_styles = "<text white-space='pre' alignment-baseline='text-top' style='fill: COLOR; storoke-width: 0; font-size: fontsize' x='X_VALUE' y='Y_VALUE'>CONTENT</text>\n"
+      @text_styles = "<text white-space='pre' alignment-baseline='text-top' style='fill: COLOR; stroke-width: 0; font-size: fontsize' x='X_VALUE' y='Y_VALUE'>CONTENT</text>\n"
       @tree_data = String.new
       @visited_x = {}
       @visited_y = {}
@@ -90,10 +100,50 @@ module RSyntaxTree
         y2 = new_y2
       end
 
+      # A sheared figure needs a canvas of its own shape. The plane is laid
+      # out in the space the tree was drawn in — everything inside the shear
+      # group shares it — so it is the union of all the ink there: the
+      # elements, the region shades, the movement rails, and a rule's name
+      # hanging past the last box. The canvas is that plane's four corners
+      # after the shear, with the usual margin around them.
+      unless @shear_k.zero?
+        gap = @global[:h_gap_between_nodes]
+        els = @element_list.get_elements
+        ink_l = els.map(&:horizontal_indent).min
+        ink_t = els.map(&:vertical_indent).min
+        ink_r = els.map { |e| e.horizontal_indent + e.content_width }.max
+        ink_b = els.map { |e| e.vertical_indent + e.content_height }.max
+        ink_r = @rule_name_edge if @rule_name_edge.to_f > ink_r
+        [@region_bounds, @path_bounds].compact.each do |b|
+          ink_l = [ink_l, b[:min_x]].min
+          ink_t = [ink_t, b[:min_y]].min
+          ink_r = [ink_r, b[:max_x]].max
+          ink_b = [ink_b, b[:max_y]].max
+        end
+        pad = gap * 1.5
+        @plane_rect = { x: (ink_l - pad).round(3), y: (ink_t - pad).round(3),
+                        w: (ink_r - ink_l + pad * 2).round(3), h: (ink_b - ink_t + pad * 2).round(3) }
+        cx0 = @plane_rect[:x] - gap
+        cx1 = @plane_rect[:x] + @plane_rect[:w] + gap
+        cy0 = @plane_rect[:y] - gap
+        cy1 = @plane_rect[:y] + @plane_rect[:h] + gap
+        sheared = [cx0 + @shear_k * cy0, cx0 + @shear_k * cy1,
+                   cx1 + @shear_k * cy0, cx1 + @shear_k * cy1]
+        x1 = sheared.min.round(3)
+        x2 = (sheared.max - sheared.min).round(3)
+        y1 = cy0.round(3)
+        y2 = (cy1 - cy0).round(3)
+        @width = x2
+        @height = y2
+      end
+
       extra_lines = @extra_lines.join("\n")
 
-      as2 = @global[:h_gap_between_nodes] * 1.0
-      as4 = as2 * 3
+      # Rounded like the stroke widths are: the arithmetic leaves float dust
+      # (13.600000000000001) in an attribute of every figure, and the SVG is a
+      # deliverable people open in editors.
+      as2 = (@global[:h_gap_between_nodes] * 1.0).round(3)
+      as4 = (as2 * 3).round(3)
       # The hatch density follows the type size the way the enclosure it
       # fills does: the cell is 10/32 of the font size, the line 4/32 —
       # the ratios the absolute 10 and 4 had at the default size.
@@ -142,10 +192,40 @@ module RSyntaxTree
       # below tree connectors and labels.
       shades = @region_shades.join
 
-      if @transparent
-        header + shades + @tree_data + extra_lines + footer
+      if @shear_k.zero?
+        if @transparent
+          header + shades + @tree_data + extra_lines + footer
+        else
+          header + rect + shades + @tree_data + extra_lines + footer
+        end
       else
-        header + rect + shades + @tree_data + extra_lines + footer
+        # The whole picture shears as one: the plane, the shades, the tree
+        # and the rails all live inside the group, so an affine map carries
+        # every incidence with it — nothing can newly touch or cross. The
+        # background stays outside, painted to the sheared canvas.
+        # No plane on a transparent background: what a clear background is
+        # for is laying the figure over something else, and an opaque sheet
+        # under it is the one thing that would defeat that.
+        plane = +""
+        if @shear_plane != "off" && !@transparent
+          color = @shear_plane == "on" ? REGION_DEFAULT_COLOR : @shear_plane
+          radius = @global[:height_connector_to_text] / 2.0
+          # Fill alone, no edge. A region shade is bounded because it marks
+          # one part of a figure off from the rest; the plane is under all of
+          # it, and a line around the whole drawing reads as a frame.
+          plane = "<rect x=\"#{@plane_rect[:x]}\" y=\"#{@plane_rect[:y]}\" " \
+                  "width=\"#{@plane_rect[:w]}\" height=\"#{@plane_rect[:h]}\" " \
+                  "rx=\"#{radius}\" ry=\"#{radius}\" " \
+                  "fill=\"#{color}\" fill-opacity=\"#{SHEAR_PLANE_FILL_OPACITY}\" " \
+                  "stroke=\"none\" />\n"
+        end
+        body = "<g transform=\"matrix(1,0,#{@shear_k},1,0,0)\">\n" +
+               plane + shades + @tree_data + extra_lines + "</g>\n"
+        if @transparent
+          header + body + footer
+        else
+          header + rect + body + footer
+        end
       end
     end
 
@@ -333,6 +413,20 @@ module RSyntaxTree
         "#{dasharray}#{markers}/>"
     end
 
+    # Where the movement paths have been, as a box. The canvas learns of a
+    # rail through @width and @height, which only say how far right and down
+    # anything got; the plane behind a sheared figure has to enclose the rail
+    # on every side, so the corners themselves are kept.
+    def note_path_extent(points)
+      xs = points.map(&:first)
+      ys = points.map(&:last)
+      b = (@path_bounds ||= { min_x: xs.min, min_y: ys.min, max_x: xs.max, max_y: ys.max })
+      b[:min_x] = [b[:min_x], xs.min].min
+      b[:min_y] = [b[:min_y], ys.min].min
+      b[:max_x] = [b[:max_x], xs.max].max
+      b[:max_y] = [b[:max_y], ys.max].max
+    end
+
     def draw_a_path(s_x, s_y, t_x, t_y, target_arrow = :none)
       spacing = @global[:h_gap_between_nodes] * 1.25
       min_bulge = @global[:height_connector_to_text]
@@ -365,6 +459,8 @@ module RSyntaxTree
         new_s_y = s_y + s_offset
         new_t_y = t_y + t_offset
 
+        note_path_extent([[s_x, new_s_y], [new_x, new_s_y],
+                          [new_x, new_t_y], [t_x, new_t_y]])
         @extra_lines << generate_path([[s_x, new_s_y], [new_x, new_s_y],
                                        [new_x, new_t_y], [t_x, new_t_y]],
                                       @col_path, dashed: dashed, radius: corner_radius,
@@ -383,6 +479,8 @@ module RSyntaxTree
         new_s_x = s_x - s_offset
         new_t_x = t_x - t_offset
 
+        note_path_extent([[new_s_x, s_y], [new_s_x, new_y],
+                          [new_t_x, new_y], [new_t_x, t_y]])
         @extra_lines << generate_path([[new_s_x, s_y], [new_s_x, new_y],
                                        [new_t_x, new_y], [new_t_x, t_y]],
                                       @col_path, dashed: dashed, radius: corner_radius,
@@ -421,6 +519,7 @@ module RSyntaxTree
       this_x = 0
       this_y = 0
       prev_line_height = nil
+      first_baseline = nil
       bc = { x: text_x - enclosure_room, y: top, width: element.content_width, height: nil }
       element.content.each_with_index do |l, idx|
         case l[:type]
@@ -461,6 +560,7 @@ module RSyntaxTree
           # after it has to clear all of it.
           text_y += prev_line_height if idx != 0 && prev_line_height
           text_y += l[:top_room].to_f
+          first_baseline ||= text_y
           prev_line_height = l[:elements].map { |e| e[:height] }.max
 
           l[:elements].each do |e|
@@ -493,6 +593,36 @@ module RSyntaxTree
       end
 
       element.content_height = bc[:height]
+
+      # Where the label's ink is, for the symmetric clearances of vmargin.
+      # A drawn shape — an enclosure, or a label that is one matrix — hands
+      # over its own edges; a plain label hands over the font's band around
+      # its first and last baselines, so the connectors of one level start
+      # level with each other whatever letters happen to hang below.
+      drawn_shape = element.enclosure != :none ||
+                    element.content.any? do |line|
+                      line[:type] == :text &&
+                        line[:elements].any? { |e| e[:decoration].include?(:matrix) }
+                    end
+      if drawn_shape
+        element.ink_top = bc[:y]
+        element.ink_bottom = bc[:y] + bc[:height]
+      elsif first_baseline
+        # The label's own ink, not the font's whole band: measured from the
+        # first and last lines of text as drawn. What the connectors then
+        # keep clear of is the union of these across a row (see row_ink), so
+        # the ends stay level within a row while a row of capitals pays no
+        # tax for descenders nobody wrote.
+        text_lines = element.content.select { |l| l[:type] == :text }
+        first_text = text_lines.first[:elements].map { |e| e[:text].to_s }.join.gsub(WHITESPACE_BLOCK, " ")
+        last_text = text_lines.last[:elements].map { |e| e[:text].to_s }.join.gsub(WHITESPACE_BLOCK, " ")
+        f_m = FontMetrics.get_metrics(first_text.strip.empty? ? "X" : first_text,
+                                      @fontset[:family], @fontsize.to_f, :normal, :normal)
+        l_m = FontMetrics.get_metrics(last_text.strip.empty? ? "X" : last_text,
+                                      @fontset[:family], @fontsize.to_f, :normal, :normal)
+        element.ink_top = first_baseline - f_m.ink_above
+        element.ink_bottom = text_y + (l_m.ink_height - l_m.ink_above)
+      end
       @tree_data += text_data.sub(/CONTENT/, new_text)
     end
 
@@ -621,11 +751,42 @@ module RSyntaxTree
     # the sizes Element#measure_lines worked out, inside its own brackets.
     def render_matrix(e, this_x, text_y, element, col)
       out = +""
+      advance = e[:width]
+      # The room measured in front of the block, if it follows something in
+      # the same cell. Taken off this_x here so the bracket starts after it,
+      # and left in the advance so the row is as wide as it was measured.
+      lead = e[:matrix_lead].to_f
+      this_x += lead
       inner_x = this_x + @global[:width_half_x] * MATRIX_BRACKET_ROOM
       baseline = text_y
       prev_height = nil
 
       e[:matrix].each_with_index do |line, idx|
+        # A rule across the matrix, the way one runs across a label: it takes
+        # a row of its own and spans the width inside the brackets, so a
+        # feature structure can separate its type from its features and a
+        # tableau its header from its candidates.
+        if %i[border bborder].include?(line[:type])
+          # Placed from the baseline above it, the way a rule across a label
+          # is: a third of a line under the row before, the rest of the gap
+          # under the rule. Measuring from the row it is about to open
+          # instead put the space on the wrong side — more above the rule
+          # than below, where the ascenders of the next row need it.
+          above = baseline
+          baseline += prev_height if idx.positive? && prev_height
+          prev_height = line[:height].to_f
+          y = if idx.zero?
+                above - prev_height - @global[:single_line_height] / 8
+              else
+                above + prev_height - @global[:single_line_height] / 8
+              end
+          inner_w = e[:width] - (inner_x - this_x) * 2
+          stroke = line[:type] == :bborder ? @global[:stroke_bold] : @global[:stroke_normal]
+          @extra_lines << "<line style=\"stroke:#{col}; fill:none; stroke-linecap:round; " \
+                          "stroke-width:#{stroke}; \" x1=\"#{inner_x}\" y1=\"#{y}\" " \
+                          "x2=\"#{inner_x + inner_w}\" y2=\"#{y}\"></line>"
+          next
+        end
         next unless line[:type] == :text
 
         baseline += prev_height if idx.positive? && prev_height
@@ -648,8 +809,8 @@ module RSyntaxTree
       # stacked blocks touching.
       padding = @global[:single_x_metrics].height * MATRIX_VERTICAL_ROOM
       top = text_y - @global[:single_x_metrics].height * 0.8 - padding
-      draw_bracket(this_x, top, e[:width], e[:matrix_height] + padding * 2, col)
-      [out, this_x + e[:width]]
+      draw_bracket(this_x, top, e[:width] - lead, e[:matrix_height] + padding * 2, col)
+      [out, this_x + advance - lead]
     end
 
     def draw_rectangle(x1, y1, width, height, col, bline = false)
@@ -1013,14 +1174,62 @@ module RSyntaxTree
     # the parent is the lower of the two, and keeping the top-to-bottom edges
     # sent the line back up through both labels. An empty label has no text to
     # clear, so the line runs to its middle.
+    # The ink extents of a row: the union, across every plain label standing
+    # at one height, of where its type actually reaches. An endpoint measured
+    # from the label's own ink alone gives every label equal air but leaves
+    # the ends of a row's connectors ragged — a line reaches lower over `on`
+    # than over `the`; measured from the whole font's band the ends are level
+    # but a row of capitals pays for descenders nobody wrote. The row's own
+    # union keeps the ends level and charges only for what the row contains.
+    def row_ink
+      @row_ink ||= @element_list.get_elements.each_with_object({}) do |e, rows|
+        next unless e.ink_top && e.ink_bottom
+        next if e.enclosure != :none
+
+        row = (rows[e.vertical_indent.round(1)] ||= { top: e.ink_top, bottom: e.ink_bottom })
+        row[:top] = [row[:top], e.ink_top].min
+        row[:bottom] = [row[:bottom], e.ink_bottom].max
+      end
+    end
+
+    # Where a connector clears an element on the vmargin geometry: the row's
+    # ink for a plain label, the drawn edge for an enclosed one.
+    def ink_over(element)
+      row = element.enclosure == :none && row_ink[element.vertical_indent.round(1)]
+      row ? row[:top] : element.ink_top
+    end
+
+    def ink_under(element)
+      row = element.enclosure == :none && row_ink[element.vertical_indent.round(1)]
+      row ? row[:bottom] : element.ink_bottom
+    end
+
     def connector_edges(child, parent)
       hctt = @global[:height_connector_to_text]
       child_above = child.vertical_indent <= parent.vertical_indent
 
+      # Each endpoint decides for itself. A line through a chain of invisible
+      # joints keeps one real label at most, and when the pair had to agree
+      # on a geometry, the segments beside a joint fell back to the box
+      # measure while their neighbours took the ink one — a row of leaves
+      # under example 080's joints ended thirteen units apart.
+      #
+      # An element whose ink went unrecorded falls back to the measure the
+      # boxes gave. Nothing reaches that now — every drawn label records its
+      # ink — and it is kept as the answer for a label that somehow has none
+      # rather than as a second geometry anyone can ask for.
+      m = @global[:single_x_metrics].height * @global[:vmargin]
+
       child_y = if child.empty_label?
                   child.vertical_indent + child.content_height / 2
                 elsif child_above
-                  child.vertical_indent + child.content_height + hctt
+                  if m && child.ink_bottom
+                    ink_under(child) + m
+                  else
+                    child.vertical_indent + child.content_height + hctt
+                  end
+                elsif m && child.ink_top
+                  ink_over(child) - m
                 else
                   child.vertical_indent + hctt / 2
                 end
@@ -1028,11 +1237,31 @@ module RSyntaxTree
       parent_y = if parent.empty_label?
                    parent.vertical_indent + parent.content_height / 2
                  elsif child_above
-                   parent.vertical_indent + hctt / 2
+                   if m && parent.ink_top
+                     ink_over(parent) - m
+                   else
+                     parent.vertical_indent + hctt / 2
+                   end
+                 elsif m && parent.ink_bottom
+                   ink_under(parent) + m
                  else
                    parent.vertical_indent + parent.content_height + hctt
                  end
 
+      # A tight pitch can put the two endpoints past each other — the gap
+      # between the inks smaller than the clearance on both sides — and a
+      # crossed pair draws the stroke back up through a label. Both then
+      # settle at the middle of the gap, which is the one point that is
+      # clear of the ink on either side whenever the gap exists at all.
+      if m
+        upper_pt, lower_pt = child_above ? [child_y, parent_y] : [parent_y, child_y]
+        if upper_pt > lower_pt
+          mid = (upper_pt + lower_pt) / 2.0
+          child_y = mid
+          parent_y = mid
+        end
+      end
+
       [child_y, parent_y]
     end
 
@@ -1122,14 +1351,41 @@ module RSyntaxTree
         x3 = parent.horizontal_indent + parent.content_width + @global[:height_connector_to_text]
         y3 = parent_y_center
       else
-        # TTB: triangle opens horizontally (left-right of child text),
-        # apex at parent's bottom
+        # The triangle spans the child's text and points at the parent. Which
+        # way it points is the question the connectors ask as `child_above`,
+        # and the answer is not always the same: bottom-to-top turns the
+        # finished layout over, so the child sits above the parent there and
+        # the base and the apex trade sides. Drawn as though the child were
+        # always below, a bottom-to-top triangle came out inside out — its
+        # base struck through the leaf and its apex through the node — for as
+        # long as the option has existed. No gallery figure carries one: the
+        # bottom-to-top examples are derivations, which draw rules instead.
         x1 = child.horizontal_indent
-        y1 = child.vertical_indent + @global[:height_connector_to_text] / 2
         x2 = child.horizontal_indent + child.content_width
-        y2 = child.vertical_indent + @global[:height_connector_to_text] / 2
         x3 = parent.horizontal_indent + parent.content_width / 2
-        y3 = parent.vertical_indent + parent.content_height + @global[:height_connector_to_text]
+        child_above = child.vertical_indent <= parent.vertical_indent
+        m = child.ink_top && parent.ink_bottom ? @global[:single_x_metrics].height * @global[:vmargin] : nil
+        if child_above
+          y1 = m ? ink_under(child) + m : child.vertical_indent + child.content_height + @global[:height_connector_to_text]
+          y3 = m ? ink_over(parent) - m : parent.vertical_indent + @global[:height_connector_to_text] / 2
+          # The apex must stay clear of the base, or the figure folds through
+          # itself; where there is no room for both clearances they meet in
+          # the middle of what room there is.
+          if m && y3 < y1
+            mid = (y1 + y3) / 2.0
+            y1 = mid
+            y3 = mid
+          end
+        else
+          y1 = m ? ink_over(child) - m : child.vertical_indent + @global[:height_connector_to_text] / 2
+          y3 = m ? ink_under(parent) + m : parent.vertical_indent + parent.content_height + @global[:height_connector_to_text]
+          if m && y3 > y1
+            mid = (y1 + y3) / 2.0
+            y1 = mid
+            y3 = mid
+          end
+        end
+        y2 = y1
       end
 
       polygon_data = @polygon_styles.sub(/X1/, x1.to_s)

data/lib/rsyntaxtree/tikz_generator.rb

@@ -40,6 +40,15 @@ module RSyntaxTree
                                  "at the top. Use png, svg or pdf for this figure.",
                            retryable: false)
       end
+      # Refused rather than quietly drawn straight: a shear is the whole point
+      # of the figure that asks for it, and TikZ's own slant (xslant) leaves
+      # the bounding box unaware of the lean, so standalone output crops.
+      if params[:shear].to_f != 0
+        raise RSTError.new(+"Error: TikZ output cannot draw a sheared figure",
+                           code: :invalid_option,
+                           hint: "Use png, svg or pdf for this figure, or drop the shear option.",
+                           retryable: false)
+      end
     end
 
     # Generate TikZ forest code

data/lib/rsyntaxtree/version.rb

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