Language Elements
=================

Below is a list of values and an explanation of any expression that can be applied to properties in CartoCSS.

Color
-----

CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, hsluv, and hsluva.
It also supports the predefined HTML colors names, like `yellow` and `blue`. ::

    #line {
      line-color: #ff0;
      line-color: #ffff00;
      line-color: rgb(255, 255, 0);
      line-color: rgba(255, 255, 0, 1);
      line-color: hsl(100, 50%, 50%);
      line-color: hsla(100, 50%, 50%, 1);
      line-color: hsluv(100, 50%, 50%); // same values yield different color than HSL
      line-color: hsluva(100, 50%, 50%, 1);
      line-color: yellow;
    }

Especially of note is the support for HSL and HSLuv, which can be easier to reason about than RGB.
CartoCSS also includes several color operation functions `borrowed from LessCSS <http://lesscss.org/functions/#color-operations>`_::

    // lighten and darken colors
    lighten(#ace, 10%);
    darken(#ace, 10%);

    // saturate and desaturate
    saturate(#550000, 10%);
    desaturate(#00ff00, 10%);

    // increase or decrease the opacity of a color
    fadein(#fafafa, 10%);
    fadeout(#fefefe, 14%);

    // spin rotates a color around the color wheel by degrees
    spin(#ff00ff, 10);

    // mix generates a color in between two other colors.
    mix(#fff, #000, 50%);

    // get color components
    hue(#ff00ff);
    saturation(#ff00ff);
    lightness(#ff00ff);
    alpha(hsla(100, 50%, 50%, 0.5));

These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors.
All the above mentioned functions also come in a *functionp*-variant (e.g. ``lightenp``), which force a given color into HSLuv color space.

Float
-----

Float is a fancy way of saying 'number'. In CartoCSS, you specify *just a number* - unlike CSS, there are no units,
but everything is specified in pixels. ::

    #line {
      line-width: 2;
    }

It's also possible to do simple math with number values::

    #line {
      line-width: 4 / 2; // division
      line-width: 4 + 2; // addition
      line-width: 4 - 2; // subtraction
      line-width: 4 * 2; // multiplication
      line-width: 4 % 2; // modulus
    }

URI
---

URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of ``url('place.png')``
notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended.
URIs can be paths to places on your computer, or on the internet. ::

    #markers {
      marker-file: url('marker.png');
    }

String
------

A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything,
though pay attention to the cases of ``text-name`` and ``shield-name`` - they actually will refer to features,
which you refer to by putting them in brackets, as seen in the example below. ::

    #labels {
      text-name: "[MY_FIELD]";
    }

Boolean
-------

Boolean means yes or no, so it accepts the values ``true`` or ``false``. ::

    #markers {
      marker-allow-overlap: true;
    }

Expressions
-----------

Expressions are statements that can include fields, numbers, and other types in a really flexible way.
You have run into expressions before, in the realm of 'fields', where you'd specify ``"[FIELD]"``,
but expressions allow you to drop the quotes and also do quick addition, division, multiplication,
and concatenation from within CartoCSS syntax. ::

    #buildings {
      building-height: [HEIGHT_FIELD] * 10;
    }

Numbers
-------

Numbers are comma-separated lists of one or more number in a specific order.
They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. ::

    #disputedboundary {
      line-dasharray: 1, 4, 2;
    }

Percentages
-----------

In CartoCSS, the percentage symbol, ``%`` universally means ``value/100``.
It's meant to be used with ratio-related properties, like opacity rules.

.. attention:: You should not use percentages as widths, heights, or other properties - unlike CSS,
   percentages are not relative to cascaded classes or page size, they're, as stated,
   simply the value divided by one hundred.

In an example::

    #world {
      // this syntax
      polygon-opacity: 50%;

      // is equivalent to
      polygon-opacity: 0.5;
    }

Functions
---------

Functions are comma-separated lists of one or more functions. For instance, transforms use the ``functions`` type
to allow for transforms within CartoCSS, which are optionally chainable. ::

    #point {
      point-transform: scale(2, 2);
    }

Mapnik Render-Time Variables
----------------------------

Mapnik >= 3.0.0 supports variables of the form ``@var``. These can be used from CartoCSS by specifying them as strings. For example::

    #layer {
      line-width: '@zoom';
    }

For this to have any effect you have to pass the variables to Mapnik at render time in a hashmap of the form ``variable_name:variable_value``.

Resetting properties
--------------------

You can reset properties by specifying them with the keyword ``none``. They will then be removed from the symbolizer thus using their default value
or not using them at all. This does not work or makes sense for all properties like e.g. not for ``text-face-name``. For an overview over properties
where this works or makes sense see `this list <https://github.com/mapbox/carto/blob/master/test/rendering-mss/issue_214.mss>`_.