Skip to content
Snippets Groups Projects
Verified Commit 0bb772b8 authored by Daniel Hornung's avatar Daniel Hornung
Browse files

DOC: Macros

parent 177cd0d5
No related branches found
No related tags found
2 merge requests!178FIX: #96 Better error output for crawl.py script.,!171sav/spss converter
Macros Macros
------ ------
Introduction
============
Macros highly facilitate the writing of complex :doc:`CFoods<cfood>`. Consider the following common Macros highly facilitate the writing of complex :doc:`CFoods<cfood>`. Consider the following common
example: example:
...@@ -83,16 +86,46 @@ The expanded version of `ExperimentalData` will look like: ...@@ -83,16 +86,46 @@ The expanded version of `ExperimentalData` will look like:
This :ref:`example<example_files_2>` can also be found in the macro unit tests (see :func:`unittests.test_macros.test_documentation_example_2`). This :ref:`example<example_files_2>` can also be found in the macro unit tests (see :func:`unittests.test_macros.test_documentation_example_2`).
Complex Example
===============
The following, more complex example, demonstrates the use Mixing macros and plain definitions
of macro variable substitutions that generate crawler variable substitutions: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also mix macros and plain definitions. Whenever a name cannot be resolved to a macro, a
plain yaml node definition is used as a fallback:
.. code:: yaml
---
metadata:
macros:
- !defmacro
name: MarkdownFile
# ... Definition here ...
---
ExperimentalData:
type: Directory
match: ExperimentalData
subtree: !macro
MarkdownFile:
- name: README
filename: ^README.md$
OtherContent: # There is no macro named "OtherContent", so this is parsed as normal content.
type: SimpleFile
match: .*txt
records:
# ... Normal content ...
- `$$$nodename` will lead to a macro variable substitution of variable `$nodename` during macro expansion. Complex example
- `$$` will be turned into `$` ===============
- So in the crawler cfood, the string will appear as `$value` if variable `nodename` would be set to `value` when using the macro.
Let's try something more complex: what happens to multiple ``$``? This example demonstrates the use
of `macro` variable substitutions to generate `crawler` variable substitutions:
- ``$$`` will be converted into ``$``.
- ``$$$nodename`` will retain a single ``$`` and substitute ``$nodename`` during macro expansion.
- So in the cfood, if ``nodename: value``, the string ``$$$nodename`` will be converted to
``$value``.
.. _example_1: .. _example_1:
.. code-block:: yaml .. code-block:: yaml
...@@ -118,7 +151,8 @@ of macro variable substitutions that generate crawler variable substitutions: ...@@ -118,7 +151,8 @@ of macro variable substitutions that generate crawler variable substitutions:
Simulation: Simulation:
$recordtype: +$File $recordtype: +$File
The expanded version of :ref:`example<example_1>` can be seen in :ref:`example<example_1_expanded>`. The expanded version of the :ref:`example above<example_1>` (with ``nodename: Dataset``) can be seen
:ref:`here<example_1_expanded>`:
.. _example_1_expanded: .. _example_1_expanded:
...@@ -141,11 +175,11 @@ The expanded version of :ref:`example<example_1>` can be seen in :ref:`example<e ...@@ -141,11 +175,11 @@ The expanded version of :ref:`example<example_1>` can be seen in :ref:`example<e
type: SimpleFile type: SimpleFile
type: Directory type: Directory
This :ref:`example<example_1>` can also be found in the macro unit tests (see :func:`unittests.test_macros.test_documentation_example_1`). This example can also be found in the macro unit tests (see
:func:`unittests.test_macros.test_documentation_example_1`).
Using Macros Multiple Times Using macros multiple times
=========================== ===========================
To use the same macro multiple times in the same yaml node, lists can be used: To use the same macro multiple times in the same yaml node, lists can be used:
...@@ -198,11 +232,11 @@ use the same top level key. Because later versions would overwrite previous ...@@ -198,11 +232,11 @@ use the same top level key. Because later versions would overwrite previous
ones. Here we used ``$macro_name`` to prevent that. ones. Here we used ``$macro_name`` to prevent that.
Limitation Limitations
========== ===========
Currently it is not possible to use the same macro twice in the same yaml node, but in different Currently it is not possible to use the same macro twice in the same yaml node, if it occurs in
positions. Consider: different positions. Consider:
.. _example_multiple_limitation: .. _example_multiple_limitation:
.. code-block:: yaml .. code-block:: yaml
...@@ -227,14 +261,13 @@ positions. Consider: ...@@ -227,14 +261,13 @@ positions. Consider:
Other_node: Other_node:
type: test type: test
test_twice: # This is NOT possible as each test_twice: # This is NOT possible as each key
# dictionary element can only appear once in a yaml node. # can only appear once in a yaml node.
- macro_name: twice # <- This is the second one, with different arguments - macro_name: twice # <- This is the second one, with different arguments
a: 5 a: 5
- {} # <- This is the third one, just using default arguments - {} # <- This is the third one, just using default arguments
However, this should not be a real limitation, as the crawler is designed in a way, This should not be a real limitation however, as the order of nodes does not matter for the crawler.
that the order of the nodes in the same level should not matter.
Using macros within macro definitions Using macros within macro definitions
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment