Module: Sevgi::Graphics

Extended by:
Graphics
Included in:
Graphics
Defined in:
lib/sevgi/graphics.rb,
lib/sevgi/graphics/xml.rb,
lib/sevgi/graphics/element.rb,
lib/sevgi/graphics/version.rb,
lib/sevgi/graphics/document.rb,
lib/sevgi/graphics/mixtures.rb,
lib/sevgi/graphics/attribute.rb,
lib/sevgi/graphics/mixtures/rdf.rb,
lib/sevgi/graphics/document/base.rb,
lib/sevgi/graphics/document/html.rb,
lib/sevgi/graphics/mixtures/call.rb,
lib/sevgi/graphics/mixtures/core.rb,
lib/sevgi/graphics/mixtures/lint.rb,
lib/sevgi/graphics/mixtures/save.rb,
lib/sevgi/graphics/mixtures/tile.rb,
lib/sevgi/graphics/auxiliary/path.rb,
lib/sevgi/graphics/mixtures/hatch.rb,
lib/sevgi/graphics/auxiliary/paper.rb,
lib/sevgi/graphics/auxiliary/sizes.rb,
lib/sevgi/graphics/mixtures/export.rb,
lib/sevgi/graphics/mixtures/render.rb,
lib/sevgi/graphics/auxiliary/canvas.rb,
lib/sevgi/graphics/auxiliary/margin.rb,
lib/sevgi/graphics/auxiliary/scalar.rb,
lib/sevgi/graphics/document/default.rb,
lib/sevgi/graphics/document/minimal.rb,
lib/sevgi/graphics/mixtures/include.rb,
lib/sevgi/graphics/mixtures/symbols.rb,
lib/sevgi/graphics/auxiliary/content.rb,
lib/sevgi/graphics/document/inkscape.rb,
lib/sevgi/graphics/mixtures/identify.rb,
lib/sevgi/graphics/mixtures/inkscape.rb,
lib/sevgi/graphics/mixtures/validate.rb,
lib/sevgi/graphics/mixtures/wrappers.rb,
lib/sevgi/graphics/mixtures/duplicate.rb,
lib/sevgi/graphics/mixtures/polyfills.rb,
lib/sevgi/graphics/mixtures/transform.rb,
lib/sevgi/graphics/mixtures/underscore.rb

Overview

SVG document builder and DSL namespace.

A document profile controls root metadata and preambles; a Canvas controls physical size, margins, viewport, and viewBox. #SVG combines them into an element tree. Library code keeps that tree as an object until it explicitly renders, validates, saves, or exports it.

Examples:

Build and render a minimal SVG document

drawing = Sevgi::Graphics.SVG :minimal, width: 10, height: 10 do
  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 Also:

Defined Under Namespace

Modules: Document, Mixtures, Module, Modules Classes: Attributes, Canvas, Content, Element, Margin, Paper

Constant Summary collapse

VERSION =

Current graphics component version.

"0.98.2"
LintError =

Raised when graphics lint checks fail.

Class.new(Error)

Instance Method Summary collapse

Instance Method Details

#canvas(paper, **overrides) ⇒ Sevgi::Graphics::Canvas #canvas(width:, height:, unit: "mm", name: :custom, margins: []) ⇒ Sevgi::Graphics::Canvas

Examples:

Use the component constructor in library code

page = Sevgi::Graphics.canvas(:a4, margins: [12, 10])
icon = Sevgi::Graphics.canvas(width: 24, height: 24, unit: :px)
[page.name, icon.viewport] # => [:a4, {width: "24.0px", height: "24.0px"}]

Overloads:

  • #canvas(paper, **overrides) ⇒ Sevgi::Graphics::Canvas

    Builds a canvas from a paper profile with optional field overrides.

    Parameters:

    • paper (Sevgi::Graphics::Paper, Symbol, String) —

      paper object or registered profile

    • overrides (Hash) —

      canvas field overrides

    Returns:

    Raises:

    • (Sevgi::ArgumentError) —

      when the paper or an override is invalid

  • #canvas(width:, height:, unit: "mm", name: :custom, margins: []) ⇒ Sevgi::Graphics::Canvas

    Builds a canvas from an explicit size.

    Parameters:

    • width (Numeric) —

      canvas width

    • height (Numeric) —

      canvas height

    • unit (Symbol, String) (defaults to: "mm") —

      SVG unit

    • name (Symbol, String) (defaults to: :custom) —

      paper name

    • margins (Array<Numeric>) (defaults to: []) —

      margin shorthand values

    Returns:

    Raises:

    • (Sevgi::ArgumentError) —

      when a required field is omitted or a value is invalid



53
54
55
 
# File 'lib/sevgi/graphics.rb', line 53

def canvas(...)
  Graphics::Canvas.call(...)
end

#document(name) ⇒ Class #document(name, preambles: Undefined, attributes: Undefined) ⇒ Class #document(preambles: Undefined, attributes: Undefined) ⇒ Class

Returns document class.

Examples:

Define, look up, and inspect a named document

Sevgi::Graphics.document(:card, attributes: {viewBox: "0 0 100 60"})
Sevgi::Graphics::Document.fetch(:card)              # => the registered document class
Sevgi::Graphics::Document.profile(:card).attributes # => {viewBox: "0 0 100 60"}

