victor 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cfb9ab7b01c8fe3986d973cf09708e47b05ec61d726f4db2e5c94f5b7697d8b
-  data.tar.gz: 55936a274c2b1f662ad6dfb4aacb8396499fe6f5c7366d33fde7858e082d02d1
+  metadata.gz: 86eac1cab671c40d60409cf11e0e06800add519f2a11e80f33adbb8a516b7906
+  data.tar.gz: ff574def00c021acf82c0071ce6d9467576a74e0651663ecd7291ca2e5884ea7
 SHA512:
-  metadata.gz: 59e8f7b5c39d6c156b322eecd4719ecb3e036e51484ba915c4642400c3ec3547b79f057a4717188ff67e7b8aee9f999f1d493552e88cbb344ff2fe9e521ca087
-  data.tar.gz: 560fe1f61b66cce12912073349b33b1ad73c656ad47780be3c713deb735d3d71a1d2bdb896c419447a7a84ad73360bfc080b56bb69113c2874641826c8519fa3
+  metadata.gz: 1fa1657d2e98c4bf98468f9f1e9a69a07c0c049eac6033d0bb3d2bbe603627cb448034923f94e6aef31db755ca66916a484ad521c86534c32274ef764a31ed79
+  data.tar.gz: 1a0662ce919d6abed8bea839c4fef03f7314960dbeaa5602b1627b44e4f69082e3ce933de57170c17973a58ab8f61ee7bb214796c99e641b35a3dec59a54d945

data/README.md

@@ -1,4 +1,5 @@
-![Victor](/examples/16_victor_logo.svg)
+<div align='center'>
+<img src='assets/logo.svg' width=500>
 
 # Victor - Ruby SVG Image Builder
 
