[6.0] 62f291a16 vmod optional arguments documentation (not new for 6.1)

Dridi Boukelmoune dridi.boukelmoune at gmail.com
Wed Oct 31 13:08:17 UTC 2018

commit 62f291a16f9fe718be04f72e538e9146e4081395
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Wed Sep 12 08:53:04 2018 +0200

    vmod optional arguments documentation (not new for 6.1)

diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 3b63f563f..b9c0fcfc8 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -140,6 +140,44 @@ different to user specified values.
 `Note` that default values have to be given in the native C-type
 syntax, see below. As a special case, ``NULL`` has to be given as ``0``.
+Optional arguments
+The vmod.vcc declaration also allows for optional arguments in square
+brackets like so::
+	$Function VOID opt(PRIV_TASK, INT four = 4, [ STRING opt])
+With any optional argument present, the C function prototype looks
+completely different:
+	* Only the ``VRT_CTX`` and object pointer arguments (only for
+	  methods) remain positional
+	* All other arguments get passed in a struct as the last
+	  argument of the C function.
+The argument struct is simple, vmod authors should check the
+`vmodtool`-generated ``vcc_if.c`` file for the function and struct
+	* for each optional argument, a ``valid_``\ `argument` member
+	  is used to signal the presence of the respective optional
+	  argument.
+	  ``valid_`` argstruct members should only be used as truth
+	  values, irrespective of their actual data type.
+	* named arguments are passed in argument struct members by the
+	  same name and with the same data type.
+	* unnamed (positional) arguments are passed as ``arg``\ `n`
+	  with `n` starting at 1 and incrementing with the argument's
+	  position.
+	  Note that in particular also ``PRIV_*`` arguments (which are
+	  unnamed by definition) are passed as ``arg``\ `n`
 .. _ref-vmod-vcl-c-types:
 VCL and C data types

More information about the varnish-commit mailing list