samples and docs for placeholders

docs/config.rst

@@ -50,6 +50,19 @@ img_dir
 
   For reading image file command (e.g. png and svg), read from this directory instead
 
+img_missing:
+  default: ``:warn``
+
+  Log a warning if an image file is missing. This option is only consulted if the following are true:
+
+    * If the ``file`` specified for an input image (e.g. :doc:`/dsl/png` or :doc:`/dsl/svg`) does not exist,
+    * AND a ``placeholder`` image does not exist
+
+  Other options:
+    * ``error`` - raise a ``RuntimeError`` and halt the entire build.
+    * ``silent`` - do nothing, log nothing, and act as if the ``file`` was ``nil``
+
+
 warn_ellipsize
   default: true
 

docs/dsl/png.rst

@@ -33,13 +33,24 @@ blend
   default: ``:none``
 
   the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators.
-  The possibilties include :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.
+  The possibilties include: :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.
 
 mask
   default: ``nil``
 
   Accepts a color (see :doc:`/colors`). If specified, the image will be used as a mask for the given color/gradient. Transparent pixels are ignored, opaque pixels are the given color. Note: the origin for gradient coordinates is at the given x,y, not at 0,0 as it is most other places.
 
+placeholder
+  default: ``nil``
+
+  if ``file`` does not exist, but the file pointed to by this string does, then draw this image instead.
+
+  No warning is thrown when a placeholder is used.
+
+  If this is non-nil, but the placeholder file does not exist, then a warning is thrown and no image is drawn.
+
+  Examples of how to use placeholders are below.
+
 .. include:: /args/transform.rst
 
 .. include:: /args/range.rst
@@ -47,3 +58,27 @@ mask
 
 Examples
 --------
+
+These examples live here: https://github.com/andymeneely/squib/tree/dev/samples/images
+
+.. literalinclude:: ../../samples/images/_images.rb
+  :linenos:
+
+.. raw:: html
+
+  <img src="../images/_images_00_expected.png" width=600 class="figure">
+
+.. literalinclude:: ../../samples/images/_placeholders.rb
+  :linenos:
+
+First placeholder expected output.
+
+.. raw:: html
+
+  <img src="../images/placeholder_sheet_00_expected.png" width=100 class="figure">
+
+Second placeholder expected output.
+
+.. raw:: html
+
+  <img src="../images/multi_placeholder_sheet_00_expected.png" width=100 class="figure">

docs/dsl/svg.rst

@@ -17,6 +17,8 @@ file
 
   file(s) to read in. As in :doc:`/arrays`, if this a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done for that card.
 
+  By default, if ``file`` is not found, a warning is logged. This behavior can be configured in :doc:`/config`
+
 .. include:: /args/xy.rst
 
 data
@@ -65,6 +67,16 @@ mask
 
     For implementation reasons, your vector image will be rasterized when mask is applied. If you use this with, say, PDF, the images will be embedded as rasters, not vectors.
 
+placeholder
+  default: ``nil``
+
+  if ``file`` does not exist, but the file pointed to by this string does, then draw this image instead.
+
+  No warning is thrown when a placeholder is used.
+
+  If this is non-nil, but the placeholder file does not exist, then a warning is thrown and no image is drawn.
+
+  Examples of how to use placeholders are below.
 
 crop_x
   default: ``0``
@@ -117,3 +129,27 @@ flip_vertical
 
 Examples
 --------
+
+These examples live here: https://github.com/andymeneely/squib/tree/dev/samples/images
+
+.. literalinclude:: ../../samples/images/_images.rb
+  :linenos:
+
+.. raw:: html
+
+  <img src="../images/_images_00_expected.png" width=600 class="figure">
+
+.. literalinclude:: ../../samples/images/_placeholders.rb
+  :linenos:
+
+First placeholder expected output.
+
+.. raw:: html
+
+  <img src="../images/placeholder_sheet_00_expected.png" width=100 class="figure">
+
+Second placeholder expected output.
+
+.. raw:: html
+
+  <img src="../images/multi_placeholder_sheet_00_expected.png" width=100 class="figure">

docs/dsl/text.rst

@@ -278,6 +278,14 @@ blend
   the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators.
   The possibilties include :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.
 
+placeholder
+  default: ``nil``
+
+  if ``file`` does not exist, but the file pointed to by this string does, then draw this image instead.
+
+  No warning is thrown when a placeholder is used.
+
+  If this is non-nil, but the placeholder file does not exist, then a warning is thrown and no image is drawn.
 
 mask
   default: ``nil``

samples/images/.gitignore

@@ -1,8 +1,8 @@
-*.png
+!*_expected.png
 !ball.png
 !grit.png
 !sprites.png
 !with-alpha.png
-!_images_00_expected.png
 !shiny-purse.png
 !angler-fish.png
+*.png

samples/images/_placeholders.rb

@@ -24,6 +24,12 @@ Squib::Deck.new(width: 100, height: 100, cards: 4) do
   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