.. _FunctionPointer: https://www.geeksforgeeks.org/function-pointer-in-c/

*******************************************************************************
PlantUML Stdlib Under The Hood 2
*******************************************************************************

.. _StdlibProposalCode: http://www.plantuml.com/plantuml/uml/j911YiCm34NtFiLV36ILP3ymCCnD54U93OhjiUI6thvk2hr1XK0WwIt--rMZQkqGDv08jDHeh8W914_6UwvtdBd9YeNxsajRURtklKMcqbbiKHXRhh10zkRSyFFnScxmbSaO_D_YZOIJ8M-8FYU5Xdmc1AwCO5RqUvxtQA4jay_7JASABVgSu_K_zWXZ4KgNa9SBVFsH-O07g_Ioyo1JW75ytwlm1l0TpcL9Mw052hJ0q6BC15xEC2q71XYCzwunCT5lP-BcMJpBVtv_aOHD4dvOQV_hd_vssEo7d3Orvi4vs_KTpXfaQstqMhCFvFgDnIIwMDgJD7eidlhZk_MNEs1PMDnt_qAv-ygQTPQU3NN6NOTJZzpQxmqtr0WdUeA23HKHlJvK16aV2IHugerhaIER7bu9MD8Nxrgw8Px1xUxOT7kfYFUMIAo6g-_g9m-vIoi0NghUDUZDB3YNmqLIGIde3r2vAoqtlsuDD_ciBAkIPVxYxTKuzVEYdV67OxSjQ4qFECASKTR0H0mu8pf8jDHjD0tfnZkBYdGupsYiaSwUOsTC61O4lLCjSEGiuvV2ivjzJzJl-eLfpcpimoLtUGdfQmf2rH-CmG2FlZ1BZzE-4Y2YmXGs_EvLbJaj5mNvfHyuLr9L6nq8b2t3SrokemahbplRt-iB2x7kN9NRoNPoVbFv0SYvCzqfYhANvg-Xq3nnbcajeuV4qvjchkf1rGmOxiUn6_1aiPzgVdTjj_Jo4ZsBDW5DwDo2C0lsSjFfRcy7vjPMw9tXzuWeC0v__oUr_ndHJzfzqn-SJ7C-_cJrDF-eJ_Zyr_ov_qzawhYCVpGM67nKNu4eEDUTp1wQA_bvROi9VxHCOw_nFPvk7u0kneKGECNc-hb3an7bUIF46YTF21OMDntlh08_nDsN5MJeAfj7SagE3Tln3POXC6PFZ_8Z2gszj_bn_pq4hj21CjPsKfodIyQCd-hhSBirM_OtQfcqlGuCioJf20BQQnH5zQhXNyMITJLGCrJ0o-h6jCn2H3GTzTWkmxkArdFLGjPFblElO6Sl1-OS_hz6zGdEnphv_7VOVxz_ZEkvuj3Mc3zU7LuFqKOqJi7tZRccSodCNycunHk4PZKljdrZNgd5FSolDC550QRA-pSScaz8rEQKNxhZhW63qoYa0fSTPSTmiM601Lu9aUjd5Cz2bfp2A8gavd1SqUwGWbmrNx7AhRUQKVnAP-j1Av4OjQYSWa8ZJzQuBbej_HBWS5Ea7QTKKHh0ypAm1VRSZjHGz4SbZK5Hk6QdHOQzCx_f8Zg2DrH77XPYSBKb-QGomwkRDO8Et2iQvt7lzZWiLd8wPmr5VDqP-Hju9Mw0uufvDQViKYc_mAsc1A97aQ3A2dShlDmcb9ibbJ6zwvfdx_LdpVYF_m1ZlxwVgAqZh9OGvpj-4yitaIB0sBoefoGxK47xgF0terHuVQKhaai6S7xEVc-m7--3zKBlB5AGgitDdC7EgMaBiUg3eCaGcsz1TrnztYJY84uqCyZ6AC9bfi9cp4LELIrV3K5_d9S5B0yAqkE-aDf1sdizg5SAFkGOvanvDqVzv9PDO8seVnVqN7M9srmgd51fQS2MH0lLjynoQVtkObz_64PyW_VK7wia4QJ8BPWC_xe-c_3OQte5wyDGoB8UCx8PCszP2X_BFwgl_jwsRI3wlpx5HSZWU7NiMDg08N2CPKs15LXI83ys3CDWqEBP9YAH7ab5qpxzZfGYEv7Lf5jTe4KAYzJnlVlnU29_dTrXwXGTlF3XepxxuVhyziFrpIk-Rptu3O7ZGaY4CIWDcT88jRev9aepgxJ_OXlBKp6d5HULkShrjeN_DXS8zr8LuFuV0vCS4YO1cH5f-KWZiG0bqMCkSfiJNq5x4vY1Z4bRUeCrqon3YmHCZCmuv8BU3XeUhcJF0ZwWh2ZPNEKMIhHa_mlQdW73IhZnaLmykWd2r6vmYbGIwtZmt2Pg6qKjexXj50Uzuq__5npaygzSMO9PQvKWT_auVCPsT7XPLbC3E6IfO8P-EPf4YxKLIfw58KsaR8vfzMWnMKcLgcLPZKt2KZmRqrD2ixa-2pNoi1y46XFBv3B56XVeBmmcaseqdGOLQZ1nw_HflNmwQHpwjiAUJaRUOXgCHXCZ_i7JSJJzOykFFoSZDpqTZO80dZWV1WSeUHCyoPjn3ipBmApO6ZTYs5-6epsaUAaHfN_beZWBfUBeSkx7NqV2uGtDM_pR4jGNgKEyXphCqnotof3GB7VZEYwQ6l-mnxeqFAyi3xJh0nQDXPlRyzltRu5OKb2BxTxh-wTX6VgBoN-hJgldXDNLX38L6ikiI6R4E0xxBSjejsdKbdwhshjNnX-lLdGIzfkaNFn-TNwvlwpqxCerUeK6fB9GA7qFNBYkcPR0J4k_S0n6LPyd4BAoT7PhrB1GQQeA8PUG2ed1mI4l9Pn1M6E4Ro1iSCBW6o4Vr3tE6XqSEVi1R6MCnYohw-B76n6veHUiUzYeZX9NyKPTn54NSzH57JMWSHTet0KQTu76OV_5WywxgmlufCEEGuJR5S8SMMxBwkOkwgFBGcbWi1GFABrU1b2WFxqaAoQNsBpBMA8LvEk2QMxWQ9vRhmok2kcd-iI1m-LmU-rFvxTlVvwHLA7AWk-0lEg02wqog4fhbN-8cgSOq2R3uH30oT0xO4w12Efp4w6e1Gdg57A3kcSW8LGmbfKkAFJY7u1pqUJhjT9LbCtvodWVvmYCapC4o-OY5ROa-lhCLWVWmJWkM9xQUeVvJhMxfJVH7dtMiyhB6s8NtIFN4w97beQZ_wpbxWxCtGDzN7i-8NHlG7-H_r-HFfAzBkARkyjtr-_FhtpKN-np7Bi6tzqmcaltPqd4XhcTaw07TmQrtoPcZObOb52uPc5NMFhx20W9IdCaEANXGJ2GB4CEJEVB3AKrmTPs2ETEg3CAOzRqwrQZfjznlsDLzB5LJXzphGePTYsFDmNvZjhhbfv3Hhgg7UjllTZCDzI6B-YlxK1_DrxyN1HPMPi7mLDvXQOkQ-t7otpTorzsTm0dm-zfi1RodWRLrXj0VE8S2tv4oVCi_HS0
.. _MigrationNotes: https://plantuml.com/preprocessing#ajlk3nchu0zkka0ybjng
.. _DefaultArgumentValue: https://plantuml.com/preprocessing#ae1b47605326b65f







Step-by-step Towards A Standard Macro
===============================================================================


.. uml:: ProcedureBuildup.puml
    :align: center
    :caption: *each output is numbered to match the procedure e.g. 51 is output for ffoo51()* 


.. literalinclude:: ProcedureBuildup.puml
    :linenos: 


Close But... 
===============================================================================

We can use the DefaultArgumentValue_ to avoid having to specify a parameter value when we call our procedure.
BUT this only works if the default parameters are at the end i.e. it is all based on the order of the procedure parameters.

*In other words, the user has to know/care about the order of parameters.*

See :ref:`Standard Library - What We Have And What We Want`.


To specify color blue I need to do

```$ffoo6("myaliasbatch2", "mydescription", "mylabel", "mytechnology", 2, blue)```

What I want to do 
```$ffoo6($color=blue)```
or 
```$ffoo6($scale=2)```


Procedure Keyword Arguments
===============================================================================


To enable the StdLib standardisation, I suggested the *keyword arguments* and Arnaud produced a release to play with next day - and this became part of an official release:


.. uml:: pre-processing.puml
    :align: center
    :caption: *each output is numbered to match the procedure e.g. 51 is output for ffoo51()* 


.. literalinclude:: pre-processing.puml
    :linenos: 



Extensibility
===============================================================================

So now we have a way for the user to specify any or all of the sprite parameters.

But what happens if we want to add new parameters in the future?

Option 1: Reserve Parameters
-------------------------------------------------------------------------------
One option is to reserve parameters in the procedure definition:


.. code-block:: 

    !unquoted procedure $SpriteDecorator($MySprite, $alias, $description="", $label="", $technology="", $scale=1, $colour="red", $res1="", $res2="", $res3="", $res4="")

and used a function/procedure to map the new parameter feature to a reserved word.

We're not smart enough to predict the future, and we don't want to impose limits, so we won't be doing this. 

Option 2: Dynamic Invocation
-------------------------------------------------------------------------------

See :ref:`stdlibreqs-label` for requirements for stdlib.

Let's define 3 SpriteDecorator Procedures that change the sprite parameters per :ref:`stdlibreqs-label`, where each procedure adds more parameters than the previous one.

::

    !unquoted procedure $SpriteDecorator($MySprite, $alias, $description="", $label="", $technology="", $scale=1, $colour="red")
    !unquoted procedure $SpriteDecorator2($MySprite, $alias, $description="", $label="", $technology="", $scale=1, $colour="green", $shape="node")
    !unquoted procedure $SpriteDecorator3($MySprite, $alias, $description="", $label="", $technology="", $scale=1, $colour="blue", $shape="cloud", $textsize="18")

When we define the procedure for the user to call e.g. $BATCH_DYN, we specify which SpriteDecorator to be used via $dynN dynamic invocation.

If at some point later, a new SpriteDecorator becomes available with same parameters but different processing, or with new parameters, then we can change this dynN to the new procedure.

User code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Parameters

#. can use ordered list of parameters up to the one they want to specify.
#. can use named arguments to specify only the parameter(s) they care about.

Existing code does not need to know or care that the SpriteDecorator has changed.

New code can use the new decorator functionality if desired.

Play with StdlibProposalCode_ online.

.. uml:: dynamic1.0.puml
    :align: center
    :caption: *decorators separated from sprite* 


.. literalinclude:: dynamic1.0.puml
    :linenos: 
    :emphasize-lines: 37, 50, 63, 102, 106,110, 83, 86, 89