Add a lid built-in expression variable

CHANGELOG.md

@@ -7,6 +7,7 @@ Release date: UNRELEASED
 ### New features and improvements
 
 * Added support for Python 3.11 and dropped support for Python 3.8 (#581)
+* Added the `lid` built-in expression variable for generator and layer processor commands (#605)
 
 ### Bug fixes
 

docs/cookbook.rst

@@ -599,6 +599,20 @@ The above pen configuration can be used by referring to its name, in this case `
 Miscellaneous recipes
 =====================
 
+Batch renaming layers
+---------------------
+
+The :ref:`cmd_name` command can be used to assign a new name to a given layer. It is typically used as follows::
+
+  $ vpype [...] name --layer 3 "Layer 3" [...]
+
+If the :option:`--layer <name --layer>` option is omitted, the provided name is assigned to *all* layers. This behaviour can be useful when combined with the ``lid`` :ref:`expression built-in variable <fundamentals_expr_builtins>`::
+
+  $ vpype random --layer 1 random --layer 3  name "Layer %lid%"  write output.svg
+
+Here, two layers with IDs 1 and 3 are created with some random lines (e.g. to simulate loading a multi-layer file). Then, these layers are renamed with "Layer 1" and "Layer 3", respectively, and the result written to the ``output.svg`` file. The layer names can be verified by opening ``output.svg`` in Inkscape.
+
+
 .. _faq_interactive_pipelines:
 
 Create interactive scripts with ``input()``

docs/fundamentals.rst

@@ -346,6 +346,14 @@ In addition, the following *vpype*-specific symbols are available:
 
   These special objects provide access to the global or current-layer properties. Properties may be accessed by attribute (e.g. ``%prop.vp_name%``) or indexation (e.g. ``%prop['vp_name']%``). The ``gprop`` object provides access to global properties. The ``lprop`` object provides access to the current layer's properties if available (i.e. within  :ref:`generator <fundamentals_generators>` and :ref:`layer processor <fundamentals_layer_processors>` commands). The ``prop`` object looks first for current-layer properties, if any, and then for global properties.
 
+* The ``lid`` variable (in supported commands).
+
+  This variable contains the layer ID of the currently processed layer. It is available only for :ref:`generator <fundamentals_generators>` and :ref:`layer processor <fundamentals_layer_processors>` commands.
+
+  .. caution::
+
+    This variable should not be confused with the ``_lid`` variable set by the :ref:`cmd_forlayer` block processor.
+
 * Units constants (|units_expr|).
 
   These variables may be used to convert values to CSS pixels unit, which *vpype* uses internally. For example, the expression ``%(3+4)*cm%`` evaluates to the pixel equivalent of 7 centimeters (e.g. ~264.6 pixels). (Note that expressions may overwrite these variables, e.g. to use the ``m`` variable for another purpose.)

tests/test_substitution.py

@@ -242,3 +242,10 @@ def test_expression_dict_of_prop(state_factory, state_type):
     state.substitute("%dict(prop)%")
     state.substitute("%dict(gprop)%")
     state.substitute("%dict(lprop)%")
+
+
+def test_expression_lid_builtin():
+    doc = vpype_cli.execute("random -l 1 random -l 3 name 'layer %lid%'")
+    assert {1, 3} == doc.layers.keys()
+    assert doc.layers[1].metadata[vp.METADATA_FIELD_NAME] == "layer 1"
+    assert doc.layers[3].metadata[vp.METADATA_FIELD_NAME] == "layer 3"

vpype_cli/decorators.py

@@ -86,7 +86,8 @@ def layer_processor(state: State) -> None:
                 start = datetime.datetime.now()
                 with state.current():
                     state.current_layer_id = lid
-                    new_args, new_kwargs = state.preprocess_arguments(args, kwargs)
+                    with state.expression_variables({"lid": lid}):
+                        new_args, new_kwargs = state.preprocess_arguments(args, kwargs)
                     logging.info(
                         f"executing layer processor `{f.__name__}` on layer {lid} "
                         f"(kwargs: {new_kwargs})"
@@ -194,7 +195,8 @@ def generator(state: State) -> None:
 
                 start = datetime.datetime.now()
                 state.current_layer_id = target_layer
-                new_args, new_kwargs = state.preprocess_arguments(args, kwargs)
+                with state.expression_variables({"lid": target_layer}):
+                    new_args, new_kwargs = state.preprocess_arguments(args, kwargs)
                 logging.info(
                     f"executing generator `{f.__name__}` to layer {target_layer} "
                     f"(kwargs: {new_kwargs})"