sevgi-graphics 0.98.2 → 1.0.0

data/lib/sevgi/graphics.rb

@@ -15,7 +15,7 @@ require_relative "graphics/version"
 module Sevgi
   # SVG document builder and DSL namespace.
   #
-  # A document profile controls root metadata and preambles; a {Canvas} controls
+  # A document profile controls root metadata and preambles. A {Canvas} controls
   # physical size, margins, viewport, and viewBox. {Graphics.SVG} combines them
   # into an element tree. Library code keeps that tree as an object until it
   # explicitly renders, validates, saves, or exports it.
@@ -25,9 +25,9 @@ module Sevgi
   #     circle cx: 5, cy: 5, r: 4
   #   end
   #   drawing.Render #=> "<svg width=\"10\" height=\"10\">\n  <circle cx=\"5\" cy=\"5\" r=\"4\"/>\n</svg>"
-  # @see https://sevgi.roktas.dev/svg/ SVG construction and profile guide
-  # @see https://sevgi.roktas.dev/library-mode/ Library composition guide
-  # @see https://sevgi.roktas.dev/showcase/ Runnable drawing examples
+  # @see https://sevgi.roktas.dev/documents/ SVG construction and profile guide
+  # @see https://sevgi.roktas.dev/compose/ Composition guide
+  # @see https://sevgi.roktas.dev/examples/ Runnable drawing examples
   # @see Sevgi::Graphics::Document
   # @see Sevgi::Graphics::Canvas
   module Graphics
@@ -63,19 +63,18 @@ module Sevgi
     #   Looks up a named profile when both definition keywords are omitted. Supplying `preambles:` or `attributes:`
     #   defines a named profile, or returns an existing profile when every explicitly supplied field matches. Omitted
     #   fields are ignored during existing-profile comparison. Profile containers and strings are copied into the
-    #   process-global, thread-atomic registry; attribute names and nested Hash keys are normalized, nil attributes are
-    #   omitted, update suffixes are retained for document-class inheritance, and mutable non-container values are
-    #   stringified once before registration. Concurrent identical definitions return the same canonical registered
-    #   class.
+    #   process-global, thread-atomic registry. Attribute names and nested Hash keys are normalized. Nil attributes are
+    #   omitted. Update suffixes remain available for document-class inheritance. Mutable non-container values are
+    #   stringified once before registration. Concurrent identical definitions return the same registered class.
     #   @param name [Symbol, String] profile name
     #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
-    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes. Nil means an empty Hash
     #   @return [Class] document class
     #   @raise [Sevgi::ArgumentError] when a profile conflicts or metadata is invalid XML, cyclic, or cannot be stringified
     # @overload document(preambles: Undefined, attributes: Undefined)
     #   Defines an anonymous document profile without registering it globally.
     #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
-    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes. Nil means an empty Hash
     #   @return [Class] anonymous document class
     #   @raise [Sevgi::ArgumentError] when metadata is invalid XML, cyclic, or cannot be stringified
     # @return [Class] document class
@@ -96,19 +95,20 @@ module Sevgi
 
     # Defines or replaces a document profile class.
     # Validation and snapshot capture complete before an existing registration is atomically replaced.
-    # Use the non-bang {#document} for ordinary idempotent definitions; this
+    # Use the non-bang {#document} for ordinary idempotent definitions. This
     # bang form is an explicit process-global replacement.
     # @param name [Symbol, String] profile name
     # @param preambles [Array<String>, nil] document preamble lines
-    # @param attributes [Hash, nil] default root attributes; nil means an empty Hash
+    # @param attributes [Hash, nil] default root attributes. Nil means an empty Hash
     # @return [Class] document class
     # @raise [Sevgi::ArgumentError] when the name or metadata is invalid XML, cyclic, or cannot be stringified
     def document!(name, preambles: [], attributes: {})
       Graphics::Document.define(name, preambles:, attributes:, overwrite: true)
     end
 
-    # Defines a paper profile unless the same profile already exists. Registration is process-global and thread-atomic;
-    # an identical concurrent definition is idempotent and a conflicting definition is rejected.
+    # Defines a paper profile unless the same profile already exists.
+    # Registration is process-global and thread-atomic. Identical concurrent definitions are idempotent. Conflicting
+    # definitions are rejected.
     # @param width [Numeric] paper width
     # @param height [Numeric] paper height
     # @param name [Symbol, String] profile name
@@ -135,15 +135,20 @@ module Sevgi
 
     # Builds an SVG root element tree without rendering it.
     #
-    # The first argument selects root metadata; the second supplies physical
-    # canvas attributes. Keyword attributes are applied to the root after both.
-    # @param document [Symbol, String, Class] document profile name or document class
+    # The first argument selects root metadata, or supplies the canvas while using the default profile. The second
+    # supplies canvas attributes when the first argument is a profile. Keyword attributes are applied after both.
+    # @param document [Symbol, String, Class, Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper] document profile,
+    #   document class, or canvas input that uses the default profile
     # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] canvas input
     # @yield evaluates the drawing DSL in the root element
     # @yieldreturn [Object] ignored block result
     # @return [Sevgi::Graphics::Document::Proto] SVG root element
     # @raise [Sevgi::ArgumentError] when the document/canvas profile or root XML attributes are invalid
     def SVG(document = :default, canvas = Undefined, **, &block)
+      if canvas.equal?(Undefined) && (document.is_a?(Canvas) || document.is_a?(Paper))
+        document, canvas = :default, document
+      end
+
       Graphics::Document.(document, canvas, **, &block)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-graphics
 version: !ruby/object:Gem::Version
-  version: 0.98.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 description: Builds and renders SVG document trees from Ruby.
 email: roktas@gmail.com
 executables: []
@@ -93,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Core SVG DSL for Sevgi.
 test_files: []