Module: Sevgi::Toplevel

Included in:
Sevgi
Defined in:
lib/sevgi/toplevel.rb,
lib/sevgi/toplevel/derender.rb,
lib/sevgi/toplevel/executor.rb,
lib/sevgi/toplevel/function.rb,
lib/sevgi/toplevel/geometry.rb,
lib/sevgi/toplevel/graphics.rb,
lib/sevgi/toplevel/sundries.rb

Overview

Shared implementation for the full Sevgi top-level DSL.

This module is installed by include Sevgi or extend Sevgi; it should not normally be included directly.

See Also:

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:

Build a paper-backed canvas

canvas = Sevgi.Canvas :a4, margins: [12, 10]

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:

    • (Sevgi::Graphics::Canvas)

    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:

    • (Sevgi::Graphics::Canvas)

    Raises:

    • (Sevgi::ArgumentError) —

      when a required field is omitted or a value is invalid

See Also:



26
 
# File 'lib/sevgi/toplevel/graphics.rb', line 26

def Canvas(...) = Graphics.canvas(...)

#Decompile(content, id: nil, omit: nil) ⇒ Sevgi::Derender::Node

Converts inline SVG/XML content into a derender node.

Parameters:

  • content (String) —

    SVG/XML source content

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (Sevgi::Derender::Node) —

    selected node in the derender tree

Raises:

  • (Sevgi::ArgumentError) —

    when content is malformed or rootless, or the id is absent

See Also:



16
 
# File 'lib/sevgi/toplevel/derender.rb', line 16

def Decompile(content, id: nil, omit: nil) = Derender.decompile(content, id:, omit:)

#DecompileFile(file, id: nil, omit: nil) ⇒ Sevgi::Derender::Node

Converts an SVG/XML file into a derender node.

Parameters:

  • file (String) —

    path to the source SVG/XML file

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (Sevgi::Derender::Node) —

    selected node in the derender tree

Raises:

  • (Sevgi::ArgumentError) —

    when the file is absent, malformed, or rootless, or the id is absent

  • (SystemCallError) —

    when the file cannot be read

See Also:



28
 
# File 'lib/sevgi/toplevel/derender.rb', line 28

def DecompileFile(file, id: nil, omit: nil) = Derender.decompile_file(file, id:, omit:)

#Derender(content, id: nil, omit: nil) ⇒ String

Converts inline SVG/XML content into Sevgi DSL Ruby source.

Parameters:

  • content (String) —

    SVG/XML source content

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (String) —

    formatted Sevgi DSL source

Raises:

  • (Sevgi::ArgumentError) —

    when content is malformed or rootless, or the id is absent

  • (Sevgi::PanicError) —

    when generated Ruby source cannot be formatted

See Also:



40
 
# File 'lib/sevgi/toplevel/derender.rb', line 40

def Derender(content, id: nil, omit: nil) = Derender.derender(content, id:, omit:)

#DerenderFile(file, id: nil, omit: nil) ⇒ String

Converts an SVG/XML file into Sevgi DSL Ruby source.

Parameters:

  • file (String) —

    path to the source SVG/XML file

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (String) —

    formatted Sevgi DSL source

Raises:

  • (Sevgi::ArgumentError) —

    when the file is absent, malformed, or rootless, or the id is absent

  • (Sevgi::PanicError) —

    when generated Ruby source cannot be formatted

  • (SystemCallError) —

    when the file cannot be read

See Also:



53
 
# File 'lib/sevgi/toplevel/derender.rb', line 53

def DerenderFile(file, id: nil, omit: nil) = Derender.derender_file(file, id:, omit:)

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

Returns document class.

Examples:

Define and use a document profile

Sevgi.Document :icon, attributes: {viewBox: "0 0 24 24"}
drawing = Sevgi.SVG(:icon) { circle cx: 12, cy: 12, r: 10 }

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

    Defines or validates a named document profile.

    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

    Returns:

    • (Class) —

      document class

    Raises:

    • (Sevgi::ArgumentError) —

      when a profile conflicts or metadata is invalid

  • #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

    Returns:

    • (Class) —

      anonymous document class

    Raises:

    • (Sevgi::ArgumentError) —

      when metadata is invalid

Returns:

  • (Class) —

    document class

See Also:



52
 
# File 'lib/sevgi/toplevel/graphics.rb', line 52

def Document(...) = Graphics.document(...)

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

Defines or replaces a document profile.

Parameters:

  • name (Symbol, String) —

    profile name

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

    document preamble lines

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

    default root attributes

Returns:

  • (Class) —

    document class

Raises:

  • (Sevgi::ArgumentError) —

    when the name or metadata is invalid

See Also:



62
63
64
 
# File 'lib/sevgi/toplevel/graphics.rb', line 62

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

#Evaluate(content, element, id: nil, omit: nil) ⇒ Sevgi::Graphics::Element?

Evaluates inline SVG/XML content under a graphics element, including the selected node.

Parameters:

  • content (String) —

    SVG/XML source content

  • element (Sevgi::Graphics::Element) —

    target graphics element

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (Sevgi::Graphics::Element, nil) —

    included selected/root element, or nil when it produces no output

Raises:

  • (Sevgi::ArgumentError) —

    when content is malformed or rootless, or the id is absent

See Also:



65
 
# File 'lib/sevgi/toplevel/derender.rb', line 65

def Evaluate(content, element, id: nil, omit: nil) = Derender.evaluate(content, element, id:, omit:)

#EvaluateChildren(content, element, id: nil, omit: nil) ⇒ Array<Sevgi::Graphics::Element>

Evaluates only the selected node's children from inline SVG/XML content under a graphics element.

Parameters:

  • content (String) —

    SVG/XML source content

  • element (Sevgi::Graphics::Element) —

    target graphics element

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (Array<Sevgi::Graphics::Element>) —

    immutable included-child snapshot

Raises:

  • (Sevgi::ArgumentError) —

    when content is malformed or rootless, or the id is absent

See Also:



77
78
79
 
# File 'lib/sevgi/toplevel/derender.rb', line 77

def EvaluateChildren(content, element, id: nil, omit: nil)
  Derender.evaluate_children(content, element, id:, omit:)
end

#EvaluateChildrenFile(file, element, id: nil, omit: nil) ⇒ Array<Sevgi::Graphics::Element>

Evaluates only the selected node's children from an SVG/XML file under a graphics element.

Parameters:

  • file (String) —

    path to the source SVG/XML file

  • element (Sevgi::Graphics::Element) —

    target graphics element

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (Array<Sevgi::Graphics::Element>) —

    immutable included-child snapshot

Raises:

  • (Sevgi::ArgumentError) —

    when the file is absent, malformed, or rootless, or the id is absent

  • (SystemCallError) —

    when the file cannot be read

See Also:



92
93
94
 
# File 'lib/sevgi/toplevel/derender.rb', line 92

def EvaluateChildrenFile(file, element, id: nil, omit: nil)
  Derender.evaluate_children_file(file, element, id:, omit:)
end

#EvaluateFile(file, element, id: nil, omit: nil) ⇒ Sevgi::Graphics::Element?

Evaluates an SVG/XML file under a graphics element, including the selected node.

Parameters:

  • file (String) —

    path to the source SVG/XML file

  • element (Sevgi::Graphics::Element) —

    target graphics element

  • id (String, Symbol, nil) (defaults to: nil) —

    optional SVG id selecting a node inside the source

  • omit (String, Symbol, Array<String, Symbol>, nil) (defaults to: nil) —

    exact attribute name or names omitted from the selected subtree after id selection

Returns:

  • (Sevgi::Graphics::Element, nil) —

    included selected/root element, or nil when it produces no output

Raises:

  • (Sevgi::ArgumentError) —

    when the file is absent, malformed, or rootless, or the id is absent

  • (SystemCallError) —

    when the file cannot be read

See Also:



107
 
# File 'lib/sevgi/toplevel/derender.rb', line 107

def EvaluateFile(file, element, id: nil, omit: nil) = Derender.evaluate_file(file, element, id:, omit:)

#Grid(canvas, unit:, multiple:) ⇒ Sevgi::Sundries::Grid

Builds a drawable grid fitted inside a graphics canvas.

The canvas margins are minimum clearances. Any span left after fitting whole major intervals is shared equally between the opposite margins, so their requested difference is preserved. The returned grid starts at (0, 0); Sundries::Grid#canvas exposes the fitted page margins.

Parameters:

  • canvas (Sevgi::Graphics::Canvas) —

    canvas defining page size and margins

  • unit (Numeric) —

    minor grid unit

  • multiple (Integer) —

    number of minor units in each major interval

Returns:

  • (Sevgi::Sundries::Grid) —

    grid fitted to the canvas

Raises:

  • (Sevgi::ArgumentError) —

    when canvas is not a graphics canvas

  • (Sevgi::ArgumentError) —

    when unit is not a finite positive number

  • (Sevgi::ArgumentError) —

    when multiple is not a positive integer

  • (Sevgi::ArgumentError) —

    when canvas dimensions, margins, and grid intervals cannot fit

See Also:



23
24
25
26
27
28
29
30
31
 
# File 'lib/sevgi/toplevel/sundries.rb', line 23

