starting documenting xywh_shorthands

CHANGELOG.md

@@ -4,7 +4,9 @@ Squib follows [semantic versioning](http://semver.org).
 ## v0.16.0 / Unreleased
 
 Features:
-* Autoscaling text! `ellipsize: :autoscale` will now downscale your `font_size` if the text ellipsized. Thanks @Qgel! (#288, #111). 
+* Special custom unit: cells. A "cell" defaults to 37.5px, or 1/8in, e.g. `x: '1 cell'` means `x: 37.5`. See the docs for details.
+* Shorthands for `x`, `y`, `width`, and `height`! The words `x: 'middle'` and `x: 'middle + 1in'` will get interpreted. See the docs for details.
+* Autoscaling text! `ellipsize: :autoscale` will now downscale your `font_size` if the text ellipsized. Thanks @Qgel! (#288, #111).
 * Option checking!! Completely reworked the way we handle arguments in Squib internally (no external behavioral differences). Now, when you give an option to Squib that is not expected. Since every DSL method "knows" what options it takes, that also means we have EVERY option properly documented (missed a few...) AND we have an automated test that will tell us if we forget to document it.
 
 Compatibility:

docs/index.rst

@@ -15,6 +15,7 @@ Contents:
    layouts
    data
    units
+   shorthands
    colors
    text_feature
    bleed

docs/shorthands.rst

@@ -0,0 +1,29 @@
+XYWH Shorthands
+===============
+
+For the arguments ``x``, ``y``, ``width``, and ``height``, a few convenient shorthands are available.
+
+* ``middle`` for ``x`` and ``width`` refer to the deck's width / 2
+* ``middle`` for ``y`` and ``height`` refer to the deck's height / 2
+* ``deck`` refers to the deck's width for ``x`` and ``width``
+* ``deck`` refers to the deck's height for ``y`` and ``height``
+* You can offset from the middle by using +, -, and /, e.g. ``middle + 1in``
+* You can offset from the width or height using, e.g. ``width - 1in`` or ``height - 2mm``
+* Works with the ``cell`` unit as well, e.g. `middle + 1 cell`. See :doc:`units`.
+
+These are all passed as strings. So you will need to quote them in Ruby, or just plain in your layout YAML.
+
+Note that the following are NOT supported:
+
+* The `+=` operator when using `extends` in a layout file
+
+Samples
+-------
+
+_shorthands.rb
+^^^^^^^^^^^^^^
+
+.. literalinclude:: ../samples/units/_shorthands.rb
+  :language: ruby
+  :linenos:
+

docs/units.rst

@@ -3,6 +3,27 @@ Unit Conversion
 
 By default, Squib thinks in pixels. This decision was made so that we can have pixel-perfect layouts without automatically scaling everything, even though working in units is sometimes easier. We provide some conversion methods, including looking for strings that end in "in", "cm", or "mm" and computing based on the current DPI. The dpi is set on `Squib::Deck.new` (not `config.yml`).
 
+Cells
+-----
+
+A "cell" is a custom unit in Squib that, by default, refers to ``37.5`` pixels. In a 300 DPI situation (i.e. the default), that refers to a 1/8 inch or 3.175mm. This tends to be a standard unit of measure in a lot of templates. By specifying your units in cells, you can increase your rapid prototyping without having to multiply 37.5.
+
+The ``cell_px`` measure is configurable. See :doc:`config`.
+
+To use the cell unit, you need to give Squib a string ending in `cell`, `cells`, or just `c`. For example:
+
+* ``2 cells``
+* ``1cell``
+* ``0.5c``
+
+See more examples below.
+
+Samples
+-------
+
+_units.rb
+^^^^^^^^^
+
 Here are some examples, which `lives here <https://github.com/andymeneely/squib/tree/master/samples/units.rb>`_
 
 .. literalinclude:: ../samples/units/_units.rb
@@ -12,3 +33,14 @@ Here are some examples, which `lives here <https://github.com/andymeneely/squib/
 .. raw:: html
 
   <img src="units/units_00_expected.png" class="figure">
+
+_cells.rb
+^^^^^^^^^
+
+.. literalinclude:: ../samples/units/_cells.rb
+  :language: ruby
+  :linenos:
+
+.. raw:: html
+
+  <img src="units/cells_00_expected.png" class="figure">

lib/squib/args/unit_conversion.rb

@@ -17,7 +17,7 @@ module Squib
         when /deg$/ # ends with "deg"
           arg.rstrip[0..-3].to_f * (Math::PI / 180.0)
         when /c(ell)?[s]?$/ # ends with 'c', 'cell', or 'cells'
-          arg.rstrip[0..-2].to_f * cell_px
+          arg.sub(/c(ell)?[s]?$/, '').to_f * cell_px
         else
           arg
         end

lib/squib/args/xywh_shorthands.rb

@@ -7,7 +7,6 @@ module Squib
       HEIGHT_MINUS_REGEX = /^height\s*\-\s*/
       WIDTH_DIV_REGEX = /^width\s*\/\s*/
       HEIGHT_DIV_REGEX = /^height\s*\/\s*/
-      CELL_REGEX = /^c[ell]?[s]?\s*/
       MIDDLE_PLUS_REGEX = /^middle\s*\+\s*/
       MIDDLE_MINUS_REGEX = /^middle\s*\-\s*/
 
@@ -32,10 +31,12 @@ module Squib
           n = UnitConversion.parse(n)
           deck.height - n
         when WIDTH_DIV_REGEX # e.g. width / 3
-          n = (arg_s.sub WIDTH_DIV_REGEX, '').to_f
+          n = arg_s.sub WIDTH_DIV_REGEX, ''
+          n = UnitConversion.parse(n).to_f
           deck.width / n
         when HEIGHT_DIV_REGEX # e.g. height / 3
-          n = (arg_s.sub HEIGHT_DIV_REGEX, '').to_f
+          n = arg_s.sub HEIGHT_DIV_REGEX, ''
+          n = UnitConversion.parse(n).to_f
           deck.height / n
         when MIDDLE_PLUS_REGEX # e.g. middle + 1.5in
           n = arg_s.sub MIDDLE_PLUS_REGEX, ''

samples/units/_shorthands.rb

@@ -25,10 +25,14 @@ Squib::Deck.new(width: '0.5in', height: '0.25in') do
   rect x: 10, y: 50, width: 10, height: 'height / 3',
        stroke_color: :purple
 
+  # And middle+/-
+
+  rect x: 'middle + 0.1in', y: 'middle - 0.1in',
+       width: '0.1in', height: '0.1in', fill_color: :blue
+
   # Layouts apply this too.
   use_layout file: 'shorthands.yml'
   rect layout: :example
-  # The x and y coordinates can also be "centered", assuming the
 
   # HOWEVER! Shorthands don't combine in an "extends" situation,
   # e.g. this won't work:
@@ -38,10 +42,8 @@ Squib::Deck.new(width: '0.5in', height: '0.25in') do
   #   extends: parent
   #   x: += 0.5in
 
-  # These shorthands are not intended for every xywh parameter or length parameter
-  # e.g. this won't work
-
-
+  # These shorthands are not intended for every xywh parameter or
+  # length parameter, see docs for when they do or do not apply.
 
   save_png prefix: 'shorthand_'
 end