sevgi-graphics 0.95.0 → 1.0.0

data/lib/sevgi/graphics/mixtures/render.rb

@@ -10,75 +10,20 @@ module Sevgi
         class Renderer
           # Default renderer options.
           DEFAULTS = {indent: "  ", linelength: 140, style: :hybrid}.freeze
+          STYLES = %i[hybrid inline block].freeze
           SVG_NAMESPACE = "http://www.w3.org/2000/svg"
 
-          # Attribute rendering strategies.
-          # @api private
-          module Attributes
-            # Block-style attribute renderer.
-            # @api private
-            module Block
-              # Renders attributes in block form.
-              # @param element [Sevgi::Graphics::Element] rendered element
-              # @param depth [Integer] element depth
-              # @return [void]
-              def attributes(element, depth)
-                attributes_block(element, depth, element.attributes.to_xml_lines)
-              end
-            end
-
-            # Hybrid attribute renderer.
-            # @api private
-            module Hybrid
-              # Renders attributes inline or in block form according to line length.
-              # @param element [Sevgi::Graphics::Element] rendered element
-              # @param depth [Integer] element depth
-              # @return [void]
-              def attributes(element, depth)
-                if attributes_as_block?(lines = element.attributes.to_xml_lines, depth)
-                  attributes_block(element, depth, lines)
-                else
-                  attributes_inline(element, depth, lines)
-                end
-              end
-
-              # Reports whether attributes should be rendered in block form.
-              # @param lines [Array<String>] rendered attribute lines
-              # @param depth [Integer] element depth
-              # @return [Boolean]
-              def attributes_as_block?(lines, depth)
-                linelength(lines, depth) > options[:linelength]
-              end
-
-              # Returns the effective inline line length.
-              # @param lines [Array<String>] rendered attribute lines
-              # @param depth [Integer] element depth
-              # @return [Integer]
-              def linelength(lines, depth)
-                indent(depth).length + lines.sum(&:length)
-              end
-            end
-
-            # Inline attribute renderer.
-            # @api private
-            module Inline
-              # Renders attributes inline.
-              # @param element [Sevgi::Graphics::Element] rendered element
-              # @param depth [Integer] element depth
-              # @return [void]
-              def attributes(element, depth)
-                attributes_inline(element, depth, element.attributes.to_xml_lines)
-              end
-            end
-          end
-
-          private_constant :Attributes
-
           ELEMENTS_WITH_INLINE_CONTENT = %i[title].freeze
           ELEMENTS_WITH_BLOCK_CONTENT = %i[style].freeze
           SEPARATOR = "\n"
 
-          private_constant :ELEMENTS_WITH_INLINE_CONTENT, :ELEMENTS_WITH_BLOCK_CONTENT, :SEPARATOR, :SVG_NAMESPACE
+          private_constant(
+            :ELEMENTS_WITH_INLINE_CONTENT,
+            :ELEMENTS_WITH_BLOCK_CONTENT,
+            :SEPARATOR,
+            :STYLES,
+            :SVG_NAMESPACE
+          )
 
           # @return [Sevgi::Graphics::Element] root element
           attr_reader :root
@@ -95,17 +40,11 @@ module Sevgi
             # Inline mark with start, stop, and depth.
             Mark = Struct.new(:start, :stop, :depth)
 
-            # Creates an inline splice tracker.
-            # @return [void]
             def initialize
               @marks = []
               @stack = []
             end
 
-            # Starts an inline splice range.
-            # @param index [Integer] output index
-            # @param depth [Integer] element depth
-            # @return [Sevgi::Graphics::Mixtures::Render::Renderer::Inlines::Mark] opened mark
             def start(index, depth)
               Mark.new(start: index, depth:).tap do |mark|
                 @marks << mark
@@ -113,10 +52,6 @@ module Sevgi
               end
             end
 
-            # Ends the innermost inline splice range.
-            # @param index [Integer] output index
-            # @return [Integer]
-            # @raise [Sevgi::PanicError] when no inline range is open
             def stop(index)
               mark = @stack.pop
               PanicError.("Inline content range was not opened") unless mark
@@ -124,12 +59,6 @@ module Sevgi
               mark.stop = index
             end
 
