[master] 6d15fe035 Split the leoprello-list of VCL variables into a separate vcl-var(7) man page.

Poul-Henning Kamp phk at FreeBSD.org
Tue Feb 16 14:16:06 UTC 2021


commit 6d15fe035cbeb680d95f1289e3cca59a015f58ec
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Tue Feb 16 14:08:17 2021 +0000

    Split the leoprello-list of VCL variables into a separate vcl-var(7) man page.

diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 2b8479243..e7ff6c9e0 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -11,6 +11,7 @@ The VCL language
 	:maxdepth: 1
 
 	VCL - The Varnish Configuration Language <vcl>
+	VCL Variables <vcl-var>
 	VCL backend configuration <vcl-backend>
 	VCL backend health probe <vcl-probe>
 	states.rst
diff --git a/doc/sphinx/reference/vcl-var.rst b/doc/sphinx/reference/vcl-var.rst
new file mode 100644
index 000000000..695d3c1bb
--- /dev/null
+++ b/doc/sphinx/reference/vcl-var.rst
@@ -0,0 +1,93 @@
+.. role:: ref(emphasis)
+
+.. _vcl-var(7):
+
+=============
+VCL-Variables
+=============
+
+------------------
+The complete album
+------------------
+
+:Manual section: 7
+
+DESCRIPTION
+===========
+
+This is a list of all variables in the VCL language.
+
+Variable names take the form ``scope.variable[.index]``, for instance::
+
+	req.url
+	beresp.http.date
+	client.ip
+
+Which operations are possible on each variable is described below,
+often with the shorthand "backend" which covers the ``vcl_backend_* {}``
+subroutines and "client" which covers the rest, except ``vcl_init {}``
+and ``vcl_fini {}``.
+
+.. include:: vcl_var.rst
+
+HTTP response status
+--------------------
+
+A HTTP status code has 3 digits XYZ where X must be between 1 and 5 included.
+Since it is not uncommon to see HTTP clients or servers relying
+on non-standard or even invalid status codes, Varnish can work
+with any status between 100 and 999.
+
+Within VCL code it is even possible to use status codes in the form
+VWXYZ as long as the overall value is lower than 65536, but only
+the XYZ part will be sent to the client, by which time the X must
+also have become non-zero.
+
+The VWXYZ form of status codes can be communicate extra information
+in ``resp.status`` and ``beresp.status`` to ``return(synth(...))`` and
+``return(error(...))``, to indicate which synthetic content to produce::
+
+    sub vcl_recv {
+        if ([...]) {
+            return synth(12404);
+        }
+    }
+
+    sub vcl_synth {
+        if (resp.status == 12404) {
+            [...] 	// this specific 404
+        } else if (resp.status % 1000 == 404) {
+            [...] 	// all other 404's
+        }
+    }
+
+The ``obj.status`` variable will inherit the VWXYZ form, but in a ban
+expresion only the XYZ part will be available. The VWXYZ form is strictly
+limited to VCL execution.
+
+Assigning an HTTP standardized code to ``resp.status`` or ``beresp.status``
+will also set ``resp.reason`` or ``beresp.reason``  to the corresponding
+status message.
+
+SEE ALSO
+========
+     
+* :ref:`varnishd(1)`
+* :ref:`vcl(7)`
+
+HISTORY
+=======
+    
+VCL was developed by Poul-Henning Kamp in cooperation with Verdens
+Gang AS, Redpill Linpro and Varnish Software.  This manual page is
+written by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland,
+Kristian Lyngstøl, Lasse Karstensen and others.
+        
+COPYRIGHT
+=========
+  
+This document is licensed under the same license as Varnish
+itself. See LICENSE for details.
+
+* Copyright (c) 2006 Verdens Gang AS
+* Copyright (c) 2006-2021 Varnish Software AS
diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
index 97fe80466..3c39a0dd9 100644
--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
@@ -40,11 +40,17 @@ The following operators are available in VCL:
   ``=``
     Assignment operator.
 
+  ``+``, ``-``, ``*``, ``/``, ``%``
+    Basic math on numerical values.
+
   ``+=``, ``-=``, ``*=``, ``/=``
     Assign and increment/decrement/multiply/divide operator.
 
     For strings, ``+=`` appends.
 
+  ``(``, ``)``
+    Evaluate separately.
+
   ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``
     Comparisons
 
@@ -67,16 +73,34 @@ implemented with the ``elseif`` statement (``elsif``\ /\ ``elif``\ /\
 
 Note that there are no loops or iterators of any kind in VCL.
 
+Variables
+---------
+
+VCL does most of the work by examining, ``set``'ing and ``unset``'ing
+variables::
 
-Strings, booleans, time, duration, integers and real numbers
-------------------------------------------------------------
+    if (req.url == "/mistyped_url.html") {
+        set req.url = "/correct_url.html";
+        unset req.http.cookie;
+    }
 
-These are the data types in Varnish. You can ``set`` or ``unset`` these.
+There are obvious limitations to what can be done, for instance it
+makes no sense to ``unset req.url;`` - a request must have some kind
+of URL to be valid, and likewise trying to manipulate a backend reponse
+when there is none (yet) makes no sense.
+The VCL compiler will detect such errors.
 
-Example::
+Variables have types.  Most of them a STRINGS, and anything in
+VCL can be turned into a STRING, but some variables have types like
+``DURATION``, ``IP`` etc.
 
-  set req.http.User-Agent = "unknown";
-  unset req.http.Range;
+When setting a such variables, the right hand side of the equal
+sign must have the correct variables type, you cannot assign a
+STRING to a variable of type NUMBER, even if the string is ``"42"``.
+
+Explicit conversion functions are available in :ref:`vmod_std(3)`.
+
+For the complete album of VCL variables see: :ref:`vcl-var(7)`.
 
 
 Strings
@@ -307,11 +331,6 @@ they are concatenated in the order in which they appear in the source.
 The built-in VCL distributed with Varnish will be implicitly concatenated
 when the VCL is compiled.
 
-
-
-.. include:: vcl_var.rst
-
-
 Functions
 ---------
 
diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index fc0d76ef5..5cb180b78 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -1,37 +1,5 @@
 .. _vcl_variables:
 
-VCL Variables
--------------
-
-Variables provide read, write and delete access to almost all aspects
-of the work at hand.
-
-Reading a variable is done simply by using its name in VCL::
-
-    if (client.ip ~ bad_guys) {
-	return (synth(400));
-    }
-
-Writing a variable, where this is possible, is done with a ``set``
-statement::
-
-    set resp.http.never = "Let You Down";
-
-Similarly, deleting a variable, for the few variables where this is
-possible, is done with a ``unset`` statement::
-
-    unset req.http.cookie;
-
-Which operations are possible on each variable is described below,
-often with the shorthand "backend" which covers the ``vcl_backend_* {}``
-subroutines and "client" which covers the rest, except ``vcl_init {}``
-and ``vcl_fini {}``.
-
-When setting a variable, the right hand side of the equal sign
-must have the variables type, you cannot assign a STRING to
-a variable of type NUMBER, even if the string is ``"42"``.
-(Explicit conversion functions can be found in
-:ref:`vmod_std(3)`).
 
 local, server, remote and client
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1403,29 +1371,3 @@ storage.<name>.happy
 	Health status for the named stevedore. Not available in any of the
 	current stevedores.
 
-HTTP response status
---------------------
-
-A status code normally has 3 digits XYZ where X must be between 1 and 5
-included. Since it is not uncommon to see HTTP clients or servers relying
-on non-standard or even invalid status codes Varnish tolerates any status
-between 100 and 999.
-
-With VCL code it is possible to use status codes in the form XXYZZ where the
-overall value is lower than 65536 and the Y digit is between 1 and 9 included.
-Only the YZZ part is sent to the client.
-
-The XXYZZ form of status codes can be set on ``resp.status`` and
-``beresp.status`` or passed via ``return(synth(...))`` and
-``return(error(...))`` transitions.
-
-XX can be therefore be used to pass information around inside VCL, for
-instance ``return(synth(22404))`` from ``vcl_recv{}`` to ``vcl_synth{}``.
-
-The ``obj.status`` variable will inherit the XXYZZ form, but in a ban
-expresion only the YZZ part will be available. The XXYZZ form is strictly
-limited to VCL execution.
-
-Assigning an HTTP standardized code to ``resp.status`` or ``beresp.status``
-will also set ``resp.reason`` or ``beresp.reason``  to the corresponding
-status message.
diff --git a/man/Makefile.am b/man/Makefile.am
index bae551370..b78dc7cfe 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -6,6 +6,7 @@ dist_man_MANS = \
 	vcl.7 \
 	vcl-backend.7 \
 	vcl-probe.7 \
+	vcl-var.7 \
 	vsl.7 \
 	vsl-query.7 \
 	varnishadm.1 \
@@ -56,6 +57,9 @@ vcl-backend.7: $(top_builddir)/doc/sphinx/reference/vcl-backend.rst
 vcl-probe.7: $(top_builddir)/doc/sphinx/reference/vcl-probe.rst
 	$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vcl-probe.rst $@
 
+vcl-var.7: $(top_builddir)/doc/sphinx/reference/vcl-var.rst
+	$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vcl-var.rst $@
+
 vsl.7: $(top_builddir)/doc/sphinx/reference/vsl.rst \
 	$(top_builddir)/doc/sphinx/include/vsl-tags.rst
 	$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vsl.rst $@


More information about the varnish-commit mailing list