@@ -6,12 +7,14 @@
 [![Build Status](https://github.com/DannyBen/victor/workflows/Test/badge.svg)](https://github.com/DannyBen/victor/actions?query=workflow%3ATest)
 [![Maintainability](https://api.codeclimate.com/v1/badges/85cc05c219d6d233ab78/maintainability)](https://codeclimate.com/github/DannyBen/victor/maintainability)
 
----
+## [victor.dannyb.co](https://victor.dannyb.co)
+
+</div>
 
-Victor is a direct Ruby-to-SVG builder. All method calls are converted
-directly to SVG elements.
+---
 
-![Demo](assets/animated.gif)
+**Victor** is a lightweight, zero-dependencies Ruby library that lets you build
+SVG images using Ruby code.
 
 ---
 
@@ -21,472 +24,46 @@ directly to SVG elements.
 $ gem install victor
 ```
 
-Or with bundler:
-
-```ruby
-gem 'victor'
-```
-
-## Examples
-
-```ruby
-require 'victor'
-
-svg = Victor::SVG.new width: 140, height: 100, style: { background: '#ddd' }
-
-svg.build do 
-  rect x: 10, y: 10, width: 120, height: 80, rx: 10, fill: '#666'
-  
-  circle cx: 50, cy: 50, r: 30, fill: 'yellow'
-  circle cx: 58, cy: 32, r: 4, fill: 'black'
-  polygon points: %w[45,50 80,30 80,70], fill: '#666'
-
-  3.times do |i|
-    x = 80 + i*18
-    circle cx: x, cy: 50, r: 4, fill: 'yellow'
-  end
-end
-
-svg.save 'pacman'
-```
-
-Output:
-
-[![pacman](https://cdn.rawgit.com/DannyBen/victor/master/examples/10_pacman.svg)](https://github.com/DannyBen/victor/blob/master/examples/10_pacman.rb)
-
-
-See the [examples] folder for several ruby scripts and their SVG output.
-
-
-## Usage
-
-Initialize your SVG image:
-
-```ruby
-require 'victor'
-svg = Victor::SVG.new
-```
-
-Any option you provide to `SVG.new` will be added as an attribute to the
-main `<svg>` element. By default, `height` and `width` are set to 100%.
-
-```ruby
-svg = Victor::SVG.new width: '100%', height: '100%'
-# same as just Victor::SVG.new
-
-svg = Victor::SVG.new width: '100%', height: '100%', viewBox: "0 0 200 100"
-```
-
-As an alternative, you can set the root SVG attributes using the `setup` method:
-
-```ruby
-require 'victor'
-svg = Victor::SVG.new
-svg.setup width: 200, height: 150
-```
-
-Victor uses a single method (`element`) to generate all SVG elements:
-
-```ruby
-svg.element :rect, x: 2, y: 2, width: 200, height: 200
-# => <rect x="2" y="2" width="200" height="200"/>
-```
-
-But you can omit it. Calls to any other method, will be delegated to the 
-`element` method, so normal usage looks more like this:
-
-```ruby
-svg.rect x: 2, y: 2, width: 200, height: 200
-# => <rect x="2" y="2" width="200" height="200"/>
-```
-
-In other words, these are the same:
-
-```ruby
-svg.element :anything, option: 'value'
-svg.anything option: 'value'
-```
-
-You can use the `build` method, to generate the SVG with a block
-
-```ruby
-svg.build do 
-  rect x: 0, y: 0, width: 100, height: 100, fill: '#ccc'
-  rect x: 20, y: 20, width: 60, height: 60, fill: '#f99'
-end
-```
-
-If the value of an attribute is a hash, it will be converted to a 
-style-compatible string:
-
-```ruby
-svg.rect x: 0, y: 0, width: 100, height: 100, style: { stroke: '#ccc', fill: 'red' }
-# => <rect x=0 y=0 width=100 height=100 style="stroke:#ccc; fill:red"/>
-```
-
-If the value of an attribute is an array, it will be converted to a 
-space delimited string:
-
-```ruby
-svg.path d: ['M', 150, 0, 'L', 75, 200, 'L', 225, 200, 'Z']
-# => <path d="M 150 0 L 75 200 L 225 200 Z"/>
-```
-
-For SVG elements that have an inner content - such as text - simply pass it as 
-the first argument:
-
-```ruby
-svg.text "Victor", x: 40, y: 50
-# => <text x="40" y="50">Victor</text>
-```
-
-You can also nest elements with blocks:
-
-```ruby
-svg.build do
-  g font_size: 30, font_family: 'arial', fill: 'white' do
-    text "Scalable Victor Graphics", x: 40, y: 50
-  end
-end
-# => <g font-size="30" font-family="arial" fill="white">
-#      <text x="40" y="50">Scalable Victor Graphics</text>
-#    </g>
-```
-
-Underscores in attribute names are converted to dashes:
-
-```ruby
-svg.text "Victor", x: 40, y: 50, font_family: 'arial', font_weight: 'bold', font_size: 40
-# => <text x="40" y="50" font-family="arial" font-weight="bold" font-size="40">
-#      Victor
-#    </text>
-```
-
-## Features
-
-### Composite SVG
-
-Victor also supports the ability to combine several smaller SVG objects into
-one using the `<<` operator or the `#append` method. 
-
-This operator expects to receive any object that responds to `#to_s` (can be another `SVG` object).
-
-```ruby
-require 'victor'
-include Victor
-
-# Create a reusable SVG object
-frame = SVG.new
-frame.rect x: 0, y: 0, width: 100, height: 100, fill: '#336'
-frame.rect x: 10, y: 10, width: 80, height: 80, fill: '#fff'
-
-# ... and another
-troll = SVG.new
-troll.circle cx: 50, cy: 60, r: 24, fill: 'yellow'
-troll.polygon points: %w[24,50 50,14 76,54], fill: 'red'
-
-# Combine objects into a single image
-svg = SVG.new viewBox: '0 0 100 100'
-svg << frame
-svg << troll
-
-# ... and save it
-svg.save 'framed-troll'
-```
-
-Output:
-
-[![troll](https://cdn.rawgit.com/DannyBen/victor/master/examples/14_composite_svg.svg)](https://cdn.rawgit.com/DannyBen/victor/master/examples/14_composite_svg.svg)
-
-These two calls are identical:
-
-```ruby
-svg << other
-svg.append other
-```
-
-To make this common use case a little easier to use, you can use a block when instantiating a new `SVG` object:
-
-```ruby
-troll = SVG.new do
-  circle cx: 50, cy: 60, r: 24, fill: 'yellow'
-end
-```
-
-Which is the same as:
-
-```ruby
-troll = SVG.new
-troll.build do
-  circle cx: 50, cy: 60, r: 24, fill: 'yellow'
-end
-```
-
-Another approach to a more modular SVG composition, would be to subclass 
-`Victor::SVG`.
-
-See the [composite svg example](https://github.com/DannyBen/victor/tree/master/examples#14-composite-svg)
-or the [subclassing example](https://github.com/DannyBen/victor/tree/master/examples#15-subclassing)
-for more details.
-
-
-### Saving the Output
-
-Generate the full SVG to a string with `render`:
-
-```ruby
-result = svg.render
-```
-
-Or, save it to a file with `save`:
-
-```ruby
-svg.save 'filename'
-# the '.svg' extension is optional
-```
-
-### SVG Templates
-
-Victor renders its content using the [`:default` template][default-template].
-
-If you wish to use another template, you can either use one of the built-in
-templates (`:default` or `:minimal`), or provide your own:
-
-```ruby
-svg = Victor::SVG.new template: :minimal
-svg = Victor::SVG.new template: 'path/to/template.svg'
-```
-
-See the [templates] folder for an understanding of how templates are 
-structured.
-
-Templates can also be provided when rendering or saving the output:
-
-```ruby
-svg.save 'filename', template: :minimal
-svg.render template: :minimal
-```
-
-
-### CSS
-
-CSS gets a special treatment in `Victor::SVG`, in order to provide a DSL-like
-syntax for CSS rules.
-
-The `Victor::SVG` object has a `css` property, which can contain either a 
-Hash or a String:
-
-```ruby
-svg = Victor::SVG.new
-
-svg.css = css_hash_or_string
-# or without the equal sign:
-svg.css css_hash_or_string
-
-svg.build do
-  # ...
-end
-```
-
-This flexibility allows you to apply CSS in multiple ways. Below are some
-examples.
-
-#### Assigning CSS rules using the hash syntax
-
-```ruby
-svg = Victor::SVG.new
-
-svg.build do 
-  css['.main'] = {
-    stroke: "green", 
-    stroke_width: 2,
-    fill: "yellow"
-  }
-
-  circle cx: 35, cy: 35, r: 20, class: 'main'
-end
-```
-
-#### Assigning a full hash to the CSS property
+## Example
 
-```ruby
-svg.css = {
-  '.bar': {
-    fill: '#666',
-    stroke: '#fff',
-    stroke_width: 1
-  },
-  '.negative': {
-    fill: '#f66'
-  },
-  '.positive': {
-    fill: '#6f6'
-  }
-}
-```
-
-Underscore characters will be converted to dashes (`stroke_width` becomes 
-`stroke-width`).
-
-#### Importing CSS from an external file
-
-```ruby
-svg.css = File.read 'styles.css'
-```
+<table><tr><td width="250">
 
-#### CSS `@import` directives
+<img src='assets/ghost.svg' width=250>
 
-If you need to add CSS statements , like `@import`, use the following syntax:
+</td><td>
 
 ```ruby
-css['@import'] = [
-  "url('https://fonts.googleapis.com/css?family=Audiowide')",
-  "url('https://fonts.googleapis.com/css?family=Pacifico')"
-]
-```
-
-This is achieved thanks to the fact that when Victor encounters an array
-in the CSS hash, it will prefix each of the array elements with the hash
-key, so the above will result in two `@import url(...)` rows.
-
-See the [css example](https://github.com/DannyBen/victor/tree/master/examples#08-css),
-[css string example](https://github.com/DannyBen/victor/tree/master/examples#09-css-string),
-or the [custom fonts example](https://github.com/DannyBen/victor/tree/master/examples#13-custom-fonts).
-
-
-### Tagless Elements
-
-Using underscore (`_`) as the element name will simply add the value to the 
-generated SVG, without any surrounding element. This is designed to allow
-generating something like this:
+setup viewBox: '0 0 100 100'
 
-```xml
-<text>
-  You are
-  <tspan font-weight="bold">not</tspan>
-  a banana
-</text>
-```
-
-using this Ruby code:
+build do
+  rect x: 0, y: 0, width: 100, height: 100, fill: :white
+  circle cx: 50, cy: 50, r: 40, fill: 'yellow'
+  rect x: 10, y: 50, width: 80, height: 50, fill: :yellow
 
-```ruby
-svg.build do 
-  text do
-    _ 'You are'
-    tspan 'not', font_weight: "bold"
-    _ 'a banana'
+  [25, 50].each do |x|
+    circle cx: x, cy: 40, r: 8, fill: :white
   end
-end
-```
-
-See the [tagless elements example](https://github.com/DannyBen/victor/tree/master/examples#17-tagless-elements).
-
-
-### XML Encoding
-
-Plain text values are encoded automatically:
-
-```ruby
-svg.build do
-  text "Ben & Jerry's"
-end
-# <text>Ben &amp; Jerry's</text>
-```
-
-If you need to use the raw, unencoded string, add `!` to the element's name:
-
-```ruby
-svg.build do
-  text! "Ben & Jerry's"
-end
-# <text>Ben & Jerry's</text>
-```
-
-See the [xml encoding example](https://github.com/DannyBen/victor/tree/master/examples#18-xml-encoding).
-
-
-### XML Newlines
-
-By default, the generated SVGs will have a newline glue between the elements.
-You can change this (for example, to an empty string) if the default newlines
-are not appropriate for your use case.
-
-```ruby
-svg = Victor::SVG.new glue: ''
-```
 
-The glue can also be provided when rendering or saving the output:
-
-```ruby
-svg.save 'filename', glue: ''
-svg.render glue: ''
-```
-
-### DSL Syntax
-
-Victor also supports a DSL-like syntax. To use it, simply `require 'victor/script'`.
-
-Once required, you have access to:
-
-- `svg` - returns an instance of `Victor::SVG`
-- All the methods that are available on the `SVG` object, are included at the root level.
-
-For example:
-
-```ruby
-require 'victor/script'
-
-setup width: 100, height: 100
-
-build do
-  circle cx: 50, cy: 50, r: 30, fill: "yellow"
+  path fill: 'white', d: %w[
+    M11 100 l13 -15 l13 15 l13 -15 
+    l13 15 l13 -15 l13 15 Z
+  ]
 end
-
-puts render
-save 'output.svg'
 ```
 
-See the [dsl example](https://github.com/DannyBen/victor/tree/master/examples#19-dsl).
-
-## Related Projects
-
-### [Victor CLI][victor-cli]
-
-A command line utility that allows converting Ruby to SVG as well as SVG to
-Victor Ruby scripts.
-
-### [Victor Opal][victor-opal]
-
-A Victor playground that works in the browser.
-
-### [Minichart][minichart]
+</td></tr></table>
 
-A Ruby gem that uses Victor to generate SVG charts
 
-[![Minichart](assets/minichart.svg)][minichart]
-
-
-### [Icodi][icodi]
-
-A Ruby gem that uses Victor to generate consistent random icon 
-images, similar to GitHub's identicon.
-
-[![Icodi](assets/icodi.svg)][icodi]
+## Documentation
 
+- [Victor Homepage][docs]
 
 ## Contributing / Support
 
 If you experience any issue, have a question or a suggestion, or if you wish
-to contribute, feel free to [open an issue][issues].
-
----
+to contribute, feel free to [open an issue][issues] or
+[start a discussion][discussions].
 
-[examples]: https://github.com/DannyBen/victor/tree/master/examples#examples
-[templates]: https://github.com/DannyBen/victor/tree/master/lib/victor/templates
-[default-template]: https://github.com/DannyBen/victor/blob/master/lib/victor/templates/default.svg?short_path=c28efa4
-[icodi]: https://github.com/DannyBen/icodi
-[minichart]: https://github.com/DannyBen/minichart
-[victor-opal]: https://kuboon.github.io/victor-opal/
-[victor-cli]:  https://github.com/DannyBen/victor-cli
 [issues]: https://github.com/DannyBen/victor/issues
+[discussions]: https://github.com/DannyBen/victor/discussions
+[docs]: https://victor.dannyb.co/

data/lib/victor/component.rb

@@ -0,0 +1,61 @@
+require 'forwardable'
+
+module Victor
+  class Component
+    extend Forwardable
+    include Marshaling
+
+    def_delegators :svg, :save, :render, :content, :element, :tag, :css, :to_s
+
+    # Marshaling data
+    def marshaling = %i[width height x y svg merged_css]
+
+    # Subclasses MUST implement this
+    def body
+      raise(NotImplementedError, "#{self.class.name} must implement `body'")
+    end
+
+    # Subclasses MUST override these methods, OR assign instance vars
+    def height
+      @height || raise(NotImplementedError,
+        "#{self.class.name} must implement `height' or `@height'")
+    end
+
+    def width
+      @width || raise(NotImplementedError,
+        "#{self.class.name} must implement `width' or `@width'")
+    end
+
+    # Subclasses MAY override these methods, OR assign instance vars
+    def style = @style ||= {}
+    def x = @x ||= 0
+    def y = @y ||= 0
+
+    # Appending/Embedding - DSL for the `#body` implementation
+    def append(component)
+      svg_instance.append component.svg
+      merged_css.merge! component.merged_css
+    end
+    alias embed append
+
+    # SVG / CSS
+    def svg
+      @svg ||= begin
+        body
+        svg_instance.css = merged_css
+        svg_instance
+      end
+    end
+
+  protected
+
+    # Start with an ordinary SVG instance
+    def svg_instance = @svg_instance ||= SVG.new(viewBox: "#{x} #{y} #{width} #{height}")
+
+    # Internal DSL to enable `add.anything` in the `#body` implementation
+    alias add svg_instance
+
+    # Start with a copy of our own style
+    def merged_css = @merged_css ||= style.dup
+  end
+end

data/lib/victor/dsl.rb

@@ -3,7 +3,7 @@ require 'forwardable'
 module Victor
   module DSL
     extend Forwardable
-    def_delegators :svg, :setup, :build, :save, :render, :append, :element, :css
+    def_delegators :svg, :setup, :build, :save, :render, :append, :element, :tag, :css
 
     def svg
       @svg ||= Victor::SVG.new

data/lib/victor/marshaling.rb

@@ -1,39 +1,33 @@
 module Victor
   module Marshaling
+    def marshaling
+      raise NotImplementedError, "#{self.class.name} must implement `marshaling'"
+    end
+
     # YAML serialization methods
     def encode_with(coder)
-      coder['template'] = @template
-      coder['glue'] = @glue
-      coder['svg_attributes'] = @svg_attributes
-      coder['css'] = @css
-      coder['content'] = @content
+      marshaling.each do |attr|
+        coder[attr.to_s] = send(attr)
+      end
     end
 
     def init_with(coder)
-      @template = coder['template']
-      @glue = coder['glue']
-      @svg_attributes = coder['svg_attributes']
-      @css = coder['css']
-      @content = coder['content']
+      marshaling.each do |attr|
+        instance_variable_set(:"@#{attr}", coder[attr.to_s])
+      end
     end
 
     # Marshal serialization methods
     def marshal_dump
-      {
-        template:       @template,
-        glue:           @glue,
-        svg_attributes: @svg_attributes,
-        css:            @css,
-        content:        @content,
-      }
+      marshaling.to_h do |attr|
+        [attr, send(attr)]
+      end
     end
 
     def marshal_load(data)
-      @template = data[:template]
-      @glue = data[:glue]
-      @svg_attributes = data[:svg_attributes]
-      @css = data[:css]
-      @content = data[:content]
+      marshaling.each do |attr|
+        instance_variable_set(:"@#{attr}", data[attr])
+      end
     end
   end
 end

data/lib/victor/svg.rb

@@ -1,7 +1,7 @@
 module Victor
   class SVG < SVGBase
     def method_missing(method_sym, ...)
-      element(method_sym, ...)
+      tag(method_sym, ...)
     end
 
     def respond_to_missing?(*)

data/lib/victor/svg_base.rb

@@ -12,10 +12,15 @@ module Victor
       build(&block) if block
     end
 
+    def marshaling
+      %i[template glue svg_attributes css content]
+    end
+
     def <<(additional_content)
       content.push additional_content.to_s
     end
     alias append <<
+    alias embed <<
 
     def setup(attributes = nil)
       attributes ||= {}
@@ -35,7 +40,7 @@ module Victor
       instance_eval(&block)
     end
 
-    def element(name, value = nil, attributes = {})
+    def tag(name, value = nil, attributes = {})
       if value.is_a? Hash
         attributes = value
         value = nil
@@ -63,6 +68,7 @@ module Victor
         content.push "<#{name} #{attributes}/>"
       end
     end
+    alias element tag
 
     def css(defs = nil)
       @css ||= {}

data/lib/victor/templates/default.svg

@@ -1,8 +1,4 @@
-<svg %{attributes} 
-  xmlns="http://www.w3.org/2000/svg"
-  xmlns:xlink="http://www.w3.org/1999/xlink">
-
+<svg %{attributes} xmlns="http://www.w3.org/2000/svg">
 %{style}
 %{content}
-
 </svg>

data/lib/victor/version.rb

@@ -1,3 +1,3 @@
 module Victor
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/victor.rb

@@ -1,7 +1,11 @@
 require 'victor/version'
-require 'victor/marshaling'
-require 'victor/svg_base'
-require 'victor/svg'
-require 'victor/attributes'
-require 'victor/css'
-require 'victor/dsl'
+
+module Victor
+  autoload :Attributes, 'victor/attributes'
+  autoload :Component, 'victor/component'
+  autoload :CSS, 'victor/css'
+  autoload :DSL, 'victor/dsl'
+  autoload :Marshaling, 'victor/marshaling'
+  autoload :SVG, 'victor/svg'
+  autoload :SVGBase, 'victor/svg_base'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: victor
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-25 00:00:00.000000000 Z
+date: 2024-08-29 00:00:00.000000000 Z
 dependencies: []
 description: Build SVG images with ease
 email: db@dannyben.com
@@ -19,6 +19,7 @@ files:
 - README.md
 - lib/victor.rb
 - lib/victor/attributes.rb
+- lib/victor/component.rb
 - lib/victor/css.rb
 - lib/victor/dsl.rb
 - lib/victor/marshaling.rb
@@ -34,6 +35,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/DannyBen/victor/issues
   changelog_uri: https://github.com/DannyBen/victor/blob/master/CHANGELOG.md
+  homepage_uri: https://victor.dannyb.co/
   source_code_uri: https://github.com/DannyBen/victor
   rubygems_mfa_required: 'true'
 post_install_message: