Options.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 1996-2022 The Squid Software Foundation and contributors
3 *
4 * Squid software is distributed under GPLv2+ license and includes
5 * contributions from numerous individuals and organizations.
6 * Please see the COPYING and CONTRIBUTORS files for details.
7 */
8
9#ifndef SQUID_ACL_OPTIONS_H
10#define SQUID_ACL_OPTIONS_H
11
12#include "acl/forward.h"
13#include "sbuf/forward.h"
14
15#include <iosfwd>
16#include <vector>
17
18// After line continuation is handled by the preprocessor, an ACL object
19// configuration can be visualized as a sequence of same-name "acl ..." lines:
20//
21// L1: acl exampleA typeT parameter1 -i parameter2 parameter3
22// L2: acl exampleA typeT parameter4
23// L3: acl exampleA typeT -i -n parameter5 +i parameter6
24// L4: acl exampleA typeT -n parameter7
25//
26// There are two kinds of ACL options (a.k.a. flags):
27//
28// * Global (e.g., "-n"): Applies to all parameters regardless of where the
29// option was discovered/parsed (e.g., "-n" on L3 affects parameter2 on L1).
30// Declared by ACL class kids (or equivalent) via ACL::options().
31//
32// * Line (e.g., "-i"): Applies to the yet unparsed ACL parameters of the
33// current "acl ..." line (e.g., "-i" on L1 has no effect on parameter4 on L2)
34// Declared by ACLData class kids (or equivalent) via lineOptions().
35//
36// Here is the option:explicitly-affected-parameters map for the above exampleA:
37// "-n": parameter1-7 (i.e. all parameters)
38// "-i": parameter2, parameter3; parameter5
39// "+i": parameter6
40//
41// The option name spelling determines the option kind and effect.
42// Both option kinds use the same general option configuration syntax:
43// option = name [ '=' value ]
44// where "name" is option-specific spelling that looks like -x, +x, or --long
45//
46// On each "acl ..." line, global options can only appear before the first
47// parameter, while line options can go before any parameter.
48//
49// XXX: The fact that global options affect previous (and subsequent) same-name
50// "acl name ..." lines surprises and confuses those who comprehend ACLs in
51// terms of configuration lines (which Squid effectively merges together).
52
53namespace Acl {
54
56class Option
57{
58public:
60 explicit Option(const char *nameThatEnables, const char *nameThatDisables = nullptr, ValueExpectation vex = valueNone);
61 virtual ~Option() {}
62
65 virtual bool configured() const = 0;
66
68 virtual void enable() const = 0;
69
71 virtual void configureWith(const SBuf &rawValue) const = 0;
72
74 virtual void disable() const = 0;
75
77 virtual void unconfigure() const = 0;
78
80 virtual bool disabled() const = 0;
81
82 virtual bool valued() const = 0;
83
85 virtual void print(std::ostream &os) const = 0;
86
88 const char * const onName = nullptr;
89
92 const char * const offName = nullptr;
93
95};
96
98template <class Value>
100{
101public:
102 typedef Value value_type;
103
104 // TODO: Some callers use .value without checking whether the option is
105 // enabled(), accessing the (default-initialized or customized) default
106 // value that way. This trick will stop working if we add valued options
107 // that can be disabled (e.g., --with-foo=x --without-foo). To support such
108 // options, store the default value separately and provide value accessor.
109
111 explicit OptionValue(const Value &aValue): value(aValue) {}
112
114 bool enabled() const { return configured && !disabled; }
115 explicit operator bool() const { return enabled(); }
116
118 void reset() { *this = OptionValue<Value>(); }
119
120 Value value;
121 bool configured = false;
122 /* flags for configured options */
123 bool disabled = false;
124 bool valued = false;
125};
126
128template <class Recipient>
129class TypedOption: public Option
130{
131public:
132 //typedef typename Recipient::value_type value_type;
133 explicit TypedOption(const char *nameThatEnables, const char *nameThatDisables = nullptr, ValueExpectation vex = valueNone):
134 Option(nameThatEnables, nameThatDisables, vex) {}
135
137 void linkWith(Recipient *recipient) const
138 {
139 assert(recipient);
140 recipient_ = recipient;
141 }
142
143 /* Option API */
144
145 virtual bool configured() const override { return recipient_ && recipient_->configured; }
146 virtual bool disabled() const override { return recipient_ && recipient_->disabled && /* paranoid: */ offName; }
147 virtual bool valued() const override { return recipient_ && recipient_->valued; }
148
149 virtual void unconfigure() const override {
151 recipient_->reset();
152 }
153
154 virtual void enable() const override
155 {
157 recipient_->configured = true;
158 recipient_->disabled = false;
159 recipient_->valued = false;
160 // leave recipient_->value unchanged
161 }
162
163 virtual void configureWith(const SBuf &rawValue) const override
164 {
166 recipient_->configured = true;
167 recipient_->disabled = false;
168 recipient_->valued = true;
169 import(rawValue);
170 }
171
172 virtual void disable() const override
173 {
175 recipient_->configured = true;
176 recipient_->disabled = true;
177 recipient_->valued = false;
178 // leave recipient_->value unchanged
179 }
180
181 virtual void print(std::ostream &os) const override
182 {
183 if (configured()) {
184 os << ' ' << (disabled() ? offName : onName);
185 if (valued())
186 os << '=' << recipient_->value;
187 }
188 // else do not report the implicit default
189 }
190
191private:
192 void import(const SBuf &rawValue) const { recipient_->value = rawValue; }
193
194 // The "mutable" specifier demarcates set-once Option kind/behavior from the
195 // ever-changing recipient of the actual admin-configured option value.
196 mutable Recipient *recipient_ = nullptr;
197};
198
199/* two typical option kinds: --foo and --bar=text */
204
205// this specialization should never be called until we start supporting
206// boolean option values like --name=enable or --name=false
207template <>
208inline void
209BooleanOption::import(const SBuf &) const
210{
211 assert(!"boolean options do not have ...=values (for now)");
212}
213
214using Options = std::vector<const Option *>;
215
218void ParseFlags(const Options &options);
219
220/* handy for Class::options() and lineOptions() defaults */
221const Options &NoOptions();
222
227
228} // namespace Acl
229
230std::ostream &operator <<(std::ostream &os, const Acl::Option &option);
231std::ostream &operator <<(std::ostream &os, const Acl::Options &options);
232
233#endif /* SQUID_ACL_OPTIONS_H */
234
std::ostream & operator<<(std::ostream &os, const Acl::Option &option)
Definition: Options.cc:248
#define assert(EX)
Definition: assert.h:19
Stores configuration of a typical boolean flag or a single-value Option.
Definition: Options.h:100
bool valued
whether a configured option had a value
Definition: Options.h:124
bool configured
whether the option was present in squid.conf
Definition: Options.h:121
bool disabled
whether the option was turned off
Definition: Options.h:123
OptionValue(const Value &aValue)
Definition: Options.h:111
bool enabled() const
whether the option is explicitly turned "on" (with or without a value)
Definition: Options.h:114
Value value
final value storage, possibly after conversions
Definition: Options.h:120
void reset()
go back to the default-initialized state
Definition: Options.h:118
Value value_type
Definition: Options.h:102
A single option supported by an ACL: -x[=value] or –name[=value].
Definition: Options.h:57
virtual bool configured() const =0
virtual void enable() const =0
called after parsing onName without a value (e.g., -x or –enable-x)
const char *const onName
A name that must be used to explicitly enable this Option (required).
Definition: Options.h:88
virtual void print(std::ostream &os) const =0
prints a configuration snippet (as an admin could have typed)
virtual void configureWith(const SBuf &rawValue) const =0
called after parsing onName and a value (e.g., -x=v or –enable-x=v)
virtual void disable() const =0
called after parsing offName (e.g., +i or –disable-x)
virtual void unconfigure() const =0
clear enable(), configureWith(), or disable() effects
virtual bool disabled() const =0
whether disable() has been called
virtual ~Option()
Definition: Options.h:61
Option(const char *nameThatEnables, const char *nameThatDisables=nullptr, ValueExpectation vex=valueNone)
Definition: Options.cc:66
ValueExpectation valueExpectation
expect "=value" part?
Definition: Options.h:94
ValueExpectation
Definition: Options.h:59
@ valueNone
Definition: Options.h:59
@ valueRequired
Definition: Options.h:59
@ valueOptional
Definition: Options.h:59
virtual bool valued() const =0
const char *const offName
Definition: Options.h:92
a type-specific Option (e.g., a boolean –toggle or -m=SBuf)
Definition: Options.h:130
virtual bool configured() const override
Definition: Options.h:145
virtual bool disabled() const override
whether disable() has been called
Definition: Options.h:146
void linkWith(Recipient *recipient) const
who to tell when this option is enabled
Definition: Options.h:137
virtual void disable() const override
called after parsing offName (e.g., +i or –disable-x)
Definition: Options.h:172
virtual void enable() const override
called after parsing onName without a value (e.g., -x or –enable-x)
Definition: Options.h:154
void import(const SBuf &rawValue) const
Definition: Options.h:192
virtual bool valued() const override
Definition: Options.h:147
virtual void print(std::ostream &os) const override
prints a configuration snippet (as an admin could have typed)
Definition: Options.h:181
Recipient * recipient_
parsing results storage
Definition: Options.h:196
virtual void configureWith(const SBuf &rawValue) const override
called after parsing onName and a value (e.g., -x=v or –enable-x=v)
Definition: Options.h:163
virtual void unconfigure() const override
clear enable(), configureWith(), or disable() effects
Definition: Options.h:149
TypedOption(const char *nameThatEnables, const char *nameThatDisables=nullptr, ValueExpectation vex=valueNone)
Definition: Options.h:133
Definition: SBuf.h:94
Definition: Acl.cc:31
TypedOption< BooleanOptionValue > BooleanOption
Definition: Options.h:202
TypedOption< TextOptionValue > TextOption
Definition: Options.h:203
const BooleanOption & CaseSensitivityOption()
Definition: Options.cc:241
const Options & NoOptions()
Definition: Options.cc:234
OptionValue< SBuf > TextOptionValue
Definition: Options.h:201
void ParseFlags(const Options &options)
Definition: Options.cc:227
std::vector< const Option * > Options
Definition: Options.h:214
OptionValue< bool > BooleanOptionValue
Definition: Options.h:200

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors