squib 0.17.2 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ee8653b18081af7af0fefe9713a87c44ce979437dd198ed251d241bb9e7c32b
-  data.tar.gz: aaf0af1bf44f085376e240f438bdc375a09d3f6c74cc288204879801243302c0
+  metadata.gz: 8e5921a89334684b7770be1b6d85ef150fd02f5c1b305ae795c0b349ac3e8a6d
+  data.tar.gz: bd29c5c8b101957a1ade535d14a128137185c002195d832d349e51c0aff9fcf4
 SHA512:
-  metadata.gz: c3b2348477dc9915e86cc08786e1ed11c07dacfcb0946f19635c5a725bc9ca1cf87e58bf9536d874f29529648962ff25c197785b6479b025e0cb06c1a00cab4d
-  data.tar.gz: 334a87f006492a9891aaf0d6ff520923dd99e95fc3847eea4e1784f60a2fe5cab3f9d2fc74ca28ae9f69667d3b4071c142bb823976676d697ad7103e194abcc6
+  metadata.gz: 021b8f98bab301f65e300523447fb4fc172cc12df0d7436da200e716e6dfd87d843b11ac3e07bd8496319eaa62803c59ad1a5ed88d9dc830e8858f99c4288366
+  data.tar.gz: 8c3d7a1b44ac551ce24716ab6da853e1bfcacac55c5ce8ba13a847990c863860cb5bc186832812d8b14aacc774ee96bf3d41057cd65ee966cbad1dda130681e7

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Report something that seems wrong
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. My code looks like this...
+2. When I run it like this...
+3. I see this error...
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+We love screenshots!
+  * Windows: `Print Screen` key and then `ctrl+v` directly into GitHub issues here.
+  * Shift + Command + 3, then `command+v` directly into GitHub issues here.
+
+**Environment**
+ - OS: (e.g. Windows 11)
+ - Ruby version (e.g. 2.7, 3.0)
+
+**Additional context**
+Add any other context about the problem here.
+
+**Check the following:**
+
+- [ ] I have updated Squib to the latest version.
+- [ ] I have checked the Squib issues backlog for something similar
+- [ ] I have attempted to make a minimal script demonstrating my problem
+- [ ] I have reviewed the [Squib Docs](https://squib.readthedocs.io/) and there's still a problem

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen. Make an example of what you want the syntax to look like.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
+
+ - [ ] I might be interested in implementing this myself

data/.github/ISSUE_TEMPLATE/help-wanted.md

@@ -0,0 +1,13 @@
+---
+name: Help Wanted - USE GITHUB DISCUSSIONS INSTEAD
+about: Need help doing something in Squib? We prefer you use the (new!) Discussions tab
+title: Help Wanted - USE GITHUB DISCUSSIONS INSTEAD
+labels: help wanted
+assignees: andymeneely
+---
+
+Need help doing something in Squib? We prefer you use the (new!) Discussions tab
+
+We prefer that GitHub issues be used for features or bugs.
+
+

data/{RELEASE TODO.md → .github/ISSUE_TEMPLATE/release-todo.md}

@@ -1,4 +1,12 @@
-Be sure to remember to do the following for releases. (Copy into a GitHub issue)
+---
+name: Release TODO list
+about: Use this checklist when we release
+title: Release v0.XYZ
+labels: release
+assignees: andymeneely
+---
+
+Be sure to remember to do the following for releases.
 
  - [ ] CHANGELOG is written for all new changes
  - [ ] README is updated

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+### Motivation
+
+*Replace this line with why you are making this change.*
+
+### Have you...
+
+  - [ ] Written a sample in `_samples`?
+  - [ ] Updated documentation in the `docs/` folder?
+  - [ ] Linked this PR to an issue?
+  - [ ] Written any automated tests?
+  - [ ] Refactored your code to be maintainable?
+
+The above things are not required, but appreciated.

data/.github/workflows/tests.yml

@@ -1,6 +1,6 @@
 name: Squib Unit Tests
 
-on: [push]
+on: [push, pull_request]
 
 jobs:
   test:
@@ -8,9 +8,9 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu, macos]
-        ruby: [2.5, 2.6, 2.7, 3.0, head]
+        ruby: [2.7, 3.0, head]
     runs-on: ${{ matrix.os }}-latest
-    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug'  || (matrix.ruby == '3.0' && matrix.os == 'macos')}}
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || (matrix.ruby == '3.0' && matrix.os == 'macos')}}
     steps:
     - uses: actions/checkout@v2
     - uses: ruby/setup-ruby@v1

data/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "restructuredtext.confPath": "${workspaceFolder}\\docs",
+  "restructuredtext.linter.disabled": true
+}

data/CHANGELOG.md

@@ -1,10 +1,25 @@
 # Squib CHANGELOG
 Squib follows [semantic versioning](http://semver.org).
 
+## v0.18.0 / Unreleased
+
+Features:
+* Placeholders! Missing images to `svg` and `png` can be replaced by a `placeholder` (#339)
+* New config option: `img_missing`. When an image is missing, warn or error to the console (#339)
+* `save_sheet` learned how to `rotate` individual images! (#301)
+
+Compatibility:
+* Because of the features above, the new default behavior is to warn instead of errors on a missing file
+* Ruby 2.7 is officially our minimum Ruby, since Ruby 2.6 will EOL in about six months from now
+
 ## v0.17.1 / 2021-09-07
 
 Bugs:
 * Fix frozen string error on `Squib.xlsx` import when stripping newlines is enabled
+* `save_sheet` works with `rtl` and `trim` altogether properly now.
+
+Chores:
+* Added autoloading for various slow-loading libraries, speeding up initial `require`
 
 ## v0.17.1 / 2021-08-11
 

data/README.md

@@ -31,7 +31,7 @@ Wanna see more? Check out the website: http://andymeneely.github.io/squib/
 
 ## Installation
 
-Squib requires Ruby 2.5 or later.
+Squib requires Ruby 2.7 or later.
 
 Install it yourself with:
 

data/bin/squib

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
 require 'squib'
+require 'squib/commands/cli'
 
 Squib::CLI.new.run

data/lib/squib/args/arg_loader.rb

@@ -126,4 +126,13 @@ module Squib::Args::ArgLoader
     self
   end
 
+  # Return the deck's configuration
+  # This keeps the @deck local to this mixin instead of forcing args classes
+  # to "know" that @deck works.
+  #
+  # It also makes unit testing easier. Sue me.
+  def deck_conf
+    @deck.conf
+  end
+
 end

data/lib/squib/args/input_file.rb

@@ -13,7 +13,10 @@ module Squib::Args
     end
 
     def self.parameters
-      { file: nil }
+      {
+        file: nil,
+        placeholder: nil
+      }
     end
 
     def self.expanding_parameters
@@ -24,10 +27,29 @@ module Squib::Args
       [] # none of them
     end
 
-    def validate_file(arg, _i)
+    def validate_file(arg, i)
       return nil if arg.nil?
-      raise "File #{File.expand_path(arg)} does not exist!" unless File.exists?(arg)
-      File.expand_path(arg)
+      return File.expand_path(arg) if File.exists?(arg)
+      return File.expand_path(placeholder[i]) if File.exists?(placeholder[i].to_s)
+
+      case deck_conf.img_missing.to_sym
+      when :error
+        raise "File #{File.expand_path(arg)} does not exist!"
+      when :warn
+        Squib.logger.warn "File #{File.expand_path(arg)} does not exist!"
+      end
+      return nil # the silent option - as if nil in the first place
+    end
+
+    def validate_placeholder(arg, _i)
+      # What if they specify placeholder, but it doesn't exist?
+      # ...always warn... that's probably a mistake they made
+      unless arg.nil? || File.exists?(arg)
+        msg = "Image placeholder #{File.expand_path(arg)} does not exist!"
+        Squib.logger.warn msg
+        return nil
+      end
+      return arg
     end
   end
 end

data/lib/squib/conf.rb

@@ -23,6 +23,7 @@ module Squib
       'dir'           => '_output',
       'hint'          => :none,
       'img_dir'       => '.',
+      'img_missing'   => :warn,
       'progress_bars' => false,
       'prefix'        => 'card_',
       'ldquote'       => "\u201C", # UTF8 chars
@@ -74,6 +75,10 @@ module Squib
       @config_hash['img_dir']
     end
 
+    def img_missing
+      @config_hash['img_missing'].to_sym
+    end
+
     def text_hint
       @config_hash['text_hint']
     end

data/lib/squib/dsl/png.rb

@@ -31,6 +31,7 @@ module Squib
           crop_corner_radius crop_corner_x_radius crop_corner_y_radius
           flip_horizontal flip_vertical
           range layout
+          placeholder
          )
       end
 

data/lib/squib/dsl/save_sheet.rb

@@ -30,7 +30,7 @@ module Squib
           range sprue
           columns rows rtl
           dir prefix count_format suffix
-          margin gap trim trim_radius
+          margin gap trim trim_radius rotate
          )
       end
 

data/lib/squib/dsl/svg.rb

@@ -33,6 +33,7 @@ module Squib
           flip_horizontal flip_vertical angle
           id force_id data
           range layout
+          placeholder
          )
       end
 

data/lib/squib/dsl/text_embed.rb

@@ -23,6 +23,7 @@ module Squib
         id force_id data
         flip_horizontal flip_vertical
         alpha angle blend mask
+        placeholder
       )
     end
 

