diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/format-specifiers.txt | 218 | ||||
-rw-r--r-- | doc/nis-design.txt | 238 | ||||
-rw-r--r-- | doc/sch-design.txt | 230 |
3 files changed, 251 insertions, 435 deletions
diff --git a/doc/format-specifiers.txt b/doc/format-specifiers.txt new file mode 100644 index 0000000..b6be91d --- /dev/null +++ b/doc/format-specifiers.txt @@ -0,0 +1,218 @@ +=== Functions In Function Specifiers === + +Format specifiers can reference values of attributes in the entry which +is currently being examined like so: + %{attribute} + +More built-in "function"s are available for importing values from other +entries and combining them with data from the current entry. Generally, +function invocations look like this: + %function(ARG1[,...]) + +A function-like invocation expects a comma-separated list of +double-quoted arguments. Any arguments which themselves contain a +double-quote need to escape the double-quote using a '\' character. +Naturally the '\' this character itself also needs to be escaped +whenever it appears. Some functions can take expressions as arguments, +allowing functions to operate on data after it has been acted on by +other functions. + +=== Implemented Functions === + * first(EXPRESSION[,DEFAULT]) + - Evaluates EXPRESSION, and if one or more values is available, + provides the first value. If no values result, then DEFAULT is + evaluated as an expression and the result is provided. + + * match(EXPRESSION,PATTERN[,DEFAULT]) + - Selects the value of EXPRESSION which matches the globbing pattern + PATTERN. If no values match, and a DEFAULT was specified, the + DEFAULT is produced, otherwise an error occurs. + - Example (examining "cn=group"): + dn: cn=group + member: bob + member: dave + %match("%{member}","b*") -> bob + %match("%{member}","d*") -> dave + %match("%{member}","e*") FAILS + %match("%{member}","e*","jim") -> jim + %match("%{member}","*","jim") -> jim (when a single value is required) + %match("%{member}","*","jim") -> bob,dave (when a list is acceptable) + * regmatch(EXPRESSION,PATTERN[,DEFAULT]) + - Selects the value of EXPRESSION which matches the extended regular + expression PATTERN. If no values match, and a DEFAULT was + specified, the DEFAULT is produced. + - Example (examining "cn=group"): + dn: cn=group + member: bob + member: dave + %regmatch("%{member}","^b.*") -> bob + %regmatch("%{member}","^d.*") -> dave + %regmatch("%{member}","e") -> dave + %regmatch("%{member}","^e") FAILS + %regmatch("%{member}","^e.*","jim") -> jim + %regmatch("%{member}",".*","jim") -> jim (when a single value is required) + %regmatch("%{member}",".*","jim") -> bob,dave (when a list is acceptable) + * regsub(EXPRESSION,PATTERN,TEMPLATE[,DEFAULT]) + - Selects the value of EXPRESSION which matches the extended regular + expression PATTERN and uses TEMPLATE to construct the output. If + no values match, and a DEFAULT was specified, the DEFAULT is + produced, otherwise an error occurs. The template is used to + construct a result using the n'th substring from the matched value + by using the sequence "%n" in the template. + - Example (examining "cn=group"): + dn: cn=group + member: bob + member: dave + %regsub("%{member}","o","%0") -> bob + %regsub("%{member}","o","%1") -> + %regsub("%{member}","^o","%0") FAILS + %regsub("%{member}","^d(.).*","%1") -> a + %regsub("%{member}","^(.*)e","t%1y") -> tdavy + %regsub("%{member}","^e","%1") FAILS + %regsub("%{member}","^e.*","%1","jim") -> jim + * deref(THISATTRIBUTE,THATATTRIBUTE) + - Creates a separated list of the values of THATATTRIBUTE for + directory entries named by this entry's THISATTRIBUTE. + - Example (examining "cn=group"): + dn: cn=group + member: uid=bob + member: uid=pete + - + dn: uid=bob + uid: bob + - + dn: uid=pete + uid: pete + %deref("member","foo") -> FAIL (when a single value is required) + %deref("member","foo") -> (when a list is acceptable) + %deref("member","uid") -> FAIL (when a single value is required) + %deref("member","uid") -> bob,pete (when a list is acceptable) + * deref_r(ATTRIBUTE[,OTHERATTRIBUTE[...]],VALUEATTRIBUTE) + - Looks for entries named by this entry's ATTRIBUTE, and then by + those entries' ATTRIBUTE, repeating the search no more entries to + find named by ATTRIBUTE. Then searches for entries named by that + set's OTHERATTRIBUTE, similarly repeating until a complete set of + entries is obtained, repeating the process for listed attribute + except the last. The VALUEATTRIBUTE of every entry examined along + the way will be returned. + - Example (examining "cn=group"): + dn: cn=group + member: cn=othergroup + member: uid=bob + - + dn: cn=othergroup + member: uid=pete + uid: bogus + - + dn: uid=bob + uid: bob + - + dn: uid=pete + uid: pete + %deref_r("member","foo") -> FAIL (when a single value is required) + %deref_r("member","foo") -> (when a list is acceptable) + %deref_r("member","uid") -> FAIL (when a single value is required) + %deref_r("member","uid") -> bogus,bob,pete (when a list is acceptable) + * referred(SET,THATATTRIBUTE,THATOTHERATTRIBUTE) + - Creates a separated list of the values of THATOTHERATTRIBUTE for + directory entries which have entries in the current group in the + named SET and which also have this entry's name as a value for + THATATTRIBUTE. Will fail if used in a context where a single + value is required. + - Example (examining "cn=group"): + dn: cn=group + - + dn: uid=bob + uid: bob + memberOf: cn=group + - + dn: uid=pete + uid: pete + memberOf: cn=group + %referred("cn=users","memberof","foo") -> FAIL (when a single value is required) + %referred("cn=users","memberof","foo") -> (when a list is acceptable) + %referred("cn=users","memberof","uid") -> FAIL (when a single value is required) + %referred("cn=users","memberof","uid") -> bob,pete (when a list is acceptable) + * referred_r(MAP,ATTRIBUTE[,OTHERMAP,OTHERATTRIBUTE[,...],VALUEATTRIBUTE) + - Searches for entries in the current domain in both the current map + and MAP which refer to this entry using ATTRIBUTE, searching for + entries in the current map and MAP for the resulting entries, + until a complete set is formed. Then searches for entries in MAP + and OTHERMAP which refer to entries in this set, repeating the + process until a new set is formed. The value of VALUEATTRIBUTE + for every entry encountered will be returned. Will fail if used + in a context where a single value is required. + - Example (examining "cn=group"): + dn: cn=group + - + dn: cn=othergroup + memberOf: cn=group + - + dn: uid=bob + uid: bob + memberOf: cn=group + - + dn: uid=pete + uid: pete + memberOf: cn=othergroup + %referred("people","memberof","foo") -> FAIL (when a single value is required) + %referred("people","memberof","foo") -> (when a list is acceptable) + %referred("people","memberof","uid") -> FAIL (when a single value is required) + %referred("people","memberof","uid") -> bob,pete (when a list is acceptable) + * merge(SEPARATOR,EXPRESSION[,...]) + - Evaluates and then creates a single value using multiple expressions + which can evaluate to either single values or lists. + - Example (examining "cn=group"): + dn: cn=group + membername: jim + member: uid=bob + member: uid=pete + - + dn: uid=bob + uid: bob + - + dn: uid=pete + uid: pete + %merge(",","%{membername}","%deref(\"member\",\"uid\")") -> jim,bob,pete + * collect(EXPRESSION[,...]) + - Evaluates each EXPRESSION in turn, creating a single list using all of + the values which are produced by evaluating every expression. + - Example (examining "cn=group"): + dn: cn=group + cn: group + membername: jim + member: uid=bob + member: uid=pete + %collect("%{member}","%{membername}") -> ["uid=bob","uid=pete","jim"] (when a list is acceptable) + %collect("%{member}","%{membername}") -> FAIL (when a list is not acceptable) + * link(EXPRESSION,PAD[,SEPARATOR,EXPRESSION,PAD[,...]) + - Evaluates each EXPRESSION in turn, padding each list of values using the + corresponding PAD value until they are all the same length, and then + producing a value using the first values from each list (separated by + the corresponding SEPARATOR), then using the second values from each + list, continuing until all lists have been exhausted. + - Example (examining "cn=group"): + dn: cn=group + cn: group + membername: jim + member: uid=bob + member: uid=pete + %link("%{member}","?","/","%{membername}","?") -> ["uid=bob/jim","uid=pete/?"] (when a list is acceptable) + %link("%{member}","-","/","%{membername}","") -> FAIL (when a list is not acceptable) + + * ifeq(ATTRIBUTE,VALUE,MATCH,NOMATCH) + - Evaluates VALUE and compares it to the entry's values for ATTRIBUTE. + If there is at least one value which is considered equal according to + the matching rules for ATTRIBUTE, evaluate and return MATCH, otherwise + evaluate and return NOMATCH. If VALUE can not be evaluated, fails to + evaluate. If MATCH or NOMATCH (whichever is appropriate) can not be + evaluated, fails to evaluate. + - Example (examining "cn=group"): + dn: cn=group + cn: group + membername: jim + member: uid=bob + member: uid=pete + %ifeq("membername","jim","yes","no") -> yes + %ifeq("membername","jeff","yes","no") -> no + %ifeq("madeup","jeff","yes","no") -> no diff --git a/doc/nis-design.txt b/doc/nis-design.txt index d0d9c30..fd894a4 100644 --- a/doc/nis-design.txt +++ b/doc/nis-design.txt @@ -260,21 +260,16 @@ one notable exception being that patterns for the "/" operator can not currently be anchored to the beginning or end of the string). A format specifier can actually be interpreted in two ways: it can be -interpreted as a single value, or it can be interpreted as providing a -list of values. When the format specifier is being interpreted as a -single value, any reference to an attribute value which does not also -specify an alternate value will cause the directory server entry to be -ignored if the referenced attribute has no value defined for that entry, -or contains multiple values. In the above example, the entry would be -ignored if the "uid", "uidNumber", "gidNumber", or "homeDirectory" -attributes of the entry did not each contain exactly one value. - -The syntax further defines "functions" which can be used to concatenate -lists of multiple values into a single result, for example for groups: - %{cn}:%{userPassword:-*}:%{gidNumber}:%merge(",","%{memberUid}") -This filter takes advantage of a built-in "merge" function, which -processes zero or more single or list values and concatenates them -together with a "," separator, to generate the list of group members. +interpreted as a single value (when given as "nis-key-format" or +"nis-value-format"), or it can be interpreted as providing a list of +values ("nis-keys-format" or "nis-values-format"). When the format +specifier is being interpreted as a single value, any reference to an +attribute value which does not also specify an alternate value will +cause the directory server entry to be ignored if the referenced +attribute has no value defined for that entry, or contains multiple +values. In the above example, the entry would be ignored if the "uid", +"uidNumber", "gidNumber", or "homeDirectory" attributes of the entry did +not each contain exactly one value. The "nis-filter", "nis-key-format", and "nis-value-format" settings have sensible defaults for the maps which we expect to be commonly used -- @@ -283,207 +278,12 @@ specifiers which could trigger undefined behavior on clients -- for example by leaving the user's numeric UID empty in a passwd entry, which may be treated as "0" by inattentive clients. -A function-like invocation expects a comma-separated list of -double-quoted arguments. Any arguments which contain a double-quote -need to escape the double-quote using a '\' character. Naturally the -'\' this character itself also needs to be escaped whenever it appears. - -=== Implemented Functions === - * first(EXPRESSION[,DEFAULT]) - - Evaluates EXPRESSION, and if one or more values is available, - provides the first value. If no values result, then DEFAULT is - evaluated as an expression and the result is provided. - * match(EXPRESSION,PATTERN[,DEFAULT]) - - Selects the value of EXPRESSION which matches the globbing pattern - PATTERN. If zero or two or more values match, and a DEFAULT was - specified, the DEFAULT is produced, otherwise an error occurs. - - Example (examining "cn=group"): - dn: cn=group - member: bob - member: dave - %match("%{member}","b*") -> bob - %match("%{member}","d*") -> dave - %match("%{member}","e*") FAILS - %match("%{member}","e*","jim") -> jim - %match("%{member}","*","jim") -> jim (when a single value is required) - %match("%{member}","*","jim") -> bob,dave (when a list is acceptable) - * regmatch(EXPRESSION,PATTERN[,DEFAULT]) - - Selects the value of EXPRESSION which matches the extended regular - expression PATTERN. If zero or two or more values match, and a - DEFAULT was specified, the DEFAULT is produced, otherwise an error - occurs. - - Example (examining "cn=group"): - dn: cn=group - member: bob - member: dave - %regmatch("%{member}","^b.*") -> bob - %regmatch("%{member}","^d.*") -> dave - %regmatch("%{member}","e") -> dave - %regmatch("%{member}","^e") FAILS - %regmatch("%{member}","^e.*","jim") -> jim - %regmatch("%{member}",".*","jim") -> jim (when a single value is required) - %regmatch("%{member}",".*","jim") -> bob,dave (when a list is acceptable) - * regsub(EXPRESSION,PATTERN,TEMPLATE[,DEFAULT]) - - Selects the value of EXPRESSION which matches the extended regular - expression PATTERN and uses TEMPLATE to construct the output. If - zero or two or more values match, and a DEFAULT was specified, the - DEFAULT is produced, otherwise an error occurs. The template is - used to construct a result using the n'th substring from the - matched value by using the sequence "%n" in the template. - - Example (examining "cn=group"): - dn: cn=group - member: bob - member: dave - %regsub("%{member}","o","%0") -> bob - %regsub("%{member}","o","%1") -> - %regsub("%{member}","^o","%0") FAILS - %regsub("%{member}","^d(.).*","%1") -> a - %regsub("%{member}","^(.*)e","t%1y") -> tdavy - %regsub("%{member}","^e","%1") FAILS - %regsub("%{member}","^e.*","%1","jim") -> jim - * deref(THISATTRIBUTE,THATATTRIBUTE) - - Creates a separated list of the values of THATATTRIBUTE for - directory entries named by this entry's THISATTRIBUTE. Will fail - if used in a context where a single value is required. - - Example (examining "cn=group"): - dn: cn=group - member: uid=bob - member: uid=pete - - - dn: uid=bob - uid: bob - - - dn: uid=pete - uid: pete - %deref("member","foo") -> FAIL (when a single value is required) - %deref("member","foo") -> (when a list is acceptable) - %deref("member","uid") -> FAIL (when a single value is required) - %deref("member","uid") -> bob,pete (when a list is acceptable) - * deref_r(ATTRIBUTE[,OTHERATTRIBUTE[...]],VALUEATTRIBUTE) - - Looks for entries named by this entry's ATTRIBUTE, and then by - those entries' ATTRIBUTE, repeating the search no more entries to - find named by ATTRIBUTE. Then searches for entries named by that - set's OTHERATTRIBUTE, similarly repeating until a complete set of - entries is obtained, repeating the process for listed attribute - except the last. The VALUEATTRIBUTE of every entry examined along - the way will be returned. - - Example (examining "cn=group"): - dn: cn=group - member: cn=othergroup - member: uid=bob - - - dn: cn=othergroup - member: uid=pete - uid: bogus - - - dn: uid=bob - uid: bob - - - dn: uid=pete - uid: pete - %deref_r("member","foo") -> FAIL (when a single value is required) - %deref_r("member","foo") -> (when a list is acceptable) - %deref_r("member","uid") -> FAIL (when a single value is required) - %deref_r("member","uid") -> bogus,bob,pete (when a list is acceptable) - * referred(MAP,THATATTRIBUTE,THATOTHERATTRIBUTE) - - Creates a separated list of the values of THATOTHERATTRIBUTE for - directory entries which have entries in the current domain in the - named MAP and which also have this entry's name as a value for - THATATTRIBUTE. Will fail if used in a context where a single - value is required. - - Example (examining "cn=group"): - dn: cn=group - - - dn: uid=bob - uid: bob - memberOf: cn=group - - - dn: uid=pete - uid: pete - memberOf: cn=group - %referred("people","memberof","foo") -> FAIL (when a single value is required) - %referred("people","memberof","foo") -> (when a list is acceptable) - %referred("people","memberof","uid") -> FAIL (when a single value is required) - %referred("people","memberof","uid") -> bob,pete (when a list is acceptable) - * referred_r(MAP,ATTRIBUTE[,OTHERMAP,OTHERATTRIBUTE[,...],VALUEATTRIBUTE) - - Searches for entries in the current domain in both the current map - and MAP which refer to this entry using ATTRIBUTE, searching for - entries in the current map and MAP for the resulting entries, - until a complete set is formed. Then searches for entries in MAP - and OTHERMAP which refer to entries in this set, repeating the - process until a new set is formed. The value of VALUEATTRIBUTE - for every entry encountered will be returned. Will fail if used - in a context where a single value is required. - - Example (examining "cn=group"): - dn: cn=group - - - dn: cn=othergroup - memberOf: cn=group - - - dn: uid=bob - uid: bob - memberOf: cn=group - - - dn: uid=pete - uid: pete - memberOf: cn=othergroup - %referred("people","memberof","foo") -> FAIL (when a single value is required) - %referred("people","memberof","foo") -> (when a list is acceptable) - %referred("people","memberof","uid") -> FAIL (when a single value is required) - %referred("people","memberof","uid") -> bob,pete (when a list is acceptable) - * merge(SEPARATOR,EXPRESSION[,...]) - - Evaluates and then creates a single value using multiple expressions - which can evaluate to either single values or lists. - - Example (examining "cn=group"): - dn: cn=group - membername: jim - member: uid=bob - member: uid=pete - - - dn: uid=bob - uid: bob - - - dn: uid=pete - uid: pete - %merge(",","%{membername}","%deref(\"member\",\"uid\")") -> jim,bob,pete - * collect(EXPRESSION[,...]) - - Evaluates each EXPRESSION in turn, creating a single list using all of - the values which are produced by evaluating every expression. - - Example (examining "cn=group"): - dn: cn=group - cn: group - membername: jim - member: uid=bob - member: uid=pete - %collect("%{member}","%{membername}") -> ["uid=bob","uid=pete","jim"] (when a list is acceptable) - %collect("%{member}","%{membername}") -> FAIL (when a list is not acceptable) - * link(EXPRESSION,PAD[,SEPARATOR,EXPRESSION,PAD[,...]) - - Evaluates each EXPRESSION in turn, padding each list of values using the - corresponding PAD value until they are all the same length, and then - producing a value using the first values from each list (separated by - the corresponding SEPARATOR), then using the second values from each - list, continuing until all lists have been exhausted. - - Example (examining "cn=group"): - dn: cn=group - cn: group - membername: jim - member: uid=bob - member: uid=pete - %link("%{member}","?","/","%{membername}","?") -> ["uid=bob/jim","uid=pete/?"] (when a list is acceptable) - %link("%{member}","-","/","%{membername}","") -> FAIL (when a list is not acceptable) - * ifeq(ATTRIBUTE,VALUE,MATCH,NOMATCH) - - Evaluates VALUE and compares it to the entry's values for ATTRIBUTE. - If there is at least one value which is considered equal according to - the matching rules for ATTRIBUTE, evaluate and return MATCH, otherwise - evaluate and return NOMATCH. If VALUE can not be evaluated, fails to - evaluate. If MATCH or NOMATCH (whichever is appropriate) can not be - evaluated, fails to evaluate. - - Example (examining "cn=group"): - dn: cn=group - cn: group - membername: jim - member: uid=bob - member: uid=pete - %ifeq("membername","jim","yes","no") -> yes - %ifeq("membername","jeff","yes","no") -> no - %ifeq("madeup","jeff","yes","no") -> no +The format specifier syntax further defines "functions" which can be +used to concatenate lists of multiple values into a single result, for +example for groups: + %{cn}:%{userPassword:-*}:%{gidNumber}:%merge(",","%{memberUid}") +This filter takes advantage of a built-in "merge" function, which +processes zero or more single or list values and concatenates them +together with a "," separator, to generate the list of the group's +members. The available functions are described more fully in +"format-specifiers.txt". diff --git a/doc/sch-design.txt b/doc/sch-design.txt index a94ad81..8854193 100644 --- a/doc/sch-design.txt +++ b/doc/sch-design.txt @@ -110,219 +110,17 @@ entry's object classes) or an existing attribute, like so: cn=%{cn} A format specifier can actually be interpreted in two ways: it can be -interpreted as a single value, or it can be interpreted as providing a -list of values. When the format specifier is being interpreted as a -single value, any reference to an attribute value which does not also -specify an alternate value will cause the directory server entry to be -ignored if the referenced attribute has no value defined for that entry, -or contains multiple values. In the above example, the RDN is evaluated -in such a manner. - -For all other attributes, if an attribute is multi-valued, the resulting -entry will have a corresponding number of values. - -A pair of built-in "function"s are available for importing values from -other entries. - -A function-like invocation expects a comma-separated list of -double-quoted arguments. Any arguments which contain a double-quote -need to escape the double-quote using a '\' character. Naturally the -'\' this character itself also needs to be escaped whenever it appears. - -=== Implemented Functions === - * first(EXPRESSION[,DEFAULT]) - - Evaluates EXPRESSION, and if one or more values is available, - provides the first value. If no values result, then DEFAULT is - evaluated as an expression and the result is provided. - * match(EXPRESSION,PATTERN[,DEFAULT]) - - Selects the value of EXPRESSION which matches the globbing pattern - PATTERN. If no values match, and a DEFAULT was specified, the - DEFAULT is produced, otherwise an error occurs. - - Example (examining "cn=group"): - dn: cn=group - member: bob - member: dave - %match("%{member}","b*") -> bob - %match("%{member}","d*") -> dave - %match("%{member}","e*") FAILS - %match("%{member}","e*","jim") -> jim - %match("%{member}","*","jim") -> jim (when a single value is required) - %match("%{member}","*","jim") -> bob,dave (when a list is acceptable) - * regmatch(EXPRESSION,PATTERN[,DEFAULT]) - - Selects the value of EXPRESSION which matches the extended regular - expression PATTERN. If no values match, and a DEFAULT was - specified, the DEFAULT is produced. - - Example (examining "cn=group"): - dn: cn=group - member: bob - member: dave - %regmatch("%{member}","^b.*") -> bob - %regmatch("%{member}","^d.*") -> dave - %regmatch("%{member}","e") -> dave - %regmatch("%{member}","^e") FAILS - %regmatch("%{member}","^e.*","jim") -> jim - %regmatch("%{member}",".*","jim") -> jim (when a single value is required) - %regmatch("%{member}",".*","jim") -> bob,dave (when a list is acceptable) - * regsub(EXPRESSION,PATTERN,TEMPLATE[,DEFAULT]) - - Selects the value of EXPRESSION which matches the extended regular - expression PATTERN and uses TEMPLATE to construct the output. If - no values match, and a DEFAULT was specified, the DEFAULT is - produced, otherwise an error occurs. The template is used to - construct a result using the n'th substring from the matched value - by using the sequence "%n" in the template. - - Example (examining "cn=group"): - dn: cn=group - member: bob - member: dave - %regsub("%{member}","o","%0") -> bob - %regsub("%{member}","o","%1") -> - %regsub("%{member}","^o","%0") FAILS - %regsub("%{member}","^d(.).*","%1") -> a - %regsub("%{member}","^(.*)e","t%1y") -> tdavy - %regsub("%{member}","^e","%1") FAILS - %regsub("%{member}","^e.*","%1","jim") -> jim - * deref(THISATTRIBUTE,THATATTRIBUTE) - - Creates a separated list of the values of THATATTRIBUTE for - directory entries named by this entry's THISATTRIBUTE. - - Example (examining "cn=group"): - dn: cn=group - member: uid=bob - member: uid=pete - - - dn: uid=bob - uid: bob - - - dn: uid=pete - uid: pete - %deref("member","foo") -> FAIL (when a single value is required) - %deref("member","foo") -> (when a list is acceptable) - %deref("member","uid") -> FAIL (when a single value is required) - %deref("member","uid") -> bob,pete (when a list is acceptable) - * deref_r(ATTRIBUTE[,OTHERATTRIBUTE[...]],VALUEATTRIBUTE) - - Looks for entries named by this entry's ATTRIBUTE, and then by - those entries' ATTRIBUTE, repeating the search no more entries to - find named by ATTRIBUTE. Then searches for entries named by that - set's OTHERATTRIBUTE, similarly repeating until a complete set of - entries is obtained, repeating the process for listed attribute - except the last. The VALUEATTRIBUTE of every entry examined along - the way will be returned. - - Example (examining "cn=group"): - dn: cn=group - member: cn=othergroup - member: uid=bob - - - dn: cn=othergroup - member: uid=pete - uid: bogus - - - dn: uid=bob - uid: bob - - - dn: uid=pete - uid: pete - %deref_r("member","foo") -> FAIL (when a single value is required) - %deref_r("member","foo") -> (when a list is acceptable) - %deref_r("member","uid") -> FAIL (when a single value is required) - %deref_r("member","uid") -> bogus,bob,pete (when a list is acceptable) - * referred(SET,THATATTRIBUTE,THATOTHERATTRIBUTE) - - Creates a separated list of the values of THATOTHERATTRIBUTE for - directory entries which have entries in the current group in the - named SET and which also have this entry's name as a value for - THATATTRIBUTE. Will fail if used in a context where a single - value is required. - - Example (examining "cn=group"): - dn: cn=group - - - dn: uid=bob - uid: bob - memberOf: cn=group - - - dn: uid=pete - uid: pete - memberOf: cn=group - %referred("cn=users","memberof","foo") -> FAIL (when a single value is required) - %referred("cn=users","memberof","foo") -> (when a list is acceptable) - %referred("cn=users","memberof","uid") -> FAIL (when a single value is required) - %referred("cn=users","memberof","uid") -> bob,pete (when a list is acceptable) - * referred_r(MAP,ATTRIBUTE[,OTHERMAP,OTHERATTRIBUTE[,...],VALUEATTRIBUTE) - - Searches for entries in the current domain in both the current map - and MAP which refer to this entry using ATTRIBUTE, searching for - entries in the current map and MAP for the resulting entries, - until a complete set is formed. Then searches for entries in MAP - and OTHERMAP which refer to entries in this set, repeating the - process until a new set is formed. The value of VALUEATTRIBUTE - for every entry encountered will be returned. Will fail if used - in a context where a single value is required. - - Example (examining "cn=group"): - dn: cn=group - - - dn: cn=othergroup - memberOf: cn=group - - - dn: uid=bob - uid: bob - memberOf: cn=group - - - dn: uid=pete - uid: pete - memberOf: cn=othergroup - %referred("people","memberof","foo") -> FAIL (when a single value is required) - %referred("people","memberof","foo") -> (when a list is acceptable) - %referred("people","memberof","uid") -> FAIL (when a single value is required) - %referred("people","memberof","uid") -> bob,pete (when a list is acceptable) - * merge(SEPARATOR,EXPRESSION[,...]) - - Evaluates and then creates a single value using multiple expressions - which can evaluate to either single values or lists. - - Example (examining "cn=group"): - dn: cn=group - membername: jim - member: uid=bob - member: uid=pete - - - dn: uid=bob - uid: bob - - - dn: uid=pete - uid: pete - %merge(",","%{membername}","%deref(\"member\",\"uid\")") -> jim,bob,pete - * collect(EXPRESSION[,...]) - - Evaluates each EXPRESSION in turn, creating a single list using all of - the values which are produced by evaluating every expression. - - Example (examining "cn=group"): - dn: cn=group - cn: group - membername: jim - member: uid=bob - member: uid=pete - %collect("%{member}","%{membername}") -> ["uid=bob","uid=pete","jim"] (when a list is acceptable) - %collect("%{member}","%{membername}") -> FAIL (when a list is not acceptable) - * link(EXPRESSION,PAD[,SEPARATOR,EXPRESSION,PAD[,...]) - - Evaluates each EXPRESSION in turn, padding each list of values using the - corresponding PAD value until they are all the same length, and then - producing a value using the first values from each list (separated by - the corresponding SEPARATOR), then using the second values from each - list, continuing until all lists have been exhausted. - - Example (examining "cn=group"): - dn: cn=group - cn: group - membername: jim - member: uid=bob - member: uid=pete - %link("%{member}","?","/","%{membername}","?") -> ["uid=bob/jim","uid=pete/?"] (when a list is acceptable) - %link("%{member}","-","/","%{membername}","") -> FAIL (when a list is not acceptable) - * ifeq(ATTRIBUTE,VALUE,MATCH,NOMATCH) - - Evaluates VALUE and compares it to the entry's values for ATTRIBUTE. - If there is at least one value which is considered equal according to - the matching rules for ATTRIBUTE, evaluate and return MATCH, otherwise - evaluate and return NOMATCH. If VALUE can not be evaluated, fails to - evaluate. If MATCH or NOMATCH (whichever is appropriate) can not be - evaluated, fails to evaluate. - - Example (examining "cn=group"): - dn: cn=group - cn: group - membername: jim - member: uid=bob - member: uid=pete - %ifeq("membername","jim","yes","no") -> yes - %ifeq("membername","jeff","yes","no") -> no - %ifeq("madeup","jeff","yes","no") -> no +interpreted as a single value (as it is for "schema-compat-entry-rdn" +values), or it can be interpreted as providing a list of values (as it +is for "schema-compat-entry-attribute" values). When the format +specifier is being interpreted as a single value, any reference to an +attribute value which does not also specify an alternate value will +cause the directory server entry to be ignored if the referenced +attribute has no value defined for that entry, or contains multiple +values. + +The format specifier syntax further defines "functions" which can be +used to manipulate values for attributes in the entry being examined, +follow references to other entries and retrieve values from them, and to +manipulate those values into whatever format is required. The available +functions are described more fully in "format-specifiers.txt". |