rsyntaxtree 1.13.2 → 2.0.0

data/lib/rsyntaxtree.rb

@@ -34,11 +34,9 @@ WHITESPACE_BLOCK = "￭"
 # Every format the library can produce, and the file extension each one
 # writes. The CLI builds its --format validation, help text, and output
 # filename from these, so a new format is added here and nowhere else.
-FORMATS = %w[png jpg gif pdf svg lsif tikz].freeze
+FORMATS = %w[png pdf svg lsif tikz].freeze
 FORMAT_EXTENSIONS = {
   "png" => "png",
-  "jpg" => "jpg",
-  "gif" => "gif",
   "pdf" => "pdf",
   "svg" => "svg",
   "lsif" => "lsif.json",
@@ -54,7 +52,7 @@ FORMAT_EXTENSIONS = {
 # pass their own extra parameters through.
 OPTION_VALUES = {
   format: FORMATS,
-  leafstyle: %w[auto triangle bar nothing none],
+  leafstyle: %w[auto triangle bar nothing],
   fontstyle: ["sans", "serif", "cjk", "mono", "noto-sans", "noto-serif", "noto-sans-mono", "cjk zenhei"],
   color: %w[modern traditional gray grey off none on true false],
   tidy: %w[off symmetric low medium high on compact true false],
@@ -68,7 +66,20 @@ NUMERIC_RANGES = {
   linewidth: 0.5..3.0,
   vheight: 0.5..5.0,
   hspacing: 0.5..3.0,
-  tidy_spacing: 0.5..3.0
+  shear: -45..45,
+  vmargin: 0.1..1.0
+}.freeze
+
+# Options 2.0 removed, and what to say instead. An unknown key is passed over
+# in silence, because a caller may hand its own parameters through — which is
+# right for a key this library never had, and wrong for one it used to obey.
+# A program that still asks for symmetrize would have been given the layout it
+# asked for in 1.x and a different one here, with nothing said. Named here,
+# the ask is refused the way `-f jpg` and `leafstyle: none` are.
+REMOVED_OPTIONS = {
+  symmetrize: 'tidy: "symmetric"',
+  tidy_spacing: "hspacing",
+  tidy_nest: 'tidy: "high"'
 }.freeze
 
 DEFAULT_OPTS = {
@@ -79,7 +90,6 @@ DEFAULT_OPTS = {
   linewidth: 1,
   vheight: 2.0,
   color: "modern",
-  symmetrize: "off",
   transparent: "off",
   polyline: "off",
   hide_default_connectors: "off",
@@ -88,7 +98,14 @@ DEFAULT_OPTS = {
   hspacing: 1.0,
   direction: "ttb",
   hyphen: "markup",
-  derivation: "off"
+  derivation: "off",
+  shear: 0,
+  shear_plane: "on",
+  # 0.4 keeps the level pitch the historical drawing had, and replaces its
+  # unequal air — a little more below every label than above it, an
+  # unadjusted leftover of measuring from the layout box — with the same
+  # clearance on both sides of the ink.
+  vmargin: 0.4
 }.freeze
 
 # A parse or generation failure. `message` is the human-readable text the
@@ -163,12 +180,29 @@ module RSyntaxTree
         next if (OPTION_VALUES.key?(key) || NUMERIC_RANGES.key?(key)) &&
                 (value.nil? || value.to_s.strip.empty?)
 
+        if REMOVED_OPTIONS.key?(key)
+          raise RSTError.new(+"Error: option '#{key}' was removed in RSyntaxTree 2.0",
+                             code: :invalid_option,
+                             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,
                              hint: "'#{key}' must be one of: #{OPTION_VALUES[key].join(', ')}.",
                              retryable: false)
         end
+        # The range check reads the value as a float, and a string that is
+        # not a number reads as zero. Every range used to sit clear of zero,
+        # so nonsense failed the range check by accident; shear's runs through
+        # it, and "abc" would have been taken as no shear at all.
+        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,
+                             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}",
@@ -200,10 +234,10 @@ module RSyntaxTree
           # strict leaf positions), "medium" (packing that may tuck
           # branches across rows as long as no two leaves swap their
           # left-right order), "high" (free tucking; leaf order kept per
-          # row only). "on"/"compact" are accepted as legacy aliases of
-          # low/high, legacy tidy_nest: "on" upgrades low to high, and
-          # legacy symmetrize: "on" upgrades "off" to "symmetric" (both
-          # below, in BaseGraph).
+          # row only). "on"/"compact" are accepted as aliases of low/high.
+          # The separate symmetrize and tidy_nest flags this scale replaced
+          # were removed in 2.0; tidy: symmetric and tidy: high say what
+          # they said.
           new_params[key] = case value.to_s
                             when "high", "compact"
                               "high"
@@ -216,7 +250,7 @@ module RSyntaxTree
                             else
                               "off"
                             end
-        when :tidy_nest, :symmetrize, :transparent, :polyline, :hide_default_connectors, :mirror, :derivation
+        when :transparent, :polyline, :hide_default_connectors, :mirror, :derivation
           new_params[key] = switched_on?(value)
         when :color
           new_params[key] = case value.to_s
@@ -235,8 +269,28 @@ module RSyntaxTree
           new_params[key] = value.to_i
         when :linewidth
           new_params[key] = value.to_f
-        when :vheight, :hspacing, :tidy_spacing
+        when :vheight, :hspacing, :shear, :vmargin
           new_params[key] = value.to_f
+        when :shear_plane
+          # on | off | a colour. The empty string is a form control nobody
+          # touched, so the default stands — this key sits outside the value
+          # tables the blanket blank-skip above covers.
+          v = value.to_s.strip
+          unless v.empty?
+            new_params[key] = case v.downcase
+                              when "on", "true", "yes", "1" then "on"
+                              when "off", "false", "no", "0", "none" then "off"
+                              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,
+                                                     hint: "'shear_plane' is on, off, a colour name, " \
+                                                           "or a hex colour of 3 or 6 digits.",
+                                                     retryable: false)
+                                end
+                                v
+                              end
+          end
         when :fontstyle
           # Fonts are resolved by name through fontconfig (measurement via
           # Pango, rendering via the SVG font-family attribute), so all a
@@ -254,13 +308,6 @@ module RSyntaxTree
         end
       end
 
-      # Legacy alias: tidy_spacing was the tidy-only horizontal gap factor
-      # before it was generalized to hspacing (all layout modes).
-      if (new_params[:hspacing].nil? || new_params[:hspacing] == 1.0) &&
-         new_params[:tidy_spacing] && new_params[:tidy_spacing] != 1.0
-        new_params[:hspacing] = new_params[:tidy_spacing]
-      end
-
       # defaults to the following
       @params = DEFAULT_OPTS.dup
       @params.merge! new_params
@@ -313,8 +360,26 @@ module RSyntaxTree
       # Horizontal counterpart of vheight: hspacing scales every horizontal
       # gap (sibling clearance in all layout modes, tidy minimum gap,
       # margins) the way vheight scales the vertical rhythm.
-      @global[:h_gap_between_nodes] = single_x_metrics.width * 0.8 * (@params[:hspacing] || 1.0).to_f
-      @global[:box_vertical_margin] = single_x_metrics.height * 0.8
+      #
+      # The factor is kept beside the gap it scales because the left-to-right
+      # layout replaces that gap with one of its own and has to scale it by
+      # the same amount. Recovering the factor by dividing the gap back out
+      # would be this rule written a second time, free to drift from this one.
+      @global[:hspacing] = (@params[:hspacing] || 1.0).to_f
+      @global[:h_gap_between_nodes] = single_x_metrics.width * 0.8 * @global[:hspacing]
+      # The font's band: how far a capital reaches above the baseline and a
+      # descender below it. What the symmetric clearances of vmargin measure
+      # from — the band rather than each label's own ink, so the line ends
+      # line up across a level instead of following every g and y.
+      @global[:cap_height] = single_x_metrics.ink_above
+      xg_metrics = FontMetrics.get_metrics("Xg", fontset[:family], @params[:fontsize], :normal, :normal)
+      @global[:descender] = xg_metrics.ink_height - xg_metrics.ink_above
+      @global[:vmargin] = @params[:vmargin]
+      @global[:box_vertical_margin] = if @params[:vmargin]
+                                        single_x_metrics.height * @params[:vmargin] * 2
+                                      else
+                                        single_x_metrics.height * 0.8
+                                      end
       # Every stroke follows the type size: linewidth 1 is 5% of it (the
       # ratio of an ordinary text rule, booktabs' \lightrulewidth), each
       # 0.5 step of the option adds another 2.5%, and a bold stroke adds
@@ -386,17 +451,15 @@ module RSyntaxTree
     #
     # Which generation depends on the format asked for, because the formats
     # can refuse different things: a tree can be too wide for a raster
-    # surface while remaining a perfectly good SVG, and JPG and GIF need a
-    # gem that may not be installed. Everything up to the last point where
-    # a format is known to say no is done; painting the tree onto the
-    # surface, which is most of the cost and refuses nothing this knows of,
-    # is not. A surface inside Cairo's limits but large enough to exhaust
-    # memory would still fail at that painting, so this is where validation
-    # is a strong guess rather than a guarantee.
+    # surface while remaining a perfectly good SVG. Everything up to the
+    # last point where a format is known to say no is done; painting the
+    # tree onto the surface, which is most of the cost and refuses nothing
+    # this knows of, is not. A surface inside Cairo's limits but large
+    # enough to exhaust memory would still fail at that painting, so this is
+    # where validation is a strong guess rather than a guarantee.
     def validate!
       case @params[:format]
       when "png" then raster_surface_for(draw_svg, &:finish)
-      when "jpg", "gif" then with_rmagick { raster_surface_for(draw_svg, &:finish) }
       when "pdf" then pdf_surface_for(draw_svg, StringIO.new, &:finish)
       when "lsif" then draw_lsif
       when "tikz" then draw_tikz
@@ -472,44 +535,6 @@ module RSyntaxTree
       graph.svg_data
     end
 
-    # JPG and GIF output converts the PNG through RMagick. The require is
-    # lazy: both formats are deprecated and will be removed in 2.0, and the
-    # library must load without RMagick for every other format. A missing
-    # RMagick is reported as an input-level error, not a bare LoadError.
-    def with_rmagick
-      require 'rmagick'
-      yield
-    rescue LoadError
-      raise RSTError.new(+"Error: JPG/GIF output requires ImageMagick and the rmagick gem, " \
-                         "which is not installed. Use PNG instead — JPG and GIF support " \
-                         "is deprecated and will be removed in 2.0.",
-                         code: :missing_dependency, retryable: false)
-    end
-
-    def draw_jpg
-      with_rmagick do
-        png_data = draw_png
-        images = Magick::Image.from_blob(png_data)
-        image = images.first
-        image.format = 'JPEG'
-        blob = image.to_blob
-        images.each(&:destroy!)
-        blob
-      end
-    end
-
-    def draw_gif
-      with_rmagick do
-        png_data = draw_png
-        images = Magick::Image.from_blob(png_data)
-        image = images.first
-        image.format = 'GIF'
-        blob = image.to_blob
-        images.each(&:destroy!)
-        blob
-      end
-    end
-
     def draw_lsif
       sp = StringParser.new(@params[:data].gsub('&', '&'), @params[:fontset], @params[:fontsize], @global)
       sp.parse

data/rsyntaxtree.gemspec

@@ -28,15 +28,16 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  # specify any dependencies here; for example:
+  # Four, and each is used: optimist parses the command line, parslet parses
+  # the markup inside a label, pango measures the text, rsvg2 draws the PNG
+  # and the PDF. Two of them build against a system library — pango and
+  # librsvg — which is what an install of this gem asks a machine for.
   s.add_runtime_dependency "optimist", ">= 3.0.1"
   s.add_runtime_dependency "pango"
   s.add_runtime_dependency "parslet"
-  s.add_runtime_dependency "rmagick", ">= 4.3"
   s.add_runtime_dependency "rsvg2"
 
   s.add_development_dependency "minitest"
   s.add_development_dependency "nokogiri"
   s.add_development_dependency "rake"
-  s.add_development_dependency "yaml"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsyntaxtree
 version: !ruby/object:Gem::Version
-  version: 1.13.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Yoichiro Hasebe
@@ -51,20 +51,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rmagick
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.3'
 - !ruby/object:Gem::Dependency
   name: rsvg2
   requirement: !ruby/object:Gem::Requirement
@@ -121,20 +107,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: yaml
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: Syntax tree generator made with Ruby
 email:
 - yohasebe@gmail.com