data/lib/squib/graphics/save_doc.rb

@@ -4,13 +4,13 @@ module Squib
     # :nodoc:
     # @api private
     def render_sheet(range, batch, sheet)
-      sheet_width = (sheet.columns * (@width + 2 * sheet.gap - 2 * sheet.trim)) + (2 * sheet.margin)
-      sheet_height = (sheet.rows * (@height + 2 * sheet.gap - 2 * sheet.trim)) + (2 * sheet.margin)
+      rotate = batch.rotate.any? true # either rotate all or none
+      w,h,sheet_width,sheet_height = compute_dimensions(sheet, rotate)
       cc = Cairo::Context.new(Cairo::ImageSurface.new(sheet_width, sheet_height))
       num_this_sheet = 0
       sheet_num = 0
       y = sheet.margin
-      x = sheet.rtl ? (sheet_width - sheet.margin - sheet.gap - @width) : sheet.margin
+      x = sheet.rtl ? rtl_start_x(sheet_width, sheet, w) : sheet.margin
       @progress_bar.start("Saving PNG sheet to #{batch.summary}", @cards.size + 1) do |bar|
         range.each do |i|
           if num_this_sheet >= (sheet.columns * sheet.rows) # new sheet
@@ -20,17 +20,19 @@ module Squib
             num_this_sheet = 0
             sheet_num += 1
             y = sheet.margin
-            x = sheet.rtl ? (sheet_width - sheet.margin - sheet.gap - @width) : sheet.margin
+            x = sheet.rtl ? rtl_start_x(sheet_width, sheet, w) : sheet.margin
             cc = Cairo::Context.new(Cairo::ImageSurface.new(sheet_width, sheet_height))
           end
-          surface = trim(@cards[i].cairo_surface, sheet.trim, @width, @height)
+          surface = preprocess(@cards[i].cairo_surface,
+                                sheet.trim, w, h,
+                                rotate, batch.angle[i])
           cc.set_source(surface, x, y)
           cc.paint
           num_this_sheet += 1
-          x += (surface.width + sheet.gap) * (sheet.rtl ? -1 : 1)
+          x += (w + sheet.gap) * (sheet.rtl ? -1 : 1)
           if num_this_sheet % sheet.columns == 0 # new row
-            x = sheet.rtl ? (sheet_width - sheet.margin - sheet.gap - @width) : sheet.margin
-            y += surface.height + sheet.gap
+            x = sheet.rtl ? rtl_start_x(sheet_width, sheet, w) : sheet.margin
+            y += h + sheet.gap
           end
           bar.increment
         end
@@ -38,18 +40,32 @@ module Squib
       end
     end
 
-    # Return a new Cairo::ImageSurface that is trimmed from the original
-    #
-    # @param surface The surface to trim
-    # @param trim The number of pixels around the edge to trim
-    # @param width The width of the surface prior to the trim
-    # @param height The height of the surface prior to the trim
+    def compute_dimensions(sheet, rotate)
+      w,h = rotate ? [@height,@width] : [@width,@height]
+      w -= 2 * sheet.trim
+      h -= 2 * sheet.trim
+      sheet_width = (sheet.columns * (w + 2 * sheet.gap)) + (2 * sheet.margin)
+      sheet_height = (sheet.rows * (h + 2 * sheet.gap)) + (2 * sheet.margin)
+      return [w, h, sheet_width, sheet_height]
+    end
+
+    def rtl_start_x(sheet_width, sheet, w)
+      return sheet_width - sheet.margin - sheet.gap - w
+    end
+
+    # Return a new Cairo::ImageSurface that is trimmed and rotated
+    # from the original
     # :nodoc:
     # @api private
-    def trim(surface, trim, width, height)
-      if trim > 0
-        tmp = Cairo::ImageSurface.new(width - 2 * trim, height - 2 * trim)
+    def preprocess(surface, trim, w, h, rotate, angle)
+      if trim > 0 || rotate
+        tmp = Cairo::ImageSurface.new(w, h)
         cc = Cairo::Context.new(tmp)
+        if rotate
+          cc.translate w * 0.5, h * 0.5
+          cc.rotate angle
+          cc.translate h * -0.5, w * -0.5
+        end
         cc.set_source(surface, -1 * trim, -1 * trim)
         cc.paint
         surface = tmp

data/lib/squib/import/xlsx_importer.rb

@@ -1,4 +1,4 @@
-require 'roo'
+autoload :Roo, 'roo'
 require_relative 'quantity_exploder'
 
 module Squib::Import

data/lib/squib/version.rb

@@ -6,6 +6,6 @@ module Squib
   # Most of the time this is in the alpha of the next release.
   # e.g. v0.0.5a is on its way to becoming v0.0.5
   #
-  VERSION = '0.17.2'
+  VERSION = '0.18.0'
 end
 

data/lib/squib.rb

@@ -1,7 +1,7 @@
+autoload :Cairo, 'cairo'
+autoload :Pango, 'pango'
+autoload :Rsvg,  'rsvg2'
 require 'logger'
-require 'cairo'
-require 'pango'
-require 'rsvg2'
 require 'rainbow/refinement'
 require_relative 'squib/version'
 require_relative 'squib/commands/cli'
@@ -9,7 +9,6 @@ require_relative 'squib/deck'
 require_relative 'squib/card'
 require_relative 'squib/system_fonts'
 
-
 module Squib
   using Rainbow # we can colorize strings now!
 

data/samples/images/_placeholders.rb

@@ -0,0 +1,49 @@
+# require 'squib'
+require_relative '../../lib/squib'
+
+# By default Squib will simply warn you if an image is missing
+# Instead, you can give it a `placeholder`
+Squib.configure img_missing: :silent  # no warnings, no errors, no placeholder
+# Squib.configure img_missing: :warn  # default
+# Squib.configure img_missing: :error # pre Squib v0.18 behavior... blech
+
+Squib::Deck.new(width: 100, height: 100, cards: 3) do
+  background color: :white
+
+  files = %w(angler-fish.png does-not-exist.png) # last one is nil
+  png file: files, placeholder: 'grit.png'
+  save_sheet columns: 1, prefix: 'placeholder_sheet_'
+end
+
+# Placeholders can be per-image too.
+# What if a placeholder is specified but doesn't exist? It'll always warn.
+Squib.configure img_missing: :warn # default
+Squib::Deck.new(width: 100, height: 100, cards: 4) do
+  background color: :white
+
+  files =        %w(angler-fish.png does-not-exist.png does-not-exist.png does-not-exist.png)
+  placeholders = %w(grit.png        does-not-exist.png grit.png                             )
+  png file: files, placeholder: placeholders
+
+  # text embeds can have placeholders too
+  text(str: 'A', color: :red) do |embed|
+    embed.png key: 'A', file: files, placeholder: placeholders, width: 30, height: 30
+  end
+
+  save_sheet columns: 1, prefix: 'multi_placeholder_sheet_'
+end
+
+# Do errors work?
+# If you REALLY want the old, pre-Squib v0.18 functionality
+# ...you can still have it
+# This is really more of a regression test than example.
+Squib.configure img_missing: :error
+Squib::Deck.new(width: 100, height: 100, cards: 1) do
+  begin
+    png file: 'does-not-exist.png' # no placeholder... should error!
+    raise Exception.new 'Runtime Error should have been thrown!'
+  rescue RuntimeError => e
+    # a runtime error should have happened here. So nothing happens. Good.
+    Squib.logger.error 'Yay! An error we expected was thrown.'
+  end
+end

