summaryrefslogtreecommitdiff
path: root/nginx-confgen.pod
diff options
context:
space:
mode:
authorYorhel <git@yorhel.nl>2020-10-22 10:55:48 +0200
committerYorhel <git@yorhel.nl>2020-10-22 10:55:50 +0200
commit17efa52f4942dc3bc7b419eedf2eb31bee17d496 (patch)
treef8a15cfdb815832ef79cbd198c9dd170986f4323 /nginx-confgen.pod
parent9ea4c004f6a09e9d00121bbef99c117ab066c34c (diff)
Rewrite in C + a bunch of visible changes
Ironically, I find C easier to maintain than Haskell, largely because its build environment and APIs are more stable and more familiar to me. Resulting binary is also a *lot* smaller. Not done any performance measurements yet, algorithmically this new implementation has some really bad worst cases, but it wouldn't matter too much if you never hit them. User-visible improvements: - pre_if now supports braces - variables are no longer lexically scoped - error messages come with context And quite likely many regressions. I'll need to write some more tests.
Diffstat (limited to 'nginx-confgen.pod')
-rw-r--r--nginx-confgen.pod26
1 files changed, 12 insertions, 14 deletions
diff --git a/nginx-confgen.pod b/nginx-confgen.pod
index d7f7a25..561930e 100644
--- a/nginx-confgen.pod
+++ b/nginx-confgen.pod
@@ -76,18 +76,15 @@ Relative paths are searched for in the directories given with the C<-I> flag.
=head2 pre_set
Similar to the C<set> directive in nginx, except that variables defined with
-C<pre_set> are resolved during preprocessing. Note that variables defined with
-C<pre_set> are only available in the same scope as they are defined, for
+C<pre_set> are resolved during preprocessing. Variables are set in the order
+that they are encountered in the configuration file, regardless of scoping. For
example:
pre_set $var outer;
location / {
pre_set $var inner;
- # $var is now "inner" within this location block.
}
- # $var is "outer" again after the location block.
-
-(This may change in the future)
+ # $var is "inner" at this point.
=head2 pre_exec
@@ -107,14 +104,13 @@ new command).
=head2 pre_if
Similar to the C<if> directive in nginx, except that this is evaluated during
-preprocessing. Also unlike C<if>, parenthesis around the arguments are not
-supported. Some examples:
+preprocessing. Braces around the condition are optional. Some examples:
pre_if -f $certdir/ocsp.der {
ssl_stapling on;
ssl_stapling_file $certdir/ocsp.der;
}
- pre_if !-f $certdir/ocsp.der {
+ pre_if (!-f $certdir/ocsp.der) {
ssl_stapling off;
}
@@ -153,7 +149,7 @@ The general syntax is as follows:
# contents
}
-The optional C<@remaining_vars> argument will capture any number of variables,
+The optional C<@remaining_vars> argument will capture any number of variables
and can be passed to another directive inside the macro contents. The optional
C<&block_var> allows the macro to be invoked with a block argument, which will
expand to any number of directives. Some examples:
@@ -204,13 +200,17 @@ not necessarily the most useful):
redir;
Similarly, macro arguments will not be available inside C<&block> expansion or
-nested macro expansion.
+nested macro expansion and any variables set inside a macro will not be
+available outside of the macro body.
=head1 BUGS & WARTS
nginx-confgen is a quickly written hack to solve a particular use case, it is
-quite likely to have some weird behavior and bugs.
+quite likely to have some weird behavior and bugs. In particular, processing
+performance may suffer on large configuration files with may macros and/or
+variables. Performance has simply not been a problem for me, but if you do run
+into trouble with your use case, let me know so I can fix it.
Comments and whitespace in the input files are thrown away and ignored. The
generated output is completely reformatted.
@@ -223,8 +223,6 @@ errors or will not survive a round-trip through nginx-confgen.
This applies to all I<*_by_lua_block> directives in the I<ngx_http_lua_module>.
The I<_by_lua> directives that accept a string should work just fine.
-The error messages given by C<nginx-confgen> aren't always helpful.
-
=head1 AUTHOR