Shorthand
=========

All three susy-sass3 functions — :ref:`span <tools-span>`,
:ref:`gutter <tools-gutter>`, and :ref:`slice <tools-slice>` — draw on the same
shorthand syntax. It lets you describe a span and its grid context in one
readable expression, and only reach for the ``$config`` map when you really need
it.

.. code-block:: scss

  // span 6 of a 12-column grid
  width: span(6 of 12);

  // span 3 columns of an asymmetrical grid, starting at column 2
  width: span(3 at 2 of (1 2 3 5 8));

  // span 3 columns with an extra side gutter, static gutter override
  width: span(3 wide of 6 set-gutters 1em);


-------------------------------------------------------------------------

Overview
--------

The shorthand is split into two halves, separated by the word ``of``:

.. describe:: syntax

  :pattern: ``<span> [<location> <spread>]`` ``of`` ``<columns> <container-spread> <gutters>``

Within each half the order doesn't matter — the flags (``at``, ``of``,
``set-gutters``) tell susy-sass3 how to read each value.


-------------------------------------------------------------------------

.. _shorthand-span:

Span Syntax
-----------

.. describe:: pattern

  :format: ``<width> [<location>] [<spread>]``

The first half describes the span. Only the **width** is required.

.. glossary::

  width
    A unitless count of columns (``span(2)``), an explicit length
    (``span(200px)``), or a column list. On a symmetrical grid a count is all
    you need.

  location
    Where the span sits on the grid, used for asymmetrical grids. Give it with
    the ``at`` flag — ``span(3 at 2)`` — or use the ``first`` / ``last``
    keywords (``at 1 == first``). Since these are functions, they don't place
    the element for you; they only return the width of those specific columns.

  spread
    How many gutters to include, using the :ref:`spread <settings-spread>`
    keywords ``narrow`` (default), ``wide``, or ``wider``.

.. code-block:: scss

  span(2);            // 2 columns, gutters between them only
  span(3 wide);       // 3 columns plus one extra side gutter
  span(3 at 2);       // the 2nd, 3rd, and 4th columns of an asymmetrical grid
  span(last 2);       // the final 2 columns


-------------------------------------------------------------------------

.. _shorthand-context:

Context Syntax
--------------

.. describe:: pattern

  :format: ``of <columns> [<container-spread>] [set-gutters <gutters>]``

Everything after the ``of`` flag describes the grid **context**. All of these
have global defaults, so the context is optional.

.. glossary::

  columns
    The available columns. A single unitless number is treated as a *slice* of
    the parent grid: on a grid of ``susy-repeat(12, 120px)``, ``of 4`` reuses
    the parent's ``120px`` column width. You can be explicit with
    ``of susy-repeat(4, 100px)``. Asymmetrical grids can't be sliced from a bare
    number — use the :ref:`slice <tools-slice>` function, e.g.
    ``of slice(first 3)``.

  container-spread
    The :ref:`container-spread <settings-container-spread>` for this context —
    ``narrow``, ``wide``, or ``wider``.

  set-gutters
    Override the global :ref:`gutters <settings-gutters>` for this one
    calculation, e.g. ``set-gutters 0.5em``.

.. code-block:: scss

  span(2 of 6);                  // slice of 6 columns from the global grid
  span(2 of 12 wide);            // 12-column context, wide container-spread
  span(2 of 12 set-gutters 0.5em); // override the gutter for this call only


-------------------------------------------------------------------------

Config Maps
-----------

Anywhere you'd use shorthand, you can instead pass a settings map as the second
``$config`` argument. This is handy when you keep several grids in variables:

.. code-block:: scss

  $wide-grid: (
    'columns': susy-repeat(12),
    'gutters': 0.5,
  );

  .banner { width: span(8, $wide-grid); }

The map and the shorthand can also be combined — the shorthand overrides matching
keys in the map:

.. code-block:: scss

  .banner { width: span(8 wide, $wide-grid); }