[master] c09032032 Make the rst anchors we generated for vmods be the vcl-syntax name: Ie:
Poul-Henning Kamp
phk at FreeBSD.org
Thu Jan 31 08:51:08 UTC 2019
commit c09032032700f91fcf06e3018d206cbb730d1772
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Thu Jan 31 08:49:07 2019 +0000
Make the rst anchors we generated for vmods be the vcl-syntax name:
Ie:
vmod.cache_req_body
instead of
func_cache_req_body
diff --git a/doc/sphinx/reference/directors.rst b/doc/sphinx/reference/directors.rst
index b359133ae..8758b4535 100644
--- a/doc/sphinx/reference/directors.rst
+++ b/doc/sphinx/reference/directors.rst
@@ -155,7 +155,7 @@ Health Probes
=============
It is possible in a VCL program to query the health of a director (see
-:ref:`func_healthy`). A director can report its health if it implements the
+:ref:`vmod_std.healthy`). A director can report its health if it implements the
``healthy`` function, it is otherwise always considered healthy.
Unless you are making a dynamic backend, you need to take care of the
diff --git a/doc/sphinx/whats-new/upgrading-5.1.rst b/doc/sphinx/whats-new/upgrading-5.1.rst
index f350c58ff..62a1726c4 100644
--- a/doc/sphinx/whats-new/upgrading-5.1.rst
+++ b/doc/sphinx/whats-new/upgrading-5.1.rst
@@ -197,7 +197,7 @@ vcl_recv
* Added ``req.storage``, which tells Varnish which storage backend to
use if you choose to save the request body (see
- :ref:`func_cache_req_body`).
+ :ref:`vmod_std.cache_req_body`).
* ``return(vcl(LABEL))`` may not be called after a restart. It can
only be called from the active VCL instance.
@@ -232,9 +232,9 @@ nuke limit is used in all cases.
vmod_std
~~~~~~~~
-* Added ``std.getenv()``, see :ref:`func_getenv`.
+* Added ``std.getenv()``, see :ref:`vmod_std.getenv`.
-* Added ``std.late_100_continue()``, see :ref:`func_late_100_continue`.
+* Added ``std.late_100_continue()``, see :ref:`vmod_std.late_100_continue`.
Other changes
=============
diff --git a/doc/sphinx/whats-new/upgrading-5.2.rst b/doc/sphinx/whats-new/upgrading-5.2.rst
index fa137c35f..8edd71b6b 100644
--- a/doc/sphinx/whats-new/upgrading-5.2.rst
+++ b/doc/sphinx/whats-new/upgrading-5.2.rst
@@ -121,7 +121,7 @@ situation.
vmod_std
~~~~~~~~
-Added :ref:`func_file_exists`.
+Added :ref:`vmod_std.file_exists`.
New VMODs in the standard distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/sphinx/whats-new/upgrading-6.0.rst b/doc/sphinx/whats-new/upgrading-6.0.rst
index 510993143..7a0227995 100644
--- a/doc/sphinx/whats-new/upgrading-6.0.rst
+++ b/doc/sphinx/whats-new/upgrading-6.0.rst
@@ -461,9 +461,9 @@ backend, or set a value for the Host header in VCL.
VMOD std
--------
-:ref:`std.port(IP) <func_port>` always returns 0 when applied to a
+:ref:`std.port(IP) <vmod_std.port>` always returns 0 when applied to a
``*.ip`` variable whose value is set to ``0.0.0.0`` because the
-listener is UDS. :ref:`std.set_ip_tos(INT) <func_set_ip_tos>` is
+listener is UDS. :ref:`std.set_ip_tos(INT) <vmod_std.set_ip_tos>` is
silently ignored when the listener is UDS.
The ``shard`` director
@@ -519,7 +519,7 @@ except for ``req.restarts`` and ``req.xid``, which change by design.
If you need to reset the client request headers to their original
state (before changes in VCL), call
-:ref:`std.rollback(req) <func_rollback>`.
+:ref:`std.rollback(req) <vmod_std.rollback>`.
``return(restart)`` can now be called from ``vcl_recv{}``.
diff --git a/doc/sphinx/whats-new/upgrading-6.1.rst b/doc/sphinx/whats-new/upgrading-6.1.rst
index a082b3cc5..7a5499af4 100644
--- a/doc/sphinx/whats-new/upgrading-6.1.rst
+++ b/doc/sphinx/whats-new/upgrading-6.1.rst
@@ -138,7 +138,7 @@ Other changes to VCL
VMODs
=====
-Added the :ref:`func_fnmatch` function to :ref:`vmod_std(3)`, which
+Added the :ref:`vmod_std.fnmatch` function to :ref:`vmod_std(3)`, which
you can use for shell-style wildcard matching. Wildcard patterns may
be a good fit for matching URLs, to match against a pattern like
``/foo/*/bar/*``. The patterns can be built at runtime, if you need to
diff --git a/lib/libvcc/vmodtool.py b/lib/libvcc/vmodtool.py
index b1e4cd590..6ad42f421 100755
--- a/lib/libvcc/vmodtool.py
+++ b/lib/libvcc/vmodtool.py
@@ -398,13 +398,13 @@ class ProtoType(object):
s += t.replace("@", " ") + ")"
return s
- def rsthead(self, fo):
+ def rst_proto(self, fo, sep='-'):
s = self.vcl_proto(False)
if len(s) < 60:
- write_rst_hdr(fo, s, '-')
+ write_rst_hdr(fo, s, sep)
else:
s = self.vcl_proto(True)
- write_rst_hdr(fo, s, '-')
+ write_rst_hdr(fo, s, sep)
fo.write("\n::\n\n" + self.vcl_proto(False, pfx=" ") + "\n")
def cname(self, pfx=False):
@@ -508,15 +508,15 @@ class Stanza(object):
warn=False)
def rstfile(self, fo, man):
- if self.rstlbl:
- fo.write("\n.. _" + self.rstlbl + ":\n")
self.rsthead(fo, man)
self.rstdoc(fo, man)
def rsthead(self, fo, unused_man):
''' Emit the systematic part of the documentation '''
+ if self.rstlbl:
+ fo.write('\n.. _' + self.rstlbl + ':\n')
if self.proto:
- self.proto.rsthead(fo)
+ self.proto.rst_proto(fo)
fo.write("\n")
def rstdoc(self, fo, unused_man):
@@ -527,7 +527,7 @@ class Stanza(object):
if man and self.proto:
fo.write(self.proto.vcl_proto(True, pfx=" ") + '\n \n')
elif self.proto and self.rstlbl:
- fo.write(' :ref:`%s`\n \n' % self.rstlbl)
+ fo.write(' :ref:`%s`\n \n' % self.rstlbl)
def cstuff(self, unused_fo, unused_where):
return
@@ -556,10 +556,7 @@ class ModuleStanza(Stanza):
else:
print("\nNOTICE: Please put $Module description in quotes.\n")
self.vcc.moddesc = " ".join(self.toks[3:])
- self.rstlbl = "vmod_%s(%s)" % (
- self.vcc.modname,
- self.vcc.mansection
- )
+ self.rstlbl = "vmod_%s(%d)" % (self.vcc.modname, 3)
self.vcc.contents.append(self)
def rsthead(self, fo, man):
@@ -570,6 +567,8 @@ class ModuleStanza(Stanza):
fo.write("\n")
fo.write(":Manual section: " + self.vcc.mansection + "\n")
else:
+ if self.rstlbl:
+ fo.write('\n.. _' + self.rstlbl + ':\n')
write_rst_hdr(fo,
self.vcc.sympfx + self.vcc.modname +
' - ' + self.vcc.moddesc,
@@ -669,7 +668,7 @@ class FunctionStanza(Stanza):
def parse(self):
self.proto = ProtoType(self)
- self.rstlbl = "func_" + self.proto.name
+ self.rstlbl = 'vmod_%s.%s' % (self.vcc.modname, self.proto.name)
self.vcc.contents.append(self)
def cstuff(self, fo, where):
@@ -702,12 +701,14 @@ class ObjectStanza(Stanza):
self.fini.argstruct = False
self.fini.args = []
- self.rstlbl = "obj_" + self.proto.name
+ self.rstlbl = 'vmod_%s.%s' % (self.vcc.modname, self.proto.name)
self.vcc.contents.append(self)
self.methods = []
def rsthead(self, fo, man):
- self.proto.rsthead(fo)
+ if self.rstlbl:
+ fo.write('\n.. _' + self.rstlbl + ':\n')
+ self.proto.rst_proto(fo)
fo.write("\n" + "\n".join(self.doc) + "\n")
for i in self.methods:
i.rstfile(fo, man)
@@ -725,7 +726,7 @@ class ObjectStanza(Stanza):
fo.write(' :ref:`%s`\n \n' % self.rstlbl)
for i in self.methods:
if i.proto and i.rstlbl:
- fo.write(' :ref:`%s`\n \n' % i.rstlbl)
+ fo.write(' :ref:`%s`\n \n' % i.rstlbl)
def cstuff(self, fo, w):
sn = self.vcc.sympfx + self.vcc.modname + "_" + self.proto.name
@@ -787,7 +788,7 @@ class MethodStanza(Stanza):
err("$Method %s: Method names need to start with . (dot)"
% self.proto.bname, warn=False)
self.proto.obj = "x" + self.pfx
- self.rstlbl = "func_" + self.proto.name
+ self.rstlbl = 'vmod_%s.%s' % ( self.vcc.modname, self.proto.name)
p.methods.append(self)
def cstruct(self, fo, define):
diff --git a/lib/libvmod_blob/vmod.vcc b/lib/libvmod_blob/vmod.vcc
index ab545480e..302293f76 100644
--- a/lib/libvmod_blob/vmod.vcc
+++ b/lib/libvmod_blob/vmod.vcc
@@ -55,7 +55,7 @@ Examples::
}
ENCODING SCHEMES
-================
+----------------
Binary-to-text encoding schemes are specified by ENUMs in the VMOD's
constructor, methods and functions. Decodings convert a (possibly
@@ -91,7 +91,7 @@ case of a string, use the ``toupper`` or ``tolower`` functions from
:ref:`vmod_std(3)`.
IDENTITY
---------
+~~~~~~~~
The simplest encoding converts between the BLOB and STRING data types,
leaving the contents byte-identical.
@@ -120,7 +120,7 @@ be written as::
The ``case`` ENUM MUST be set to ``DEFAULT`` for ``IDENTITY`` encodings.
BASE64*
--------
+~~~~~~~
The base64 encoding schemes use 4 characters to encode 3 bytes. There
are no newlines or maximal line lengths -- whitespace is not
@@ -143,7 +143,7 @@ The ``case`` ENUM MUST be set to ``DEFAULT`` for for all of the
``BASE64*`` encodings.
HEX
----
+~~~
The ``HEX`` encoding scheme converts hex strings into blobs and vice
versa. For encodings, you may use the ``case`` ENUM to specify upper-
@@ -164,7 +164,7 @@ byte. For example::
encoded=resp.http.First + resp.http.Second));
URL
----
+~~~
The ``URL`` decoding replaces any ``%<2-hex-digits>`` substrings with
the binary value of the hexadecimal number after the % sign.
@@ -197,6 +197,7 @@ Example::
# convert string to blob
blob.decode(encoded="foo");
+
$Function STRING encode(ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD,
HEX, URL} encoding="IDENTITY",
ENUM {LOWER, UPPER, DEFAULT} case="DEFAULT", BLOB blob)
diff --git a/lib/libvmod_directors/vmod.vcc b/lib/libvmod_directors/vmod.vcc
index a98352983..71ec5be1b 100644
--- a/lib/libvmod_directors/vmod.vcc
+++ b/lib/libvmod_directors/vmod.vcc
@@ -349,13 +349,13 @@ Set the default rampup duration. See `rampup` parameter of
$Method VOID .associate(BLOB param=0)
-Associate a default `obj_shard_param`_ object or clear an association.
+Associate a default `vmod_directors.shard_param`_ object or clear an association.
The value of the `param` argument must be a call to the
-`func_shard_param.use`_ method. No argument clears the association.
+`vmod_directors.shard_param.use`_ method. No argument clears the association.
The association can be changed per backend request using the `param`
-argument of `func_shard.backend`_.
+argument of `vmod_directors.shard.backend`_.
$Method BOOL .add_backend(PRIV_TASK, BACKEND backend,
[STRING ident], [DURATION rampup])
@@ -371,7 +371,7 @@ backend name.
`rampup`: Optionally specify a specific rampup time for this
backend. Otherwise, the per-director rampup time is used (see
-:ref:`func_shard.set_rampup`).
+:ref:`vmod_directors.shard.set_rampup`).
NOTE: Backend changes need to be finalized with `shard.reconfigure()`
and are only supported on one shard director at a time.
@@ -536,14 +536,14 @@ is _not_ the order given when backends are added.
* `param`
Use or associate a parameter set. The value of the `param` argument
- must be a call to the `func_shard_param.use`_ method.
+ must be a call to the `vmod_directors.shard_param.use`_ method.
- default: as set by `func_shard.associate`_ or unset.
+ default: as set by `vmod_directors.shard.associate`_ or unset.
* for ``resolve=NOW`` take parameter defaults from the
- `obj_shard_param`_ parameter set
+ `vmod_directors.shard_param`_ parameter set
- * for ``resolve=LAZY`` associate the `obj_shard_param`_ parameter
+ * for ``resolve=LAZY`` associate the `vmod_directors.shard_param`_ parameter
set for this backend request
Implementation notes for use of parameter sets with
@@ -557,7 +557,7 @@ is _not_ the order given when backends are added.
and are kept even if the parameter set given by the `param`
argument is subsequently changed within the same backend request.
- * Each call to `func_shard.backend`_ overrides any previous call.
+ * Each call to `vmod_directors.shard.backend`_ overrides any previous call.
$Method VOID .debug(INT)
@@ -567,7 +567,7 @@ $Object shard_param()
Create a shard parameter set.
-A parameter set allows for re-use of `func_shard.backend`_ arguments
+A parameter set allows for re-use of `vmod_directors.shard.backend`_ arguments
across many shard director instances and simplifies advanced use cases
(e.g. shard director with custom parameters layered below other
directors).
@@ -586,7 +586,7 @@ Parameter sets can not be used in client context.
$Method VOID .clear()
Reset the parameter set to default values as documented for
-`func_shard.backend`_.
+`vmod_directors.shard.backend`_.
* in ``vcl_init{}``, resets the parameter set default for this VCL
* in backend context, resets the parameter set for this backend
@@ -604,7 +604,7 @@ $Method VOID .set(
[ ENUM {CHOSEN, IGNORE, ALL} healthy ])
Change the given parameters of a parameter set as documented for
-`func_shard.backend`_.
+`vmod_directors.shard.backend`_.
* in ``vcl_init{}``, changes the parameter set default for this VCL
@@ -618,39 +618,39 @@ $Method STRING .get_by()
Get a string representation of the `by` enum argument which denotes
how a shard director using this parameter object would derive the
-shard key. See `func_shard.backend`_.
+shard key. See `vmod_directors.shard.backend`_.
$Method INT .get_key()
Get the key which a shard director using this parameter object would
-use. See `func_shard.backend`_.
+use. See `vmod_directors.shard.backend`_.
$Method INT .get_alt()
Get the `alt` parameter which a shard director using this parameter
-object would use. See `func_shard.backend`_.
+object would use. See `vmod_directors.shard.backend`_.
$Method REAL .get_warmup()
Get the `warmup` parameter which a shard director using this parameter
-object would use. See `func_shard.backend`_.
+object would use. See `vmod_directors.shard.backend`_.
$Method BOOL .get_rampup()
Get the `rampup` parameter which a shard director using this parameter
-object would use. See `func_shard.backend`_.
+object would use. See `vmod_directors.shard.backend`_.
$Method STRING .get_healthy()
Get a string representation of the `healthy` enum argument which a
shard director using this parameter object would use. See
-`func_shard.backend`_.
+`vmod_directors.shard.backend`_.
$Method BLOB .use()
This method may only be used in backend context.
-For use with the `param` argument of `func_shard.backend`_ to associate
+For use with the `param` argument of `vmod_directors.shard.backend`_ to associate
this shard parameter set with a shard director.
ACKNOWLEDGEMENTS
diff --git a/lib/libvmod_std/vmod.vcc b/lib/libvmod_std/vmod.vcc
index afab2bed3..cf919d250 100644
--- a/lib/libvmod_std/vmod.vcc
+++ b/lib/libvmod_std/vmod.vcc
@@ -214,7 +214,7 @@ $Function TIME real2time(REAL r, TIME fallback)
Description
Rounds the real *r* to the nearest integer (see
- `func_real2integer`_) and returns the corresponding time when
+ `vmod_std.real2integer`_) and returns the corresponding time when
interpreted as a unix epoch. If conversion fails, *fallback*
will be returned.
Example
More information about the varnish-commit
mailing list