-            # Joins marked output ranges into inline content.
-            # @param output [Array<Array<String>, nil>] renderer output buffer
-            # @param indent [String] indentation unit
-            # @param separator [String] line separator
-            # @return [Array<Array<String>, nil>, nil]
-            # @raise [Sevgi::PanicError] when an inline range was not closed
             def join(output, indent:, separator:)
               return if @marks.empty?
 
@@ -165,11 +94,10 @@ module Sevgi
           #   @raise [Sevgi::ArgumentError] when an option is unknown, malformed, missing, or unsupported
           def initialize(root, **)
             @root = root
-            @options = DEFAULTS.merge(**)
+            @options = self.class.send(:validate, **)
             @output = []
             @inlines = Inlines.new
-
-            build
+            unclosed
           end
 
           # @overload call(root, **options)
@@ -187,6 +115,29 @@ module Sevgi
           # @raise [Sevgi::ArgumentError] when options, names, attributes, or content are invalid XML
           def self.fragment(root, **options) = new(root, **options).call
 
+          def self.validate(**options)
+            options = DEFAULTS.merge(options)
+            unknown = options.keys - DEFAULTS.keys
+            ArgumentError.("Unknown renderer options: #{unknown.join(", ")}") unless unknown.empty?
+
+            indent = options[:indent]
+            unless indent.is_a?(::String) && /\A[\t\n\r ]*\z/.match?(indent)
+              ArgumentError.("Renderer indent must contain only XML whitespace")
+            end
+
+            options[:indent] = XML.text(indent, context: "Renderer indent")
+            linelength = options[:linelength]
+            unless linelength.is_a?(::Integer) && linelength >= 0
+              ArgumentError.("Renderer linelength must be a non-negative Integer")
+            end
+
+            ArgumentError.("Unrecognized style: #{options[:style]}") unless STYLES.include?(options[:style])
+
+            options.freeze
+          end
+
+          private_class_method :validate
+
           # Appends rendered lines to the output buffer.
           # @param depth [Integer, nil] indentation depth
           # @param lines [Array<String>] rendered lines
@@ -216,6 +167,14 @@ module Sevgi
 
           attr_reader :inlines
 
+          def attributes(element, depth)
+            lines = element.attributes.send(:xml_lines)
+            block = options[:style] == :block ||
+              (options[:style] == :hybrid && indent(depth).length + lines.sum(&:length) > options[:linelength])
+
+            block ? attributes_block(element, depth, lines) : attributes_inline(element, depth, lines)
+          end
+
           def attributes_block(element, depth, lines)
             return attributes_inline(element, depth, lines) if lines.empty?
 
@@ -235,24 +194,6 @@ module Sevgi
             end
           end
 
-          def build
-            validate_options!
-            ArgumentError.("Missing style") unless options[:style]
-
-            case options[:style]
-            when :hybrid
-              extend(Attributes::Hybrid)
-            when :inline
-              extend(Attributes::Inline)
-            when :block
-              extend(Attributes::Block)
-            else
-              ArgumentError.("Unrecognized style: #{options[:style]}")
-            end
-
-            unclosed
-          end
-
           def childless?(element)
             element.children.empty? && element.contents.empty?
           end
@@ -330,32 +271,23 @@ module Sevgi
 
           def unclosed = @closed = false
 
-          def validate_options!
-            unknown = options.keys - DEFAULTS.keys
-            ArgumentError.("Unknown renderer options: #{unknown.join(", ")}") unless unknown.empty?
-
-            indent = options[:indent]
-            unless indent.is_a?(::String) && /\A[\t\n\r ]*\z/.match?(indent)
-              ArgumentError.("Renderer indent must contain only XML whitespace")
-            end
-
-            options[:indent] = XML.text(indent, context: "Renderer indent")
-            linelength = options[:linelength]
-            return if linelength.is_a?(::Integer) && linelength >= 0
-
-            ArgumentError.("Renderer linelength must be a non-negative Integer")
-          end
         end
 
         private_constant :Renderer
 
         # @overload Render(**options)
         #   Renders this element as SVG source.
-        #   Elements with inline text content may also contain inline children such as `tspan`; the renderer keeps those
+        #   Elements with inline text content can also contain inline children such as `tspan`. The renderer keeps those
         #   descendants in the same text line. Whitespace inside content objects is preserved as given, and encoded
-        #   content is XML-escaped unless a verbatim content object is used. SVG `style` elements use block content;
+        #   content is XML-escaped unless a verbatim content object is used. SVG `style` elements use block content.
         #   same-named elements under a foreign default namespace retain ordinary inline text formatting.
+        #   @example Keep every attribute on the element's opening line
+        #     SVG(:minimal) { rect id: "card", width: 80, height: 40 }.Render(style: :inline)
         #   @param options [Hash] renderer options
+        #   @option options [String] :indent ("  ") XML-whitespace indentation unit
+        #   @option options [Integer] :linelength (140) non-negative line length that switches hybrid attributes to block
+        #     style
+        #   @option options [Symbol] :style (:hybrid) attribute layout: `:hybrid`, `:inline`, or `:block`
         #   @return [String] SVG source
         #   @raise [Sevgi::ArgumentError] when options, preambles, names, attributes, or content are invalid XML
         def Render(**) = Renderer.(self, **)
@@ -363,14 +295,22 @@ module Sevgi
         # Renders only this element's children.
         # Child render output omits document preambles and preserves each child's text whitespace and inline
         # mixed-content formatting.
+        # @example Render child fragments with block-style attributes
+        #   Sevgi::Graphics.SVG(:minimal) { rect id: "one" }.RenderChildren(style: :block, indent: "\t")
         # @param separator [String] separator between child documents
+        # @param options [Hash] renderer options applied to every child fragment
+        # @option options [String] :indent ("  ") XML-whitespace indentation unit
+        # @option options [Integer] :linelength (140) non-negative line length that switches hybrid attributes to block
+        #   style
+        # @option options [Symbol] :style (:hybrid) attribute layout: `:hybrid`, `:inline`, or `:block`
         # @return [String] rendered child fragments
-        # @raise [Sevgi::ArgumentError] when separator or rendered child data is not valid XML text
-        def RenderChildren(separator = "\n\n")
+        # @raise [Sevgi::ArgumentError] when separator, options, or rendered child data is invalid
+        def RenderChildren(separator = "\n\n", **options)
           ArgumentError.("SVG fragment separator must be a String") unless separator.is_a?(::String)
 
           separator = XML.text(separator, context: "SVG fragment separator")
-          children.map { Renderer.fragment(it) }.join(separator)
+          Renderer.send(:validate, **options)
+          children.map { Renderer.fragment(it, **options) }.join(separator)
         end
       end
     end

data/lib/sevgi/graphics/mixtures/save.rb

@@ -8,52 +8,96 @@ module Sevgi
       # DSL helpers for writing rendered SVG output.
       module Save
         # Default SVG extension.
+        # @api private
         EXT = ".svg"
 
+        private_constant :EXT
+
+        # Change-aware file writer with optional backup support.
+        # @api private
+        class Writer
+          # Writes content when it differs from the destination.
+          # @param path [String] expanded output path
+          # @param content [String] rendered content
+          # @param backup_suffix [String, nil] suffix used for an existing-file backup
+          # @yield [content] optionally normalizes old and new content for change detection
+          # @yieldparam content [String] old or new content
+          # @yieldreturn [String] normalized content
+          # @return [String, nil] expanded path when written, otherwise nil
+          # @raise [SystemCallError] when the destination or backup cannot be created, read, or written
+          def self.call(path, content, backup_suffix: nil, &filter)
+            output = "#{content.chomp}\n"
+
+            return unless F.changed?(path, output, &filter)
+
+            ::FileUtils.mkdir_p(::File.dirname(path))
+            if backup_suffix && !backup_suffix.empty? && ::File.exist?(path)
+              ::FileUtils.cp(path, "#{path}#{backup_suffix}")
+            end
+
+            path.tap { ::File.write(path, output) }
+          end
+        end
+
+        private_constant :Writer
+
         # Writes rendered SVG to standard output.
-        # @param kwargs [Hash] render options
-        # @yield [content] optionally transforms rendered content before output
-        # @yieldparam content [String] rendered SVG source
-        # @yieldreturn [String] transformed SVG source
-        # @return [Object] F.out return value
-        def Out(**kwargs, &filter)
-          F.out(self.(**kwargs), &filter)
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @return [nil]
+        # @raise [Sevgi::ArgumentError] when a render option or XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @see Sevgi::Graphics::Document::Proto#call
+        def Out(**kwargs)
+          F.out(self.(**kwargs))
         end
 
-        # Saves rendered SVG to a path derived from the caller by default.
-        # @param path [String, nil] output path or directory
-        # @param default [String, nil] default output path
+        # Saves rendered SVG when its content differs from the destination.
+        # Relative destinations are expanded before being returned. When a non-empty backup suffix is given, an
+        # existing destination is copied immediately before replacement. Unchanged saves leave both files untouched.
+        # Missing parent directories are created. An existing directory target uses the default file name.
+        # @example Save to a relative destination
+        #   path = Sevgi::Graphics.SVG.Save("build/drawing.svg")
+        #   path == File.expand_path("build/drawing.svg") # => true
+        # @param path [String, #to_path, nil] output path or existing directory
+        # @param default [String, #to_path, nil] default output path
         # @param backup_suffix [String, nil] suffix used for an existing-file backup
-        # @yield [content] optionally transforms rendered content before output
-        # @yieldparam content [String] rendered SVG source
-        # @yieldreturn [String] transformed SVG source
-        # @return [Object] F.out return value
-        def Save(path = nil, default: nil, backup_suffix: nil, &filter)
-          default ||= F.subext(EXT, caller_locations(1..1).first.path)
-
-          if path
-            ::File.directory?(path) ? ::File.join(path, ::File.basename(default)) : path
-          else
-            default
-          end => path
-
-          ::FileUtils.mkdir_p(::File.dirname(path))
-          if backup_suffix && !backup_suffix.empty? && ::File.exist?(path)
-            ::FileUtils.cp(path, "#{path}#{backup_suffix}")
-          end
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @yield [content] optionally normalizes old and new content for change detection
+        # @yieldparam content [String] old or new SVG source
+        # @yieldreturn [String] normalized SVG source
+        # @return [String, nil] expanded path when written, or nil when unchanged
+        # @raise [Sevgi::ArgumentError] when a selected path/default, render option, or XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @raise [SystemCallError] when the destination or backup cannot be created, read, or written
+        # @see Sevgi::Graphics::Document::Proto#call
+        def Save(path = nil, default: nil, backup_suffix: nil, **kwargs, &filter)
+          default = F.subext(EXT, caller_locations(1..1).first.path) if default.nil?
+          path = Path.resolve(path, default:, context: "Save")
 
-          Write(path, &filter)
+          Writer.(path, self.(**kwargs), backup_suffix:, &filter)
         end
 
         # Writes rendered SVG to a path.
-        # @param path [String] output path
-        # @param kwargs [Hash] render options
-        # @yield [content] optionally transforms rendered content before output
-        # @yieldparam content [String] rendered SVG source
-        # @yieldreturn [String] transformed SVG source
-        # @return [Object] F.out return value
+        # Missing parent directories are created. Unlike {#Save}, a directory is not treated as a request for a default
+        # file name.
+        # @param path [String, #to_path] output file path
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @yield [content] optionally normalizes old and new content for change detection
+        # @yieldparam content [String] old or new SVG source
+        # @yieldreturn [String] normalized SVG source
+        # @return [String, nil] expanded path when written, or nil when unchanged
+        # @raise [Sevgi::ArgumentError] when path, a render option, or an XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @raise [SystemCallError] when the destination cannot be read or written
+        # @see Sevgi::Graphics::Document::Proto#call
         def Write(path, **kwargs, &filter)
-          F.out(self.(**kwargs), path, &filter)
+          path = Path.(path, context: "Write path")
+          ArgumentError.("Write path must name a file") if ::File.directory?(path)
+
+          Writer.(path, self.(**kwargs), &filter)
         end
       end
     end

data/lib/sevgi/graphics/mixtures/symbols.rb

@@ -5,20 +5,89 @@ module Sevgi
     module Mixtures
       # DSL helpers for expanding callable modules into SVG symbols.
       module Symbols
-        # Renders module callables as symbols under defs.
-        # @param mod [Module] callable drawing module
+        # Builds one symbol set without adding helper methods to the document DSL.
+        # @api private
+        class Expansion
+          # Creates a symbol expansion.
+          # @param receiver [Sevgi::Graphics::Element] parent element
+          # @param mod [Module] module extended with {Sevgi::Graphics::Module}
+          # @return [void]
+          def initialize(receiver, mod)
+            @receiver = receiver
+            @mod = mod
+          end
+
+          # Builds a defs container and populates it from the callable module.
+          # @param args [Array<Object>] callable positional arguments
+          # @param attributes [Hash] defs attributes
+          # @param ids [#call, nil] symbol id mapper
+          # @param kwargs [Hash] callable keyword arguments
+          # @param block [Proc, nil] callable block argument
+          # @return [Sevgi::Graphics::Element] defs element
+          # @raise [Sevgi::ArgumentError] when an input channel is invalid
+          def call(*args, attributes:, ids:, **kwargs, &block)
+            methods = Graphics::Module.__send__(:callables, @mod)
+            ArgumentError.("Defs attributes must be a Hash") unless attributes.is_a?(::Hash)
+            ArgumentError.("Symbol ids must respond to call") if ids && !ids.respond_to?(:call)
+
+            defaults = @mod.name ? {id: F.demodulize(@mod.name).to_sym} : {}
+            attributes = Attribute.defaults(attributes, **defaults)
+            @args, @kwargs, @block = args, kwargs, block
+            @receiver.defs(**attributes).tap { populate(it, methods, ids) }
+          end
+
+          private
+
+          # Adds bases and symbols to a defs element.
+          # @param defs [Sevgi::Graphics::Element] defs element
+          # @param methods [Array<UnboundMethod>] callable methods
+          # @param ids [#call, nil] symbol id mapper
+          # @return [void]
+          def populate(defs, methods, ids)
+            context = Graphics::Module.__send__(:context, @mod, defs)
+            Graphics::Module.__send__(:bases, @mod).each { context.instance_exec(&it) }
+            methods.each { draw(defs, it, ids) }
+          end
+
+          # Adds one callable symbol.
+          # @param defs [Sevgi::Graphics::Element] defs element
+          # @param method [UnboundMethod] callable method
+          # @param ids [#call, nil] symbol id mapper
+          # @return [Object, nil] callable return value
+          def draw(defs, method, ids)
+            name = method.name
+            symbol = defs.symbol(id: ids ? ids.call(name) : name.to_s.tr("_", "-"))
+            symbol.title(name.to_s.split("_").map(&:capitalize).join(" "))
+            context = Graphics::Module.__send__(:context, @mod, symbol)
+            Graphics::Module.__send__(:invoke, context, symbol, [method], *@args, **@kwargs, &@block)
+          end
+        end
+
+        private_constant :Expansion
+
+        # Renders module callables as symbols under defs. Named modules default the defs id to their final constant name.
+        # anonymous modules omit the id unless supplied.
+        # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
-        # @param kwargs [Hash] defs attributes
-        # @yield [name] converts each callable name to a symbol id
-        # @yieldparam name [Symbol] callable method name
-        # @yieldreturn [String, Symbol] symbol id
+        # Base blocks run once in the defs element before symbols are created. Positional arguments, keyword arguments,
+        # and the block are forwarded to each callable.
+        # @example Expand named drawing methods into reusable symbols
+        #   icons = Module.new do
+        #     extend Sevgi::Graphics::Module
+        #     def dot = circle r: 2
+        #     def tick = path d: "M 0 2 L 2 4 L 6 0"
+        #   end
+        #   Sevgi::Graphics.SVG(:minimal) { Symbols icons }
+        # @param attributes [Hash] defs attributes. String and Symbol names are normalized and must not collide
+        # @param ids [#call, nil] optional callable mapping each method name to a symbol id
+        # @param kwargs [Hash] callable keyword arguments
+        # @yield forwarded to each callable
+        # @yieldreturn [Object] callable-defined block result
         # @return [Sevgi::Graphics::Element] defs element
-        # @raise [Sevgi::ArgumentError] when mod is not a plain module
-        def Symbols(mod, *args, **kwargs, &block)
-          CallWithin(mod, :defs, :symbol, *args, **kwargs) do |name, element|
-            element[:id] = block ? block.call(name) : name.to_s.split("_").join("-")
-            title(name.to_s.split("_").map(&:capitalize).join(" "))
-          end
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module, attributes is not a Hash, or ids is
+        #   not callable
+        def Symbols(mod, *args, attributes: {}, ids: nil, **kwargs, &block)
+          Expansion.new(self, mod).call(*args, attributes:, ids:, **kwargs, &block)
         end
       end
     end