Define an anonymous document without changing the registry

klass = Sevgi::Graphics.document(attributes: {viewBox: "0 0 10 10"})
klass.profile.name # => nil

Define and use a named profile from library code

Sevgi::Graphics.document(:badge, attributes: {viewBox: "0 0 24 24"})
drawing = Sevgi::Graphics.SVG(:badge) { circle cx: 12, cy: 12, r: 10 }
drawing[:viewBox] # => "0 0 24 24"

Overloads:

  • #document(name) ⇒ Class

    Looks up an existing document profile by name.

    Parameters:

    • name (Symbol, String) —

      profile name

    Returns:

    • (Class) —

      document class

    Raises:

    • (Sevgi::ArgumentError) —

      when the profile is unknown

  • #document(name, preambles: Undefined, attributes: Undefined) ⇒ Class

    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.

    Parameters:

    • name (Symbol, String) —

      profile name

    • preambles (Array<String>, nil, Sevgi::Undefined) (defaults to: Undefined) —

      document preamble lines

    • attributes (Hash, nil, Sevgi::Undefined) (defaults to: Undefined) —

      default root attributes; nil means an empty Hash

    Returns:

    • (Class) —

      document class

    Raises:

    • (Sevgi::ArgumentError) —

      when a profile conflicts or metadata is invalid XML, cyclic, or cannot be stringified

  • #document(preambles: Undefined, attributes: Undefined) ⇒ Class

    Defines an anonymous document profile without registering it globally.

    Parameters:

    • preambles (Array<String>, nil, Sevgi::Undefined) (defaults to: Undefined) —

      document preamble lines

    • attributes (Hash, nil, Sevgi::Undefined) (defaults to: Undefined) —

      default root attributes; nil means an empty Hash

    Returns:

    • (Class) —

      anonymous document class

    Raises:

    • (Sevgi::ArgumentError) —

      when metadata is invalid XML, cyclic, or cannot be stringified

Returns:

  • (Class) —

    document class



93
94
95
 
# File 'lib/sevgi/graphics.rb', line 93

def document(name = Undefined, preambles: Undefined, attributes: Undefined)
  Graphics::Document.define(name, preambles:, attributes:)
end

#document!(name, preambles: [], attributes: {}) ⇒ Class

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 bang form is an explicit process-global replacement.

Parameters:

  • name (Symbol, String) —

    profile name

  • preambles (Array<String>, nil) (defaults to: []) —

    document preamble lines

  • attributes (Hash, nil) (defaults to: {}) —

    default root attributes; nil means an empty Hash

Returns:

  • (Class) —

    document class

Raises:

  • (Sevgi::ArgumentError) —

    when the name or metadata is invalid XML, cyclic, or cannot be stringified



106
107
108
 
# File 'lib/sevgi/graphics.rb', line 106

def document!(name, preambles: [], attributes: {})
  Graphics::Document.define(name, preambles:, attributes:, overwrite: true)
end

#paper(width, height, name = :custom, unit: "mm") ⇒ Symbol, String

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.

Parameters:

  • width (Numeric) —

    paper width

  • height (Numeric) —

    paper height

  • name (Symbol, String) (defaults to: :custom) —

    profile name

  • unit (Symbol, String) (defaults to: "mm") —

    SVG unit

Returns:

  • (Symbol, String) —

    original profile name

Raises:

  • (Sevgi::ArgumentError) —

    when the profile is invalid or an existing profile has different dimensions



118
119
120
121
122
 
# File 'lib/sevgi/graphics.rb', line 118

def paper(width, height, name = :custom, unit: "mm")
  Graphics::Paper.define(name, width:, height:, unit:, overwrite: false)

  name
end

#paper!(width, height, name = :custom, unit: "mm") ⇒ Symbol, String

Defines or replaces a paper profile. Use this only when replacing the process-global meaning of a name is intentional.

Parameters:

  • width (Numeric) —

    paper width

  • height (Numeric) —

    paper height

  • name (Symbol, String) (defaults to: :custom) —

    profile name

  • unit (Symbol, String) (defaults to: "mm") —

    SVG unit

Returns:

  • (Symbol, String) —

    original profile name

Raises:

  • (Sevgi::ArgumentError) —

    when the profile is invalid or the profile name is reserved



132
133
134
 
# File 'lib/sevgi/graphics.rb', line 132

def paper!(width, height, name = :custom, unit: "mm")
  name.tap { Graphics::Paper.define(name, width:, height:, unit:, overwrite: true) }
end

#SVG(document = :default, canvas = Undefined) { ... } ⇒ Sevgi::Graphics::Document::Proto

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.

Parameters:

  • document (Symbol, String, Class) (defaults to: :default) —

    document profile name or document class

  • canvas (Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil) (defaults to: Undefined) —

    canvas input

Yields:

  • evaluates the drawing DSL in the root element

Yield Returns:

  • (Object) —

    ignored block result

Returns:

Raises:

  • (Sevgi::ArgumentError) —

    when the document/canvas profile or root XML attributes are invalid



146
147
148
 
# File 'lib/sevgi/graphics.rb', line 146

def SVG(document = :default, canvas = Undefined, **, &block)
  Graphics::Document.(document, canvas, **, &block)
end