- Doc: added section on metadata in fundamentals

- `propset` now accepts units for int and float

docs/cookbook.rst

@@ -156,6 +156,8 @@ Note that *vpype* does not "remember" of such configuration file and the ``--con
    *vpype* is bundled with a `configuration file <https://github.com/abey79/vpype/blob/master/vpype/vpype_config.toml>`_. It is strongly discouraged to edit this file as it will be overwritten each time *vpype* is installed or updated.
 
 
+.. _faq_custom_pen_config:
+
 Creating a custom pen configuration
 ===================================
 

docs/fundamentals.rst

@@ -156,6 +156,49 @@ Likewise, angles are interpreted as degrees by default but alternative units may
   $ vpype rect 0 0 50 100 rotate 0.785398rad
 
 
+.. _fundamentals_metadata:
+
+Metadata
+========
+
+Metadata is data which provides information about other data. In the case of *vpype*, metadata takes the form of *properties* that are either attached to a given layer, or global. Properties are identified by a name and their value can be of arbitrary type (e.g. integer, floating point, color, etc.). There can be any number of global and/or layer properties and it is up to commands (and plug-ins) how they act based (or upon) these properties.
+
+
+System properties
+-----------------
+
+Some properties are referred to as *system properties*. Their name is prefixed with ``vp:`` and they are widely used throughout *vpype*. Currently, the following system properties are defined:
+
+  * ``vp:color``: the color of a layer (layer property)
+  * ``vp:pen_width``: the pen width of a layer (layer property)
+  * ``vp:name``: the name of a layer (layer property)
+  * ``vp:page_size``: the page size (global property)
+
+Many commands acts on these properties. For example, the :ref:`cmd_read` command sets these properties according to the imported SVG file's content. The :ref:`cmd_color`, :ref:`cmd_penwidth`, :ref:`cmd_name`, and :ref:`cmd_pens` commands can set these properties to arbitrary values. In particular, the :ref:`cmd_pens` commands can apply a predefined set of values on multiple layers at once, for example to apply a CMYK color scheme (see :ref:`faq_custom_pen_config` for more information). The page size global property is set by the :ref:`cmd_pagesize` and :ref:`cmd_layout` commands.
+
+
+SVG attributes properties
+-------------------------
+
+The :ref:`cmd_read` command identifies SVG attributes common to all geometries in a given layer and store their value as layer property with a ``svg:`` prefix. For example, if all geometries in a given layer share a ``stroke-dasharray="3 1"`` SVG attribute (either because it is set at the level of the group element, or because it is set in every single geometry elements), a property named ``svg:stroke-dasharray`` with a value of ``"3 1"`` is added to the layer.
+
+These properties are set for informational and extension purposes, and are mostly ignored by *vpype* commands. One exception is the :ref:`cmd_write` command, which can optionally restore these attributes in the exported SVG file.
+
+An example of future extension could be a plug-in which detects the ``svg:stroke-dasharray`` property and turns the corresponding layer's lines into their dashed equivalent. Another example would be a plug-in looking for a ``svg:fill`` property and adding the corresponding hatching patterns to reproduce the filled area.
+
+
+Interacting with properties
+---------------------------
+
+High-level commands such as :ref:`cmd_penwidth` are not the only means of interacting with properties. *vpype* includes a set of low-level commands to inspect and modify global and layer properties:
+
+  * :ref:`cmd_propget`: reads the value of a single global or layer property
+  * :ref:`cmd_proplist`: lists all the global or layer properties
+  * :ref:`cmd_propset`: sets the value of a given global or layer property
+  * :ref:`cmd_propdel`: deletes a given global or layer property
+  * :ref:`cmd_propclear`: deletes all global or layer properties
+
+
 .. _fundamentals_blocks:
 
 Blocks

tests/test_commands.py

@@ -569,6 +569,10 @@ def test_text_command_empty():
     ("cmd", "expected_output"),
     [
         ("propset -l1 prop val", ""),
+        (
+            "random propset -l1 -t int prop 1cm propget -l1 prop",
+            "layer 1 property prop: (int) 37",
+        ),
         ("propset -g prop val", ""),
         ("propget -g prop", "global property prop: n/a"),
         ("line 0 0 1 1 propget -l1 prop", "layer 1 property prop: n/a"),

vpype_cli/metadata.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Any, List, Optional, Tuple, Union
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import click
 
@@ -20,10 +20,10 @@
 )
 
 
-_STR_TO_TYPE = {
+_STR_TO_TYPE: Dict[str, Callable] = {
     "str": str,
-    "int": int,
-    "float": float,
+    "int": lambda x: int(vp.convert_length(x)),
+    "float": vp.convert_length,
     "color": vp.Color,
 }
 
@@ -84,6 +84,9 @@ def propset(
         float: floating-point number
         color: color
 
+    When using the `int` and `float` types, units may be used and the value will be converted
+    to pixels.
+
     When using the `color` type, any SVG-compatible string may be used for VALUE, including
     16-bit RGB (#ff0000), 16-bit RGBA (#ff0000ff), 8-bit variants (#f00 or #f00f), or color
     names (red).
@@ -94,6 +97,11 @@ def propset(
 
             vpype [...] propset --global --type int my_prop 10 [...]
 
+        Set the layer property of type `float` (this is equivalent to using the `penwidth`
+        command:
+
+            vpype [...] propset --layer 1 --type float vp:pen_width 0.5mm [...]
+
         Set a layer property of type `color`:
 
             vpype [...] propset --layer 1 --type color my_prop red [...]
@@ -292,7 +300,8 @@ def penwidth(layer: vp.LineCollection, pen_width: float) -> vp.LineCollection:
 def color(layer: vp.LineCollection, color: str) -> vp.LineCollection:
     """Set the color for one or more layers.
 
-    All CSS ways of specifying color are valid for COLOR.
+    Any SVG-compatible string may be used for VALUE, including 16-bit RGB (#ff0000),
+    16-bit RGBA (#ff0000ff), 8-bit variants (#f00 or #f00f), or color names (red).
 
     By default, this commands sets the color for all layers. Use the `--layer` option to set
     the color of one (or more) specific layer(s).