From 85e0ad9f1309afceaa8d3946c9273e089d3c25b8 Mon Sep 17 00:00:00 2001 From: Pauli Date: Thu, 30 May 2019 11:37:12 +1000 Subject: [PATCH] Document property hierarchy. Add documentation to indicate the interaction between global (context level) property queries and local (passed to fetch) ones. Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/9042) --- doc/man7/property.pod | 61 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/doc/man7/property.pod b/doc/man7/property.pod index e05f112b65..4f842e066c 100644 --- a/doc/man7/property.pod +++ b/doc/man7/property.pod @@ -68,7 +68,40 @@ Matching such clauses is not a requirement, but any additional optional match counts in favor of the algorithm. More details about that in the B section. A I is a sequence of comma separated property query clauses. -The full syntax for property queries appears below. +The full syntax for property queries appears below, but the available syntatic +features are: + +=over + +=item * + +B<=> is an infix operator providing an equality test. + +=item * + +B is an infix operator providing an inequality test. + +=item * + +B is a prefix operator that means that the following clause is optional +but preferred. + +=item * + +B<-> is a prefix operator that means any global query clause involving the +following property name should be ignored. + +=item * + +B<"..."> is a quoted string. +The quotes are not included in the body of the string. + +=item * + +B<'...'> is a quoted string. +The quotes are not included in the body of the string. + +=back =head2 Lookups @@ -87,7 +120,31 @@ In order to permit a more concise expression of boolean properties, there is one short cut: a property name alone (e.g. "default") is exactly equivalent to "default=yes" in both definitions and queries. -=head1 Syntax +=head2 Global and Local + +Two levels of property query are supported. +A context based property query that applies to all fetch operations and a local +property query. +Where both the context and local queries include a clause with the same name, +the local clause is used and the context one ignored. +For example, a context property query of "fips=yes" and a local property query +of "fips=no" would result in algorithms that have the "fips" property set t +"no". + +=head2 Override + +It is possible for a local property query to override a clause in the context +property query by preceeding the property name with a '-'. +For example, a conxtet property query that contains "fips=yes" would normally +result in implementations that have "fips=yes". +However, if the setting of +the "fips" property is irrelevant to the operations being performed, the local +property query can include the clause "-fips". +Note that the local property query could not use "fips=no" because that would +disallow any implementations with "fips=yes" rather than not caring about the +setting. + +=head1 SYNTAX The lexical syntax in EBNF is given by: