implement placeholder functionality

needs testing but almost there

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)
+      return File.expand_path(arg) if File.exists?(arg)
-      File.expand_path(arg)
+      return File.expand_path(placeholder[i]) if File.exists?(placeholder[i])
+
+      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

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

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
 

lib/squib/dsl/svg.rb

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

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
 

samples/images/_placeholders.rb

@@ -0,0 +1,28 @@
+# 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::Deck.new(width: 100, height: 100, cards: 3) do
+  background color: :white
+
+  files =        %w(angler-fish.png does-not-exist.png does-not-exist.png)
+  placeholders = %w(grit.png        does-not-exist.png grit.png)
+  png file: files, placeholder: placeholders
+  save_sheet columns: 1, prefix: 'multi_placeholder_sheet_'
+end