[master] 4a5385858 vmod optional arguments documentation (not new for 6.1)

Nils Goroll nils.goroll at uplex.de
Wed Sep 12 06:58:12 UTC 2018


commit 4a5385858b5d0b904de82c55e53c4e7cf6626da0
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
+declarations:
+
+	* 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