data/samples/saves/_saves.rb

@@ -1,7 +1,7 @@
-require 'squib'
+# require 'squib'
+require_relative '../../lib/squib'
 
 # This sample demonstrates how to use the various save methods
-
 Squib::Deck.new(width: 825, height: 1125, cards: 16) do
   background color: :gray
   rect x: 38, y: 38, width: 750, height: 1050,
@@ -60,3 +60,16 @@ Squib::Deck.new(width: 100, height: 100, cards: 3) do
   # Buggy behavior was to revert to 1 row and not respect the rows arg.
   save_sheet prefix: 'save_sheet_bug332_', rows: 2, columns: 4
 end
+
+# Allow rotating
+Squib::Deck.new(width: 100, height: 50, cards: 8) do
+  background color: :white
+  rect x: 10, y: 10, width: 80, height: 30
+  rect x: 5, y: 5, width: 90, height: 40, stroke_width: 5, stroke_color: :blue
+  text y: 2, str: 0..7, font: 'Open Sans Bold 8', align: :center, width: 100
+  save_sheet prefix: 'save_sheet_unrotated_', rows: 2, columns: 3
+  save_sheet prefix: 'save_sheet_custom_rotate_', rows: 2, columns: 3, rotate: [:clockwise, :counterclockwise] * 4
+  save_sheet prefix: 'save_sheet_rotated_', rows: 2, columns: 3, rotate: true
+  save_sheet prefix: 'save_sheet_rotated_trimmed_', rows: 2, columns: 3, rotate: true, trim: 5
+  save_sheet prefix: 'save_sheet_rotated_trimmed_rtl_', rows: 2, columns: 3, rotate: true, trim: 5, rtl: true
+end

data/squib.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.specification_version = 2 if spec.respond_to? :specification_version=
   spec.required_rubygems_version = Gem::Requirement.new('>= 0') if spec.respond_to? :required_rubygems_version=
   spec.rubygems_version = '2.2.2'
-  spec.required_ruby_version = '>= 2.5.0'
+  spec.required_ruby_version = '>= 2.7.0'
 
   spec.name          = 'squib'
   spec.version       = Squib::VERSION

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: squib
 version: !ruby/object:Gem::Version
-  version: 0.17.2
+  version: 0.18.0
 platform: ruby
 authors:
 - Andy Meneely
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-07 00:00:00.000000000 Z
+date: 2021-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cairo
@@ -341,6 +341,7 @@ extra_rdoc_files:
 - samples/images/_cairo_access.rb
 - samples/images/_images.rb
 - samples/images/_more_load_images.rb
+- samples/images/_placeholders.rb
 - samples/intro/01_hello.rb
 - samples/intro/02_options.rb
 - samples/intro/03_layout.rb
@@ -377,8 +378,14 @@ extra_rdoc_files:
 - samples/units/_shorthands.rb
 - samples/units/_units.rb
 files:
+- ".github/ISSUE_TEMPLATE/bug_report.md"
+- ".github/ISSUE_TEMPLATE/feature_request.md"
+- ".github/ISSUE_TEMPLATE/help-wanted.md"
+- ".github/ISSUE_TEMPLATE/release-todo.md"
+- ".github/PULL_REQUEST_TEMPLATE.md"
 - ".github/workflows/tests.yml"
 - ".gitignore"
+- ".vscode/settings.json"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - Dockerfile
@@ -386,7 +393,6 @@ files:
 - Guardfile
 - LICENSE.txt
 - README.md
-- RELEASE TODO.md
 - Rakefile
 - bin/squib
 - lib/squib.rb
@@ -539,6 +545,7 @@ files:
 - samples/images/_cairo_access.rb
 - samples/images/_images.rb
 - samples/images/_more_load_images.rb
+- samples/images/_placeholders.rb
 - samples/intro/01_hello.rb
 - samples/intro/02_options.rb
 - samples/intro/03_layout.rb
@@ -588,7 +595,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -617,6 +624,7 @@ test_files:
 - samples/images/_cairo_access.rb
 - samples/images/_images.rb
 - samples/images/_more_load_images.rb
+- samples/images/_placeholders.rb
 - samples/intro/01_hello.rb
 - samples/intro/02_options.rb
 - samples/intro/03_layout.rb