def Grid(canvas, unit:, multiple:)
  ArgumentError.("Must be a Canvas: #{canvas}") unless canvas.is_a?(Graphics::Canvas)

  Sundries::Grid.new(
    x: Sundries::Ruler.new(brut: canvas.width, unit:, multiple:, margins: [canvas.left, canvas.right]),
    y: Sundries::Ruler.new(brut: canvas.height, unit:, multiple:, margins: [canvas.top, canvas.bottom]),
    canvas:
  )
end

#Load(*files) ⇒ Array<String>

Note:

Load resolves against the active executor scope in the current fiber.

Note:

Ordinary library code should use Ruby require; Load is available only during Sevgi script execution.

Loads one or more Sevgi files relative to the caller's source file.

Parameters:

  • files (Array<String>) —

    Sevgi script files to locate and execute

Returns:

  • (Array<String>) —

    the input file list

Raises:

  • (Sevgi::PanicError) —

    when called without an active executor scope

  • (Sevgi::Error) —

    when a file cannot be located

See Also:



77
78
79
80
81
82
83
84
85
 
# File 'lib/sevgi/toplevel/executor.rb', line 77

def Load(*files)
  start = ::File.dirname(caller_locations(1..1).first.path)

  files.each do |file|
    location = F.locate(file, start)

    ::Sevgi::Executor.__send__(:load, location.file)
  end
end

#Mixin(mod, document = Sevgi::Graphics::Document::Base) ⇒ nil #Mixin(mod, document = Sevgi::Graphics::Document::Base) { ... } ⇒ Module #Mixin(document = Sevgi::Graphics::Document::Base) { ... } ⇒ Module

Overloads:

  • #Mixin(mod, document = Sevgi::Graphics::Document::Base) ⇒ nil

    Adds a named graphics mixture to a document class.

    Parameters:

    • mod (Symbol, String) —

      named mixture to mix into the document

    • document (Class) (defaults to: Sevgi::Graphics::Document::Base) —

      document class receiving the mixture

    Returns:

    • (nil)

    Raises:

    • (NameError) —

      when a named mixture cannot be resolved

    See Also:

  • #Mixin(mod, document = Sevgi::Graphics::Document::Base) { ... } ⇒ Module

    Adds a named graphics mixture and an anonymous extension to a document class.

    Parameters:

    • mod (Symbol, String) —

      named mixture to mix into the document

    • document (Class) (defaults to: Sevgi::Graphics::Document::Base) —

      document class receiving the mixture

    Yields:

    • optional anonymous mixture module body

    Yield Returns:

    • (void)

    Returns:

    • (Module) —

      anonymous mixture

    Raises:

    • (NameError) —

      when a named mixture cannot be resolved

    See Also:

  • #Mixin(document = Sevgi::Graphics::Document::Base) { ... } ⇒ Module

    Adds an anonymous graphics mixture to a document class.

    Parameters:

    • document (Class) (defaults to: Sevgi::Graphics::Document::Base) —

      document class receiving the mixture

    Yields:

    • anonymous mixture module body

    Yield Returns:

    • (void)

    Returns:

    • (Module) —

      anonymous mixture

    Raises:

    • (Sevgi::ArgumentError) —

      when no named mixture or block is given

    See Also:



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

def Mixin(...) = Graphics::Mixtures.mixin(...)

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

Defines or validates a named paper profile for DSL use.

Parameters:

  • width (Numeric) —

    paper width

  • height (Numeric) —

    paper height

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

    paper profile name

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

    size unit

Returns:

  • (Symbol, String) —

    the original paper profile name

Raises:

  • (Sevgi::ArgumentError) —

    when the profile is invalid or an existing profile differs

See Also:



120
 
# File 'lib/sevgi/toplevel/graphics.rb', line 120

def Paper(...) = Graphics.paper(...)

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

Defines or overwrites a named paper profile for DSL use.

Parameters:

  • width (Numeric) —

    paper width

  • height (Numeric) —

    paper height

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

    paper profile name

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

    size unit

Returns:

  • (Symbol, String) —

    the original paper profile name

Raises:

  • (Sevgi::ArgumentError) —

    when the profile is invalid or the paper name is reserved

See Also:



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

def Paper!(...) = Graphics.paper!(...)

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

Builds an SVG document through the full Sevgi top-level DSL.

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) —

    optional canvas or paper profile

  • attributes (Hash) —

    root SVG attributes

Yields:

  • the document block evaluated in the SVG document context

Yield Returns:

  • (void)

Returns:

  • (Sevgi::Graphics::Document::Proto) —

    SVG document object

Raises:

  • (Sevgi::ArgumentError) —

    when the document, paper, or canvas arguments are invalid

See Also:

  • SVG
  • Graphics.SVG


77
78
79
 
# File 'lib/sevgi/toplevel/graphics.rb', line 77

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