aci

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 8, 2023 License: MIT Imports: 13 Imported by: 0

README

Go Report Card Go Reference Software License codecov contributions welcome Experimental GitHub Workflow Status (with event) Libraries.io dependency status for GitHub repo Author GitHub release (with filter) Help Animals

Overview

Package aci implements the complete ACIv3 syntax as an SDK in a vendor-agnostic manner with rich features and a flexible design.

License

The aci package -- from go-aci -- is available under the terms of the MIT license.

For further details, see the LICENSE file within the root of the linked repository.

Dependencies

This package depends upon the following official (built-in) Go packages:

This package depends upon the following third-party packages:

* Conceived and maintained by same author

Status and Production Roadmap

Per the badge in the header, this package is to be regarded as highly experimental.

Design for this package began during June of 2023. As such, it is quite infantile and has not been subjected to any known use in the wild.

Because of this, it should NOT be used in any production or mission-critical context without extreme scrutiny.

The only "safe" applications for this package -- at the time of this writing -- are those confined to R&D, PoC, testing and other low-or-no-risk scenarios.

Adoption of this package is NOT a substitute for a comprehensive ACI review process. It is intended to reduce tedium, not assume full responsibility for ACI authorship and management.

If you want to try and tie some A.I into this, thats your business -- but don't complain to me when some emerging intelligence locks you out of your DIT because it considers you a threat. 🤓

About ACIs

Within the context of ACIv3, An ACI is an expressive statement or "policy" that is used to define the disclosing or withholding of information for an X.500/LDAP DIT as it pertains to its userbase.

In layperson's terms, ACIs are a specific and (largely) non-proprietary form of "LDAP permissions" that govern who can read, write, search, etc.

Not all LDAP server implementations support the ACIv3 syntax, but several do. Check your vendor or reference material for compatibility information.

Implementation Compatibility Notice

The ACIv3 syntax, though largely the same across the multiple supporting directory products that have adopted it, does have a few variations in terms of available keywords and features.

Though this is not a comprehensive list, a few of these cases are listed below:

  • TargetRule scoping, through the targetscope keyword
  • BindRule DN roles, through the roledn keyword
  • Group attribute-based value matching, through the groupattr keyword
  • LDAP Extended Operation OID definitions, through the extop keyword
  • LDAP Control OID definitions, through the targetcontrol keyword
  • Rights definitions, such as import and export
  • Number of supported 'levels' for inheritance value matching

This package aims to support ALL of the facets of the ACIv3 syntax without exception. Users will need to verify, however, that any ACI definitions generated -- in part or in whole as a result of using this package -- are compatible with their particular X.500/LDAP DSA implementation; check the docs and always listen to your vendor!

Features

  • Intuitive
    • Well-documented with numerous examples
    • Written with consideration for the various strata of LDAP engineers
    • Style leans towards "informative" more so than "succinct", and strives to be more helpful than terse
  • Efficient
    • Easy initialization routines available for those on-the-go
    • Unnecessary string literals are not stored -- for example, the ldap:/// prefix required of all LDAP DNs per ACIv3 -- yet they will still be present during string representation
      • Thus, less typing for full compliance!
    • Parsers offered via go-antlraci are wrapped and extended in this package in a "conveniently compartmentalized" manner
      • All-or-nothing Instruction parsing is not required
      • Users may opt to parse only a single TargetRule or an entire (nested!) BindRules hierarchical expression!
      • All major components allow compartmentalized parsing:
        • TargetRule
        • TargetRules
        • BindRule
        • BindRules
        • PermissionBindRule
        • PermissionBindRules
        • Instruction
        • Instructions
    • Memory usage was given particular consideration during the initial design phase
      • Certain values, such as an SSF level, were designed to fit (completely!) inside a single byte instance, regardless of the effective value
      • All numerical types utilize only the smallest possible primitive numeral type (e.g.: uint8, uint16) to suit its needs; never too much, and never too little!
      • Embedded pointer references are leveraged centrally throughout this package; storage of unneeded string literals is avoided wherever possible
    • A package-wide cyclomatic complexity factor limit of nine (9) is imposed
      • We realize the standard recommended maximum is fifteen (15); we feel we can do better!
      • The following imported packages also exercise this philosophy:
  • Compatible
    • Overall package design is meant to honor all of the facets of the ACIv3 specification in its entirety
    • No single vendor implementation is catered-to exclusively
    • So-called "Happy Mediums" were chosen at all possible points, favoring the exclusion of no one over any vendor-partisan implementation
    • Quite simply: chances are good that this package supports more of the ACIv3 syntax than your actual LDAP product does
  • Flexible
    • ACI composition can be approached in a variety of ways, without enforcing any particular "style"
    • Parenthetical encapsulation, padding and other attributes can be enabled or disabled for select (and eligible) type instances when desired, or even set globally in certain cases
    • Two (2) distinct quotation styles are supported for multi-valued DNs, OIDs and ATs present within eligible BindRule and/or TargetRule instances; see here for details
    • Fluent-style "method chaining" is supported, but not required
    • Most values can be assigned and set 'piecemeal', or in an 'all-in-one-shot' context

Parsing vs. Assembly

This package imports an ANTLR4 parsing subsystem to facilitate the "conversion" of ACI textual definitions into proper type instances. This functionality is provided by the go-antlraci package.

The parser reads the user-provided textual expression, processes the components and generates a proper instance of the package-provided type.

For example, this is a basic parse operation in which an abstract SSF context is evaluated as greater than or equal to an SSF value of 128. This expression is to be converted into an instance of BindRule.

// raw textual expression
raw := `ssf >= "128"`

// create variable for our
// new BindRule
var br BindRule

// Parse the above raw variable using
// your BindRule instance's Parse
// method ...
if err := br.Parse(raw); err != nil {
        fmt.Println(err) // always check your parser errors
        return
}

On the other hand, one need not limit their activities to "parsing of textual expressions"; one can also assemble various expressive object instances and input only the specific values needed.

For example, this is a basic assembly operation that mirrors the outcome of the above:

// Create our SSF instance
obj := SSF(128)

// Use object's Ge (Greater Than Or Equal)
// method to create a new BindRule instance

br := obj.Ge()

Which technique is "better" depends on the use-case. For individuals writing ACIs themselves, the "assembly" option may seem more appropriate.

Then again, the same sentiment may not apply to situations in which there are no individuals, and the process is wholly automated: the "parsing" option may be far more appealing.

Potential Use Cases

This package could conceivably be used in any of the following scenarios:

  • For Directory security audits that pertain to, or include, access control review
  • For Directory personnel in charge of authoring and/or managing rich documentation
  • For Directory personnel who desire a means to author and/or manage sets of ACIs in a more programmatic / automated manner, perhaps with the aid of a templating system
  • For use as an access control framework within an actual (Go-based) Directory System Agent implementation that honors the ACI syntax
  • For generalized experimentation within the realm of DSA access control design

Limitations

The go-aci package (straight out of the box, so to speak) is not an access control decision-making framework unto itself -- that particular functionality would reside in the X.500/LDAP server to be protected through the use of ACIs.

However this package could be leveraged to craft such a framework, given all of the syntax-defined types are made available to the end user. If users wish to approach this concept, they are advised to leverage the underlying go-stackage Stack type's methods for implementing evaluatory capabilities, such as attribute value assertion checks and the like. This would conceivably allow the use of matchingRule and ldapSyntax operations that precede attribute value disclosure/withholding (hint: take a look at go-schemax if this capability interests you).

Comparison Operators

Thanks to the import of the go-stackage package, this package gains access to all of the necessary comparison operators for use in the crafting of ACIv3 compliant BindRule and TargetRule expressions.

Below are two (2) tables containing all of the comparison operators available, as well all of the applicable (and non-applicable) scenarios for their use. These tables are based upon vendor documentation for multiple adopters of the ACIv3 syntax, therefore it may not reflect the offerings of every product identically.

Bind Keyword Eq Ne Lt Le Gt Ge
ip ✅ ✅ ❌ ❌ ❌ ❌
dns ✅ ✅ ❌ ❌ ❌ ❌
userdn ✅ ✅ ❌ ❌ ❌ ❌
groupdn ✅ ✅ ❌ ❌ ❌ ❌
roledn ✅ ✅ ❌ ❌ ❌ ❌
userattr ✅ ✅ ❌ ❌ ❌ ❌
groupattr ✅ ✅ ❌ ❌ ❌ ❌
authmethod ✅ ✅ ❌ ❌ ❌ ❌
dayofweek ✅ ✅ ❌ ❌ ❌ ❌
ssf ✅ ✅ ✅ ✅ ✅ ✅
timeofday ✅ ✅ ✅ ✅ ✅ ✅
Target Keyword Eq Ne Lt Le Gt Ge
target ✅ ✅ ❌ ❌ ❌ ❌
target_to ✅ ✅ ❌ ❌ ❌ ❌
target_from ✅ ✅ ❌ ❌ ❌ ❌
targetattr ✅ ✅ ❌ ❌ ❌ ❌
targetfilter ✅ ✅ ❌ ❌ ❌ ❌
targattrfilters ✅ ❌ ❌ ❌ ❌ ❌
targetscope ✅ ❌ ❌ ❌ ❌ ❌
targetcontrol ✅ ✅ ❌ ❌ ❌ ❌
extop ✅ ✅ ❌ ❌ ❌ ❌

Quotation Schemes

Another trait of this package's flexibility is the ability to handle either of the following quotation schemes when parsing or building statements that reference a multi-valued expression:

"value" || "value" || "value" ...
"value || value || value" ...

In particular, these sorts of quotation schemes appear in the following scenarios:

  • targetattr TargetRules for lists of LDAP ATs
  • target, target_to and target_from TargetRule DNs
  • userdn and groupdn BindRule DNs
  • extop and targetcontrol TargetRule OIDs

Users are advised to honor the quotation scheme recommended by their vendor or product documentation. This package aims to support either of the above schemes with no variance in the end result, but has no official position as to which of these schemes should be honored by the user except that quotation should always be used in some form.

Contribution Encouraged

The ACIv3 syntax is fairly complex, rendering its innate flexibility akin to a double-edged sword. As such there may be errors, or concepts overlooked by the author within this package. Users are strongly encouraged to speak up if they perceive a feature or some behavioral trait of the package to be suboptimal or incomplete in some manner.

See issues for all bug reports -- past and present -- as well as a means to file new ones.

Some Words of Warning

The concept of access control -- whether related to the security of databases or not -- is an extremely critical component of effective cybersecurity design as a whole. Permissions, such as ACIs, should never be implemented in an untested or cavalier fashion. Breaches associated with poor access control models can destroy companies, end careers and maybe even endanger human lives.

Though this package can reduce much of the tedium associated with directory security through the use of permissions, it can just as easily generate completely bogus rules that will have the opposite intended effect. Even worse, it may generate rules that may expose sensitive DIT content!

Those who choose to leverage this package are strongly advised to triple-check their work. Make no assumptions. Take no unnecessary risks. TEST. TEST. TEST and then TEST some more!

Another area of risk is the disposition (or lack thereof) regarding so-called "ACI Best Practices", which do vary across the various supporting directory products on the market. Users uncertain as to the best approach for a desired action are strongly advised to ask their vendor, or consult an appropriate online community forum.

By now, it is likely obvious this package aims to provide everything one could possibly need to compose an ACI. However, this package does not discriminate ACIs that may be overtly "broad" in their influence or entry-matching potential.

One such example of this is careless use of the negated equality operator (!=), which (when used improperly) can disclose myriad attribute values unintentionally. This particular case is well-documented in vendor manuals for supporting directory products (likely for legal CYA reasons). Users are advised to LEARN the syntax well enough to know when to take such risks.

Documentation

Index

Examples

Constants

View Source 
const AttributeFilterOperationsCommaDelim = 0

AttributeFilterOperationsCommaDelim shall invoke the default delimitation character offered by this package for use within instances of the AttributeFilterOperations type.

In cases where the AttributeFilterOperations type is used to represent any TargetRule bearing the targattrfilters keyword context, one (1) of two (2) different delimiter characters MAY be permitted for use, depending on which directory product is in use.

Use of this constant allows the use of a comma (ASCII #44) to delimit the slices in an AttributeFilterOperations instance as opposed to the alternative delimiter (semicolon, ASCII #59).

This constant may be fed to the SetDelimiter method that is extended through the AttributeFilterOperations type.

This is the default setting for the above scenario, and likely need to be specified manually unless reverting back from the alternative character.

View Source 
const AttributeFilterOperationsSemiDelim = 1

AttributeFilterOperationsSemiDelim invokes the alternative delimitation character offered by this package for use within instances of the AttributeFilterOperations type.

In cases where the AttributeFilterOperations type is used to represent any TargetRule bearing the targattrfilters keyword context, one (1) of two (2) different delimiter characters MAY be permitted for use, depending on which directory product is in use.

Use of this constant allows the use of a semicolon (ASCII #59) to delimit the slices in an AttributeFilterOperations instance as opposed to the default delimiter (comma, ASCII #44).

This constant may be fed to the SetDelimiter method that is extended through the AttributeFilterOperations type.

View Source 
const MultivalOuterQuotes = 1

MultivalOuterQuotes represents the alternate quotation style used by this package. In cases where a multi-valued BindRule or TargetRule expression involving LDAP distinguished names, ASN.1 Object Identifiers (in dot notation) and LDAP Attribute Type names is being created, this constant will enforce only outer-most double-quotation of the whole sequence of values, including the delimiters. 

Example: keyword = "<val> || <val> || <val>"

This constant may be fed to the SetQuoteStyle method that is extended through eligible types.

View Source 
const MultivalSliceQuotes = 0

MultivalSliceQuotes represents the standard quotation scheme offered by this package. In cases where a multi-valued BindRule or TargetRule expression involving LDAP distinguished names, ASN.1 Object Identifiers (in dot notation) and LDAP Attribute Type names is being created, this constant shall disable outermost quotation and will, instead, quote individual values. This will NOT enclose symbolic OR (||) delimiters within quotations. 

Example: keyword = "<val>" || "<val>" || "<val>"

This constant may be fed to the SetQuoteStyle method that is extended through eligible types.

View Source 
const Version float32 = 3.0

Version defines the official ACI syntax version number implemented and honored by this package.

Variables

View Source 
var AuthenticationMethodLowerCase bool

AuthenticationMethodLowerCase allows control over the case folding of AuthenticationMethod string representation.

A value of true shall force lowercase normalization, while a value of false (default) forces uppercase normalization.

View Source 
var RulePadding bool = true

RulePadding is a global variable that will be applies to ALL TargetRule and Bindrule instances assembled during package operations. This is a convenient alternative to manually invoking the NoPadding method on a case-by-case basis.

Padding is enabled by default, and can be disabled here globally, or overridden for individual TargetRule/BindRule instances as needed.

Note that altering this value will not impact instances that were already created; this only impacts the creation of new instances.

View Source 
var StackPadding bool = true

StackPadding is a global variable that will be applies to ALL Stack instances assembled during package operations. This is a convenient alternative to manually invoking the NoPadding method on a case by case basis.

Padding is enabled by default, and can be disabled here globally, or overridden for individual Stack instances as needed.

Note that altering this value will not impact instances that were already created; this only impacts the creation of new instances.

Functions

func Hash 

func Hash(x any) (string, error)

Hash computes a SHA-1 hash value, derived from the String method output (or string value) of input value x.

The hash, if generated, is cast as a string prior to being returned alongside an error.

Input value x must qualify as one (1) of the following:

  • Must be a string in of itself, OR ...
  • Must be a type instance that has its own stringer method

Failing the above, a non-nil error instance is returned.

This package-level function is the basis for all Compare methods extended by myriad types throughout this package. In most cases, using an available Compare method is easier than using this function directly.

The hash evaluation offered by this package is meant to act as a supplement in a change review process or similar. The return value should not be used to gauge "validity", "nilness" or "initialization status" of an instance. In certain cases, two (2) dissimilar (and invalid!) instances of the same type shall evaluate as "equal". When string representation yields the same effective value for two (2) type instances, this is both guaranteed and expected behavior.

Types

type AttributeBindTypeOrValue 

type AttributeBindTypeOrValue struct {
	BindKeyword // BindUAT or BindGAT keywords only!
	// contains filtered or unexported fields
}

AttributeBindTypeOrValue contains a statement of the following syntax: 

<AttributeName>#<BindType -OR- AttributeValue>

Instances of this type are used in certain Bind Rules, particularly those that involve user-attribute or group-attribute keywords.

func ABTV 

func ABTV(kw BindKeyword, x ...any) (a AttributeBindTypeOrValue)

ABTV will return a new instance of AttributeBindTypeOrValue. The required BindKeyword must be either BindUAT or BindGAT. The optional input values (x), if provided, will be used to set the instance.

Example 
var atb AttributeBindTypeOrValue = ABTV(BindUAT)
atb.Set(AT(`owner`), GROUPDN)
fmt.Printf("%T: %s", atb, atb)

Output:

aci.AttributeBindTypeOrValue: owner#GROUPDN

func GAT 

func GAT(x ...any) AttributeBindTypeOrValue

GAT (Group-Attribute Name + Bind Type -OR- Attribute Value) returns an initialized instance of AttributeBindTypeOrValue configured for rules that leverage the `groupattr` Bind Rule keyword.

Example

This example demonstrates the creation of an instance of AttributeBindTypeOrValue. 

attr := AT(`owner`)
btype := SELFDN

atb := GAT(attr, btype)

fmt.Printf("%T: %s", atb, atb)

Output:

aci.AttributeBindTypeOrValue: owner#SELFDN

func UAT 

func UAT(x ...any) AttributeBindTypeOrValue

UAT (User-Attribute Name + Bind Type -OR- Attribute Value) returns an initialized instance of AttributeBindTypeOrValue configured for rules that leverage the `userattr` Bind Rule keyword.

Example

This example demonstrates the creation of an instance of AttributeBindTypeOrValue. 

attr := AT(`manager`)
btype := USERDN

atb := UAT(attr, btype)

fmt.Printf("%T: %s", atb, atb)

Output:

aci.AttributeBindTypeOrValue: manager#USERDN

func (AttributeBindTypeOrValue) BRM 

func (r AttributeBindTypeOrValue) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var atb AttributeBindTypeOrValue
fmt.Printf("%d available aci.BindRuleMethod instances", atb.BRM().Len())

Output:

2 available aci.BindRuleMethod instances

func (AttributeBindTypeOrValue) Compare 

func (r AttributeBindTypeOrValue) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) AttributeBindTypeOrValue instances using the Compare method. 

// these will eval as true (match) because the underlying
// string call does not include the Keyword. We need the
// bind rule to see that ...
attr := ABTV(BindUAT, `cACertificate`, `USERDN`)
oattr := ABTV(BindGAT, `cACertificate`, USERDN)

eqaBr := attr.Eq()
eqoBr := oattr.Eq()

fmt.Printf("Hashes are equal: %t", eqaBr.Compare(eqoBr))

Output:

Hashes are equal: false

func (AttributeBindTypeOrValue) Eq 

func (r AttributeBindTypeOrValue) Eq() (b BindRule)

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To a `userattr` or `groupattr` Bind keyword context.

Example

This example demonstrates the use of the AttributeBindTypeOrValue type's Eq method, allowing for the creation of a TargetRule instance containing the receiver value, and bearing the `targattrfilters` keyword context. 

attr := AT(`manager`)
btype := USERDN

atb := UAT(attr, btype)

fmt.Printf("%s", atb.Eq())

Output:

userattr = "manager#USERDN"

func (AttributeBindTypeOrValue) IsZero 

func (r AttributeBindTypeOrValue) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example

This example demonstrates a check of the receiver for "nilness". 

var atb AttributeBindTypeOrValue

fmt.Printf("Is zero: %t", atb.IsZero())

Output:

Is zero: true

func (AttributeBindTypeOrValue) Keyword 

func (r AttributeBindTypeOrValue) Keyword() Keyword

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned will be either BindUAT or BindGAT.

Example

This example demonstrates the interrogation of the receiver in order to discern the appropriate Keyword.

Its string representation, along with the name of the Keyword type, is shown. 

var atb AttributeBindTypeOrValue

fmt.Printf("Keyword is '%s' (type:%T)", atb.Keyword(), atb.Keyword())

Output:

Keyword is 'userattr' (type:aci.BindKeyword)

func (AttributeBindTypeOrValue) Ne 

func (r AttributeBindTypeOrValue) Ne() (b BindRule)

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To a `userattr`, `groupattr` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example

This example demonstrates the use of the AttributeBindTypeOrValue type's Ne method 

attr := AT(`manager`)
btype := USERDN

atb := UAT(attr, btype)

fmt.Printf("%s", atb.Ne())

Output:

userattr != "manager#USERDN"

func (*AttributeBindTypeOrValue) Parse 

func (r *AttributeBindTypeOrValue) Parse(raw string, bkw ...any) (err error)

Parse reads the input string (raw) in an attempt to marshal its contents into the receiver instance (r). An error is returned at the end of the process.

If no suitable BindKeyword is provided (bkw), the default is BindUAT. Valid options are BindUAT and BindGAT.

Example

This example demonstrates the creation of an instance of AttributeBindTypeOrValue.

In this example, a raw string representation of an AttributeBindTypeOrValue instance is used for parser input. 

txt := `manager#USERDN`
var atb AttributeBindTypeOrValue
err := atb.Parse(txt)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("%T: %s", atb, atb)

Output:

aci.AttributeBindTypeOrValue: manager#USERDN

func (*AttributeBindTypeOrValue) Set 

func (r *AttributeBindTypeOrValue) Set(x ...any) *AttributeBindTypeOrValue

Set assigns value(s) x to the receiver. The value(s) must be AttributeType and/or AttributeValue instances, created via the package-level AT and AV functions respectively.

Example

This example demonstrates the creation of an instance of AttributeBindTypeOrValue followed by a call of its String method through fmt.Printf.

The return value is the entirely of the receiver in string representation. 

var atb AttributeBindTypeOrValue = ABTV(BindUAT)
atb.Set(AT(`manager`), USERDN)
fmt.Printf("%s value is %s", atb.Keyword(), atb)

Output:

userattr value is manager#USERDN
Example (Alt)

This example demonstrates the creation of an instance of AttributeBindTypeOrValue followed by a call of its String method through fmt.Printf. In this example, the receiver instance is populated using only string values.

The return value is the entirely of the receiver in string representation. 

var atb AttributeBindTypeOrValue
atb.Set(`manager`, `USERDN`)
fmt.Printf("%s", atb)

Output:

manager#USERDN

func (AttributeBindTypeOrValue) String 

func (r AttributeBindTypeOrValue) String() (s string)

String is a stringer method that returns the string representation of the receiver.

Example

This example demonstrates the creation of an instance of AttributeBindTypeOrValue followed by a call of its String method.

The return value is the entirely of the receiver in string representation. 

var atb AttributeBindTypeOrValue
atb.Set(AT(`manager`), USERDN)
fmt.Printf("%s", atb)

Output:

manager#USERDN

func (AttributeBindTypeOrValue) Valid 

func (r AttributeBindTypeOrValue) Valid() (err error)

Valid returns an error indicative of whether the receiver is in an aberrant state.

Example

This example demonstrates the creation of an instance of AttributeBindTypeOrValue followed by a call of its Valid method for the purpose of sanity checking the receiver.

An error is reported and printed to STDOUT. 

var (
	atb AttributeBindTypeOrValue
	err error
)

if err = atb.Valid(); err != nil {
	fmt.Println(err)
}

Output:

aci.AttributeBindTypeOrValue instance is nil

type AttributeFilter 

type AttributeFilter struct {
	// contains filtered or unexported fields
}

AttributeFilter is a struct type that embeds an AttributeTyp and filter-style Rule. Instances of this type are a component in the creation of Target Rule definitions based upon the targattrfilters keyword.

func AF 

func AF(x ...any) AttributeFilter

AF initializes, optionally sets and returns a new instance of AttributeFilter, which is a critical component of the `targattrfilters` Target Rule.

Input values must be either a SearchFilter or an AttributeType.

Example

This example demonstrates the creation of an instance of AttributeFilter, which is strictly intended for use within instances of AttributeFilterOperation.

In this example, proper type instances are fed to the package level AF function to form a complete AttributeFilter instance.

The return type, AttributeFilter, is then shown in string representation. 

af := AF(
	AT(`homeDirectory`),
	Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`),
)

fmt.Printf("%s", af)

Output:

homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))

func (AttributeFilter) AttributeType 

func (r AttributeFilter) AttributeType() AttributeType

AttributeType returns the underlying instance of AttributeType, or a bogus AttributeType if unset.

Example

This example demonstrates the creation of an instance of AttributeFilter followed by a call of its AttributeType method.

The return type, AttributeType, is shown in string representation. 

aftxt := `homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))`
var af AttributeFilter
_ = af.Parse(aftxt) // shadow error for brevity

fmt.Printf("%s", af.AttributeType())

Output:

homeDirectory

func (AttributeFilter) Compare 

func (r AttributeFilter) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) AttributeFilter instances using the Compare method. 

f1 := AF(`objectClass`, `(|(objectClass=contractor)(objectClass=intern))`)
f2 := AF(`homeDirectory`, `(|(objectClass=contractor)(objectClass=intern))`)

fmt.Printf("Hashes are equal: %t", f1.Compare(f2))

Output:

Hashes are equal: false

func (AttributeFilter) IsZero 

func (r AttributeFilter) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example

This example demonstrates a check of the receiver for "nilness". 

var af AttributeFilter

fmt.Printf("Is zero: %t (obviously)", af.IsZero())

Output:

Is zero: true (obviously)

func (AttributeFilter) Keyword 

func (r AttributeFilter) Keyword() Keyword

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned is always TargetFilter.

Example

This example demonstrates the interrogation of the receiver in order to discern the appropriate Keyword.

Its string representation, along with the name of the Keyword type, is shown. 

var af AttributeFilter

fmt.Printf("Keyword is '%s' (type:%T)", af.Keyword(), af.Keyword())

Output:

Keyword is 'targattrfilters' (type:aci.TargetKeyword)

func (*AttributeFilter) Parse 

func (r *AttributeFilter) Parse(raw string) (err error)

Parse parses the string input value (raw) and attempts to marshal its contents into the receiver instance. An error is returned if the attempt should fail for some reason.

Example

This example demonstrates the creation of an instance of AttributeFilter, which is strictly intended for use within instances of AttributeFilterOperation.

In this example, a raw string representation of an AttributeFilter is used for parser input.

The return type, AttributeFilter, is then interrogated by way of the AttributeType and SearchFilter methods it makes available to the user. An alternative to this approach is to simply use its String method to get the whole value, if desired. 

aftxt := `objectClass:(&(objectClass=employee)(cn=Jesse Coretta))`
var af AttributeFilter
_ = af.Parse(`4537895439h`)
err := af.Parse(aftxt)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("AT:%q, FILTER:%q", af.AttributeType(), af.SearchFilter())

Output:

AT:"objectClass", FILTER:"(&(objectClass=employee)(cn=Jesse Coretta))"

func (AttributeFilter) SearchFilter 

func (r AttributeFilter) SearchFilter() SearchFilter

SearchFilter returns the underlying instance of SearchFilter, or a bogus SearchFilter if unset.

Example

This example demonstrates the creation of an instance of AttributeFilter followed by a call of its SearchFilter method.

The return type, SearchFilter, is shown in string representation. 

aftxt := `homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))`
var af AttributeFilter
_ = af.Parse(aftxt) // shadow error for brevity

fmt.Printf("%s", af.SearchFilter())

Output:

(&(objectClass=employee)(cn=Jesse Coretta))

func (*AttributeFilter) Set 

func (r *AttributeFilter) Set(x ...any) *AttributeFilter

Set assigns the provided address component to the receiver and returns the receiver instance in fluent-form.

Multiple values can be provided in variadic form, or piecemeal.

Example

This example demonstrates the creation of an instance of AttributeFilter, which is strictly intended for use within instances of AttributeFilterOperation.

In this example, proper type instances are fed to the Set method to form a complete AttributeFilter instance.

The return type, AttributeFilter, is then shown in string representation. 

var af AttributeFilter // see also the package level AF function
af.Set(
	AT(`homeDirectory`),
	Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`),
)

fmt.Printf("%s", af)

Output:

homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))

func (AttributeFilter) String 

func (r AttributeFilter) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example

This example demonstrates the creation of an instance of AttributeFilter followed by a call of its String method.

The return value is the entirely of the receiver in string representation. 

aftxt := `homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))`
var af AttributeFilter
_ = af.Parse(aftxt) // shadow error for brevity

fmt.Printf("%s", af)

Output:

homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))

func (AttributeFilter) Valid 

func (r AttributeFilter) Valid() (err error)

Valid returns an error indicative of whether the receiver is in an aberrant state.

Example

This example demonstrates the creation of an instance of AttributeFilter followed by a call of its Valid method for the purpose of sanity checking the receiver.

An error is reported and printed to STDOUT. 

var (
	af  AttributeFilter
	err error
)

if err = af.Valid(); err != nil {
	fmt.Println(err)
}

Output:

aci.AttributeFilter instance is nil

type AttributeFilterOperation 

type AttributeFilterOperation stackage.Stack

AttributeFilterOperation is a stackage.Stack type alias used to store Target Attribute Filters expressions, specifically those used within TargetRule instances bearing the `targattrfilters` TargetRule keyword context.

See also the AttributeFilterOperations type and its methods.

Example (ByAttributeOperationConstants)

This example demonstrates an alternative to the AFO package level example. Instead of feeding an instance of AttributeOperation into the function, one can also use the AttributeOperation constant itself to generate the type instance needed. This may be useful in situations which require portability of certain functionality. 

// define the desired attributeType
attr := AT(`homeDirectory`)

// define the filter expression
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)

// create an AttributeFilter instance
// using the above components
aF := AF(attr, filter)

// We'll use the Delete operation (DelOp)
// package constant to spawn a new instance
// of AttributeFilterOperation. This will
// produce the same result as the AFO example
// demonstrated earlier, except this time we
// will impose the Delete operation.
aFO := DelOp.AFO(aF)

fmt.Printf("%s", aFO)

Output:

delete=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))

func AFO 

func AFO(x ...any) (f AttributeFilterOperation)

AFO returns a freshly initialized instance of AttributeFilterOperation, configured to store one (1) or more AttributeFilter instances for the purpose of crafting TargetRule instances which bear the `targattrfilters` keyword context. Instances of this design are not generally needed outside of that context.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the AttributeFilter type (or its string equivalent) during initialization. This is merely a more convenient alternative to separate init and push procedures.

Multiple values are automatically ANDed using stackage.And() using the symbolic AND operator (&&).

See also the AttributeFilterOperations type, and its AFOs function, for the multi-valued incarnation of this type.

Example

This example demonstrates the creation of an instance of AttributeFilterOperation, which is strictly intended for use within instances of AttributeFilterOperations.

In this example, proper type instances are fed to the package level AFO function to form a complete AttributeFilterOperation instance.

The return type, AttributeFilterOperation, is then shown in string representation. 

// define the desired attributeType
attr := AT(`homeDirectory`)

// define the filter expression
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)

// create an AttributeFilter instance
// using the above components
aF := AF(attr, filter)

// When using the package level AFO function, it
// is necessary to feed it an AttributeOperation
// instance (either AddOp or DelOp) to define the
// disposition of the new instance.
aFO := AFO(AddOp, aF)

fmt.Printf("%s", aFO)

Output:

add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))

func (AttributeFilterOperation) Compare 

func (r AttributeFilterOperation) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) AttributeFilterOperation instances using the Compare method. 

attr := AT(`uidNumber`)
filter := Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF1 := AF(attr, filter)
aFO1 := AddOp.AFO(aF1)

attr = AT(`gidNumber`)
filter = Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF2 := AF(attr, filter)
aFO2 := DelOp.AFO(aF2)

fmt.Printf("Hashes are equal: %t", aFO1.Compare(aFO2))

Output:

Hashes are equal: false

func (AttributeFilterOperation) Contains 

func (r AttributeFilterOperation) Contains(x any) bool

Contains returns a Boolean value indicative of whether the type and its value were located within the receiver.

Valid input types are AttributeFilter or a valid string equivalent.

Case is significant in the matching process.

Example

This example demonstrates the use of the AttributeFilterOperation type's Contains method, allowing for basic text searches of the receiver.

Note that case is significant in the matching process for instances of this type. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO := AddOp.AFO(aF1, aF2)

fmt.Printf("%t", aFO.Contains(`homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))`))

Output:

true

func (AttributeFilterOperation) Eq 

func (r AttributeFilterOperation) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To a `targattrfilters` keyword context.

Example

This example demonstrates the use of the AttributeFilterOperation type's Eq method, allowing for the creation of a TargetRule instance containing the receiver value, and bearing the `targattrfilters` keyword context. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO := AddOp.AFO(aF1, aF2)

fmt.Printf("%s", aFO.Eq())

Output:

( targattrfilters = "add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern))" )

func (AttributeFilterOperation) F 

func (r AttributeFilterOperation) F() func(...any) AttributeFilter

F returns the appropriate instance creator function for crafting individual AttributeFilter instances for submission to the receiver. This is merely a convenient alternative to maintaining knowledge as to which function applies to the current receiver instance.

As there is only one possibility for instances of this design, the AF function is returned.

Example

This example demonstrates the use of the AttributeFilterOperation type's F method, which returns the appropriate slice building function for convenience. 

var aFO AttributeFilterOperation

// this returns the package-level AF function
Func := aFO.F()

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF := Func(attr, filter)

fmt.Printf("%s", aF)

Output:

homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))

func (AttributeFilterOperation) Index 

func (r AttributeFilterOperation) Index(idx int) (af AttributeFilter)

Index wraps go-stackage's Stack.Index method. Note that the Boolean OK value returned by go-stackage by default will be shadowed and not obtainable by the caller.

Example

This example demonstrates the use of the AttributeFilterOperation type's Index method to allow iteration of the receiver's contents. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO := AddOp.AFO(aF1, aF2)

idx := aFO.Index(1) // 2nd index in stack

fmt.Printf("%s", idx.AttributeType())

Output:

gecos

func (AttributeFilterOperation) IsZero 

func (r AttributeFilterOperation) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example

This example demonstrates a check of the receiver for "nilness" using the AttributeFilterOperation type's IsZero method. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF := AF(attr, filter)
aFO := AddOp.AFO(aF)

fmt.Printf("%t", aFO.IsZero())

Output:

false

func (AttributeFilterOperation) Keyword 

func (r AttributeFilterOperation) Keyword() Keyword

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned is always TargetFilter.

Example

This example demonstrates the use of the AttributeFilterOperation type's Keyword method. 

var aFO AttributeFilterOperation

fmt.Printf("%s", aFO.Keyword())

Output:

targattrfilters

func (AttributeFilterOperation) Kind 

func (r AttributeFilterOperation) Kind() string

Kind returns the categorical label assigned to the receiver.

Example

This example demonstrates the use of the AttributeFilterOperation type's Kind method. 

var aFO AttributeFilterOperation

fmt.Printf("%s", aFO.Kind())

Output:

targattrfilters

func (AttributeFilterOperation) Len 

func (r AttributeFilterOperation) Len() int

Len wraps go-stackage's Stack.Len method.

Example

This example demonstrates the use of the AttributeFilterOperation type's Len method to report the integer length of the receiver. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO := AddOp.AFO(aF1, aF2)

fmt.Printf("Length: %d", aFO.Len())

Output:

Length: 2

func (AttributeFilterOperation) Ne 

func (r AttributeFilterOperation) Ne() TargetRule

Ne performs no useful task, as negated equality comparison does not apply to TargetRule instances that bear the `targattrfilters` keyword context.

This method exists solely to convey this message and conform to Go's interface qualifying signature. When executed, this method will return a bogus TargetRule.

Negated equality TargetRule instances should be used with caution.

Example

This example demonstrates the use of the AttributeFilterOperation type's Ne method, which is not intended to be used in any situation ever. See the comments for this method for details. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
af := AF(attr, filter)
aFO := AddOp.AFO(af)

bogus := aFO.Ne()

fmt.Printf("%t", bogus.IsZero())

Output:

true

func (AttributeFilterOperation) Operation 

func (r AttributeFilterOperation) Operation() AttributeOperation

Operation returns AddOp or DelOp as extracted from the receiver's categorical label. If invalid, an invalid AttributeOperation value is returned.

Example

This example demonstrates a check of the receiver's operational disposition using the Operation method. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF := AF(attr, filter)
aFO := AddOp.AFO(aF)

fmt.Printf("%s", aFO.Operation())

Output:

add

func (*AttributeFilterOperation) Parse 

func (r *AttributeFilterOperation) Parse(raw string) error

Parse returns an error instance following an attempt to parse input raw into the receiver instance. A successful parse will clobber (or obliterate) any contents already present within the receiver.

Example

This example demonstrates the creation of an instance of AttributeFilterOperation using the AttributeFilterOperation type's Parse method.

In this example, a raw string representation of an AttributeFilterOperation is used for parser input. The resultant output from the instance's String method should be identical to that which was fed into the Parse method. 

af1 := `objectClass:(&(objectClass=employee)(cn=Jesse Coretta))`
af2 := `homeDirectory:(&(objectClass=accountant)(cn=Courtney Tolana))`
want := `add=` + af1 + ` && ` + af2

var afo AttributeFilterOperation
if err := afo.Parse(want); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%s", afo)

Output:

add=objectClass:(&(objectClass=employee)(cn=Jesse Coretta)) && homeDirectory:(&(objectClass=accountant)(cn=Courtney Tolana))

func (AttributeFilterOperation) Pop 

func (r AttributeFilterOperation) Pop() (af AttributeFilter)

Pop wraps go-stackage's Stack.Pop method.

Example

This example demonstrates the use of the AttributeFilterOperation type's Pop method to remove the last stack slice per LIFO ordering. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO := AddOp.AFO(aF1, aF2)

popped := aFO.Pop()

fmt.Printf("%s", popped.AttributeType())

Output:

gecos

func (AttributeFilterOperation) Push 

func (r AttributeFilterOperation) Push(x ...any) AttributeFilterOperation

Push wraps go-stackage's Stack.Push method.

Example

This example demonstrates the use of the AttributeFilterOperation type's Push method to append a new (eligible) instance to the receiver. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

aFO := AddOp.AFO(aF1)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO.Push(aF2)

fmt.Printf("%s", aFO)

Output:

add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern))

func (AttributeFilterOperation) String 

func (r AttributeFilterOperation) String() (s string)

String is a stringer method that returns the string representation of the receiver instance.

Example

This example demonstrates the creation of an instance of AttributeFilterOperation followed by a call of its String method.

The return value is the entirely of the receiver in string representation. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO := AddOp.AFO(aF1, aF2)

fmt.Printf("%s", aFO)

Output:

add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern))

func (AttributeFilterOperation) TRM 

func (r AttributeFilterOperation) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual TargetRuleMethod instance for OPTIONAL use in the creation of a TargetRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var afo AttributeFilterOperation
fmt.Printf("%d available aci.TargetRuleMethod instances", afo.TRM().Len())

Output:

2 available aci.TargetRuleMethod instances

func (AttributeFilterOperation) Valid 

func (r AttributeFilterOperation) Valid() (err error)

Valid wraps go-stackage's Stack.Valid method.

Example

This example demonstrates the creation of an instance of AttributeFilterOperation followed by a call of its Valid method for the purpose of sanity checking the receiver.

No error is reported and printed to STDOUT in this case, as the instance is valid. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF := AF(attr, filter)
aFO := AddOp.AFO(aF)

fmt.Printf("%t", aFO.Valid() == nil)

Output:

true

type AttributeFilterOperations 

type AttributeFilterOperations stackage.Stack

AttributeFilterOperations is a go-stackage Stack alias type, used for the storage of individual AttributeFilterOperation instances.

Instances of this design are used in TargetRule instances which bear the targattrfilters keyword context.

func AFOs 

func AFOs(x ...any) (f AttributeFilterOperations)

AFOs returns a freshly initialized instance of AttributeFilterOperations, configured to store one (1) or more AttributeFilterOperation instances for the purpose of crafting TargetRule instances which bear the `targattrfilters` keyword context.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the AttributeFilterOperation type (or its string equivalent) during initialization. This is merely a more convenient alternative to separate initialization and push procedures.

Instances of this design are not generally needed elsewhere.

Values are automatically joined using stackage.List() with SetDelimiter for comma delimitation by default. See SetDelimiter method if semicolon delimitation is preferred.

Example

This example demonstrates the creation of an instance of AttributeFilterOperations, which is used to store individual AttributeFilterOperation instances.

In this example, proper type instances are fed to the package level AFOs function to form a complete AttributeFilterOperations instance.

The return type, AttributeFilterOperations, is then shown in string representation. 

// define the desired attributeType
// and filter for the first element
attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

// Create the AttributeFilterOperation
// instance (aFO)
aFO := AddOp.AFO(aF1, aF2)

// prepare our AttributeFilterOperations
// instance stack (aFOs) using the AFOs
// package level function.
aFOs := AFOs(aFO)

fmt.Printf("%s", aFOs)

Output:

add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern))

func (AttributeFilterOperations) Compare 

func (r AttributeFilterOperations) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) AttributeFilterOperations instances using the Compare method.

The comparison returns false, as the compared instances are ordered differently. 

attr := AT(`uidNumber`)
filter := Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF1 := AF(attr, filter)
aFO1 := AddOp.AFO(aF1)

attr = AT(`gidNumber`)
filter = Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF2 := AF(attr, filter)
aFO2 := DelOp.AFO(aF2)

// Create the second AttributeFilterOperation
// instance (aFO2)
var afos1 AttributeFilterOperations = AFOs()
afos1.Push(aFO1, aFO2)

var afos2 AttributeFilterOperations = AFOs()
afos2.Push(aFO2, aFO1)

fmt.Printf("Hashes are equal: %t", afos1.Compare(afos2))

Output:

Hashes are equal: false

func (AttributeFilterOperations) Contains 

func (r AttributeFilterOperations) Contains(x any) bool

Contains returns a Boolean value indicative of whether the type and its value were located within the receiver.

Valid input types are AttributeFilterOperation or a valid string equivalent.

Case is significant in the matching process.

Example

This example demonstrates the creation of an instance of AttributeFilterOperations, which is used to store individual AttributeFilterOperation instances.

In this example, proper type instances are fed to the package level AFOs function to form a complete AttributeFilterOperations instance.

The return type, AttributeFilterOperations, is then shown in string representation. 

// define the desired attributeType
// and filter for the first element
attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

// Create the first AttributeFilterOperation
// instance (aFO1)
aFO1 := AddOp.AFO(aF1, aF2)

attr = AT(`uidNumber`)
filter = Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF3 := AF(attr, filter)

attr = AT(`gidNumber`)
filter = Filter(`(objectClass=account)`)
aF4 := AF(attr, filter)

// Create the second AttributeFilterOperation
// instance (aFO2)
aFO2 := DelOp.AFO(aF3, aF4)

// prepare our AttributeFilterOperations
// instance stack (aFOs) using the AFOs
// package level function. Push both of
// the above AFO instances.
aFOs := AFOs(aFO1, aFO2)

fmt.Printf("%t", aFOs.Contains(`delete=uidNumber:(&(objectClass=accounting)(terminated=FALSE)) && gidNumber:(objectClass=account)`))

Output:

true

func (AttributeFilterOperations) Eq 

func (r AttributeFilterOperations) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To a `targattrfilters` keyword context.

Example

This example demonstrates the use of the AttributeFilterOperations type's Eq method, allowing for the creation of a TargetRule instance containing the receiver value, and bearing the `targattrfilters` keyword context. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFO := AddOp.AFO(aF1, aF2)

// all of the above was copied verbatim
// from the AttributeFilterOperation Eq
// example. All we're really doing here
// is enveloping it in another stack
aFOs := AFOs(aFO)

fmt.Printf("%s", aFOs.Eq())

Output:

( targattrfilters = "add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern))" )

func (AttributeFilterOperations) F 

func (r AttributeFilterOperations) F() func(...any) AttributeFilterOperation

F returns the appropriate instance creator function for crafting individual AttributeFilterOperation instances for submission to the receiver. This is merely a convenient alternative to maintaining knowledge as to which function applies to the current receiver instance.

As there is only one possibility for instances of this design, the AFO function is returned.

Example

This example demonstrates the use of the AttributeFilterOperations type's F method, which returns the appropriate slice building function for convenience. 

var aFOs AttributeFilterOperations

// this returns the package-level AFO function
Func := aFOs.F()

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF := Func(attr, filter)
aFO := Func(aF)

fmt.Printf("%T", aFO)

Output:

aci.AttributeFilterOperation

func (AttributeFilterOperations) Index 

func (r AttributeFilterOperations) Index(idx int) (afo AttributeFilterOperation)

Index wraps go-stackage's Stack.Index method. Note that the Boolean OK value returned by go-stackage by default will be shadowed and not obtainable by the caller.

Example

This example demonstrates the use of the AttributeFilterOperations type's Index method to allow iteration of the receiver's contents. 

// define the desired attributeType
// and filter for the first element
attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

// Create the first AttributeFilterOperation
// instance (aFO1)
aFO1 := AddOp.AFO(aF1, aF2)

attr = AT(`uidNumber`)
filter = Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF3 := AF(attr, filter)

attr = AT(`gidNumber`)
filter = Filter(`(objectClass=account)`)
aF4 := AF(attr, filter)

// Create the second AttributeFilterOperation
// instance (aFO2)
aFO2 := DelOp.AFO(aF3, aF4)

// prepare our AttributeFilterOperations
// instance stack (aFOs) using the AFOs
// package level function. Push both of
// the above AFO instances.
aFOs := AFOs(aFO1, aFO2)

slice := aFOs.Index(1)

fmt.Printf("%s", slice)

Output:

delete=uidNumber:(&(objectClass=accounting)(terminated=FALSE)) && gidNumber:(objectClass=account)

func (AttributeFilterOperations) IsZero 

func (r AttributeFilterOperations) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example

This example demonstrates a check of the receiver for "nilness" using the AttributeFilterOperations type's IsZero method. 

var afo AttributeFilterOperations
fmt.Printf("%t", afo.IsZero())

Output:

true

func (AttributeFilterOperations) Keyword 

func (r AttributeFilterOperations) Keyword() Keyword

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned is always TargetFilter.

Example

This example demonstrates the use of the AttributeFilterOperations type's Keyword method. 

var afos AttributeFilterOperations

fmt.Printf("%s", afos.Keyword())

Output:

targattrfilters

func (AttributeFilterOperations) Kind 

func (r AttributeFilterOperations) Kind() string

Kind returns the categorical label assigned to the receiver.

Example

This example demonstrates the use of the AttributeFilterOperations type's Kind method. 

var aFOs AttributeFilterOperations

fmt.Printf("%s", aFOs.Kind())

Output:

targattrfilters

func (AttributeFilterOperations) Len 

func (r AttributeFilterOperations) Len() int

Len wraps go-stackage's Stack.Len method.

Example

This example demonstrates the use of the AttributeFilterOperation type's Len method to report the integer length of the receiver. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFOs := AFOs(AddOp.AFO(aF1, aF2))

fmt.Printf("Length: %d", aFOs.Len())

Output:

Length: 1

func (AttributeFilterOperations) Ne 

func (r AttributeFilterOperations) Ne() TargetRule

Ne performs no useful task, as negated equality comparison does not apply to TargetRule instances that bear the `targattrfilters` keyword context.

This method exists solely to convey this message and conform to Go's interface qualifying signature. When executed, this method will return a bogus TargetRule.

Negated equality TargetRule instances should be used with caution.

Example

This example demonstrates the use of the AttributeFilterOperation type's Ne method, which is not intended to be used in any situation ever. See the comments for this method for details. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
af := AF(attr, filter)
aFO := AddOp.AFO(af)

// all of the above was copied verbatim
// from the AttributeFilterOperation Ne
// example. All we're really doing here
// is enveloping it in another stack
aFOs := AFOs(aFO)
bogus := aFOs.Ne()

fmt.Printf("%t", bogus.IsZero())

Output:

true

func (*AttributeFilterOperations) Parse 

func (r *AttributeFilterOperations) Parse(raw string, delim ...int) (err error)

Parse is a convenient alternative to building the receiver instance using individual instances of the needed types. This method does not use go-antlraci.

An error is returned if the parsing attempt fails for some reason. If successful, the receiver pointer is updated (clobbered) with new information.

Parse will process the input string (raw) and attempt to split the value using a delimiter integer identifier, if specified. See AttributeFilterOperationsCommaDelim (default) and AttributeFilterOperationsSemiDelim const definitions for details.

Example

This example demonstrates the creation of an instance of AttributeFilterOperations using the AttributeFilterOperations type's Parse method.

In this example, a raw string representation of an AttributeFilterOperations is used for parser input. The resultant output from the instance's String method should be identical to that which was fed into the Parse method. 

aftxt := `delete=objectClass:(&(objectClass=employee)(cn=Jesse Coretta)) && homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta))`
var afos AttributeFilterOperations
err := afos.Parse(aftxt)
if err != nil {
	fmt.Println(err) // always check your parser errors
	return
}
got := afos.String()

fmt.Printf("Values match: %t", got == aftxt)

Output:

Values match: true

func (AttributeFilterOperations) Pop 

func (r AttributeFilterOperations) Pop() (afo AttributeFilterOperation)

Pop wraps go-stackage's Stack.Pop method.

Example

This example demonstrates the use of the AttributeFilterOperations type's Pop method to remove the last stack slice per LIFO ordering. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

aFOs := AFOs(DelOp.AFO(aF1, aF2))

popped := aFOs.Pop()

fmt.Printf("%s", popped)

Output:

delete=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern))

func (AttributeFilterOperations) Push 

func (r AttributeFilterOperations) Push(x ...any) AttributeFilterOperations

Push wraps go-stackage's Stack.Push method. This method shall attempt to add the provided input values (x) -- which may contain one (1) or more instances of AttributeFilterOperation or its string equivalent -- to the receiver instance.

Example

This example demonstrates the use of the AttributeFilterOperations type's Push method to append a new (eligible) instance to the receiver. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

var afos AttributeFilterOperations = AFOs()
afos.Push(AddOp.AFO(aF1, aF2))

fmt.Printf("%d", afos.Len())

Output:

1
Example (ByString)

This example demonstrates the use of the AttributeFilterOperations type's Push method to append a new (eligible) instance to the receiver. 

attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

var afos AttributeFilterOperations = AFOs()
ad := AddOp.AFO(aF1, aF2)
afos.Push(ad.String())

fmt.Printf("%d", afos.Index(0).Len())

Output:

2

func (AttributeFilterOperations) SetDelimiter 

func (r AttributeFilterOperations) SetDelimiter(i ...int) AttributeFilterOperations

SetDelimiter controls the delimitation scheme employed by the receiver.

Some vendors use semicolon (ASCII #59) for delimitation for expressions that include values of this kind. This alternative scheme can be set using the AttributeFilterOperationsSemiDelim integer constant (1).

Other vendors use a comma (ASCII #44) for delimitation of the same form of expression. This delimitation scheme represents the default (most common) behavior, but can be set using the AttributeFilterOperationsCommaDelim integer constant (0), or when run in niladic fashion.

Example 
// define the desired attributeType
// and filter for the first element
attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

// Create the first AttributeFilterOperation
// instance (aFO1)
aFO1 := AddOp.AFO(aF1, aF2)

attr = AT(`uidNumber`)
filter = Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF3 := AF(attr, filter)

attr = AT(`gidNumber`)
filter = Filter(`(objectClass=account)`)
aF4 := AF(attr, filter)

// Create the second AttributeFilterOperation
// instance (aFO2)
aFO2 := DelOp.AFO(aF3, aF4)

// prepare our AttributeFilterOperations
// instance stack (aFOs) using the AFOs
// package level function. Push both of
// the above AFO instances, and set a
// delimiter other than the default...
delimiter := AttributeFilterOperationsSemiDelim

aFOs := AFOs(aFO1, aFO2).SetDelimiter(delimiter)
fmt.Printf("%s", aFOs)

Output:

add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern));delete=uidNumber:(&(objectClass=accounting)(terminated=FALSE)) && gidNumber:(objectClass=account)

func (AttributeFilterOperations) String 

func (r AttributeFilterOperations) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example 
// define the desired attributeType
// and filter for the first element
attr := AT(`homeDirectory`)
filter := Filter(`(&(objectClass=employee)(cn=Jesse Coretta))`)
aF1 := AF(attr, filter)

attr = AT(`gecos`)
filter = Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF2 := AF(attr, filter)

// Create the first AttributeFilterOperation
// instance (aFO1)
aFO1 := AddOp.AFO(aF1, aF2)

attr = AT(`uidNumber`)
filter = Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF3 := AF(attr, filter)

attr = AT(`gidNumber`)
filter = Filter(`(objectClass=account)`)
aF4 := AF(attr, filter)

// Create the second AttributeFilterOperation
// instance (aFO2)
aFO2 := DelOp.AFO(aF3, aF4)

// prepare our AttributeFilterOperations
// instance stack (aFOs) using the AFOs
// package level function. Push both of
// the above AFO instances

aFOs := AFOs(aFO1, aFO2)
fmt.Printf("%s", aFOs)

Output:

add=homeDirectory:(&(objectClass=employee)(cn=Jesse Coretta)) && gecos:(|(objectClass=contractor)(objectClass=intern)),delete=uidNumber:(&(objectClass=accounting)(terminated=FALSE)) && gidNumber:(objectClass=account)

func (AttributeFilterOperations) TRM 

func (r AttributeFilterOperations) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual TargetRuleMethod instance for OPTIONAL use in the creation of a TargetRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var afos AttributeFilterOperations
fmt.Printf("%d available aci.TargetRuleMethod instances", afos.TRM().Len())

Output:

2 available aci.TargetRuleMethod instances

func (AttributeFilterOperations) Valid 

func (r AttributeFilterOperations) Valid() error

Valid wraps go-stackage's Stack.Valid method.

Example

This example demonstrates the creation of an instance of AttributeFilterOperations followed by a call of its Valid method for the purpose of sanity checking the receiver. 

attr := AT(`uidNumber`)
filter := Filter(`(&(objectClass=accounting)(terminated=FALSE))`)
aF1 := AF(attr, filter)

attr = AT(`gidNumber`)
filter = Filter(`(objectClass=account)`)
aF2 := AF(attr, filter)

// Create the second AttributeFilterOperation
// instance (aFO2)
var afos AttributeFilterOperations = AFOs()
afos.Push(DelOp.AFO(aF1, aF2))

fmt.Printf("Valid: %t", afos.Valid() == nil)

Output:

Valid: true

type AttributeOperation 

type AttributeOperation uint8

AttributeOperation defines either an Add Operation or a Delete Operation.

Constants of this type are used in AttributeFilters instances. 

const (
	AddOp AttributeOperation // add=
	DelOp                    // delete=
)

AttributeOperation constants are used to initialize and return AttributeFilters instances based on one (1) of the possible two (2) constants defined below.

func (AttributeOperation) AFO 

func (r AttributeOperation) AFO(x ...any) (afo AttributeFilterOperation)

AFO returns an instance of AttributeFilterOperation based upon the input AttributeFilter instances.

The instance of AttributeFilterOperation contains an ANDed Rule instance using symbols (`&&`).

Example

This example demonstrates the creation of an instance of AttributeFilterOperation, which is strictly intended for use within instances of AttributeFilterOperations.

In this example, proper type instances are fed to the AttributeOperation AFO method to form a complete AttributeFilterOperation instance.

The return type, AttributeFilterOperation, has its type shown in text, along with the current stack length. 

attr := AT(`gecos`)
filter := Filter(`(|(objectClass=contractor)(objectClass=intern))`)
aF := AF(attr, filter)

// Create the first AttributeFilterOperation
// instance (aFO1)
aFO := AddOp.AFO(aF)

fmt.Printf("%T [len:%d]", aFO, aFO.Len())

Output:

aci.AttributeFilterOperation [len:1]

func (AttributeOperation) String 

func (r AttributeOperation) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example

This example demonstrates the string representation of an AttributeOperation constant.

In this example, the instance is shown in string representation. 

fmt.Printf("%s and %s", AddOp, DelOp)

Output:

add and delete

type AttributeType 

type AttributeType struct {
	// contains filtered or unexported fields
}

AttributeType embeds a pointer value that reflects a single AttributeType name such as `manager` or `cn`.

func AT 

func AT(x string) (A AttributeType)

AT initializes, sets and returns an AT instance in one shot. The input value x shall be a string attributeType name (e.g.: `manager`).

Example

This example demonstrates the creation of an instance of AttributeType, which is used in a variety of contexts.

In this example, a string name is fed to the package level AT function to form a complete AttributeType instance, which is then shown in string representation. 

atb := AT(`homeDirectory`)
fmt.Printf("%s", atb)

Output:

homeDirectory

func (AttributeType) Compare 

func (r AttributeType) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) AttributeType instances using the Compare method. 

attr := AT(`cACertificate`)
oattr := AT(`cacertificate`)

fmt.Printf("Hashes are equal: %t", oattr.Compare(attr))

Output:

Hashes are equal: false

func (AttributeType) Eq 

func (r AttributeType) Eq() (t TargetRule)

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To a `targetattr` keyword context.

Example

This example demonstrates the creation of an equality TargetRule (targetattr) using the receiver instance as input: 

attr := AT(`*`)
fmt.Printf("%s", attr.Eq())

Output:

( targetattr = "*" )

func (AttributeType) IsZero 

func (r AttributeType) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example

This example demonstrates a check of the receiver for "nilness". 

fmt.Printf("%t", AT(`owner`).IsZero())

Output:

false

func (AttributeType) Keyword 

func (r AttributeType) Keyword() Keyword

Keyword performs no useful task, as the receiver instance has no concept of a keyword. This method exists solely to satisfy Go's interface signature requirements and will return nil if executed.

Example

This example demonstrates the use of the useless Keyword method, as AttributeType instances do not have any knowledge of Keywords at this time. 

fmt.Printf("%v", AT(`owner`).Keyword())

Output:

<nil>

func (AttributeType) Kind 

func (r AttributeType) Kind() string

Kind performs no useful task, as the receiver instance has no concept of a keyword, which is the typical value source for Kind calls. This method exists solely to satisfy Go's interface signature requirements and will return a zero string if executed.

Example

This example demonstrates the use of the useless Kind method, as this information is normally derived from a Keyword, which the receiver does not have. 

fmt.Printf("'%s'", AT(`owner`).Kind())

Output:

''

func (AttributeType) Len 

func (r AttributeType) Len() int

Len returns 0 or 1 to describe an abstract length of the receiver. This method exists only to satisfy Go's interface signature requirements and need not be used.

Example

This example demonstrates the use of the useless Len method, as this information is only made available to satisfy Go's interface signature requirements as they pertain to the AttributeTypeContext interface. 

fmt.Printf("%d", AT(`owner`).Len())

Output:

1

func (AttributeType) Ne 

func (r AttributeType) Ne() (t TargetRule)

Ne initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Not-Equal-To a `targetattr` keyword context.

Negated equality TargetRule instances should be used with caution.

Example

This example demonstrates the creation of a negated equality TargetRule (targetattr) using the receiver instance as input: 

attr := AT(`aci`)
fmt.Printf("%s", attr.Ne())

Output:

( targetattr != "aci" )

func (AttributeType) String 

func (r AttributeType) String() (s string)

String returns the string representation of the underlying value within the receiver. The return value shall reflect an attributeType name, such as `manager` or `cn`.

Example

This example demonstrates the string representation of the receiver instance. 

fmt.Printf("%s", AT(`owner`))

Output:

owner

func (AttributeType) TRM 

func (r AttributeType) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual TargetRuleMethod instance for OPTIONAL use in the creation of a TargetRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly initialized, populated and prepared for such activity.

Example

This example demonstrates how a caller can determine the number of comparison operator methods are available for use by the receiver instance. 

var at AttributeType
fmt.Printf("%d available aci.BindRuleMethod instances", at.TRM().Len())

Output:

2 available aci.BindRuleMethod instances

func (AttributeType) Valid 

func (r AttributeType) Valid() error

Valid returns an instance of error describing the aberrant state of the receiver, if applicable. At the moment, this method merely verifies nilness, as the AttributeType type defined within this package is extremely one dimensional, and lacks any significant mechanics for extended scrutiny.

Example

This example demonstrates a check of the receiver for an aberrant state. 

fmt.Printf("Valid: %t", AT(`owner`).Valid() == nil)

Output:

Valid: true

type AttributeTypeContext 

type AttributeTypeContext interface {
	Len() int
	String() string
	Kind() string
	Keyword() Keyword
	IsZero() bool
	Valid() error
	// contains filtered or unexported methods
}

AttributeTypeContext is a convenient interface type that is qualified by the following types:

• AttributeType

• AttributeTypes

The qualifying methods shown below are intended to make the generalized handling of attributeTypes slightly easier without an absolute need for type assertion at every step.

These methods are inherently read-only in nature.

To alter the underlying value, or to gain access to all of a given type's methods, type assertion of qualifying instances shall be necessary.

type AttributeTypes 

type AttributeTypes stackage.Stack

AttributeTypes is an alias type for stackage.Stack, and is intended to house one (1) or more AttributeType instances for the purpose of expression within a BindRule or TargetRule instance.

Example (TargetAttributes)

This example demonstrates the creation of an AttributeTypes instance suitable for use in the assembly of a TargetRule bearing the `targetattr` keyword context. 

// the TAs function allows AttributeType
// instances in string representation, or
// cast as proper AttributeType instances.
//
// Ordering is always preserved.
attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
	AT(`l`),
)

fmt.Printf("%s", attrs.Eq())

Output:

( targetattr = "cn || givenName || sn || objectClass || l" )
Example (URIAttributes)

This example demonstrates the creation of an AttributeTypes instance suitable for use in an LDAPURI instance. 

// the UAs function allows AttributeType
// instances in string representation, or
// cast as proper AttributeType instances.
//
//
// Ordering is always preserved.
attrs := UAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
	AT(`l`),
)

fmt.Printf("%s", attrs)

Output:

cn,givenName,sn,objectClass,l

func TAs 

func TAs(x ...any) (a AttributeTypes)

TAs returns a freshly initialized instance of AttributeTypes, configured to store one (1) or more AttributeType instances for the purpose of TargetRule expression when using the `targetattr` keyword context.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the AttributeType type (or its string equivalent) during initialization. This is merely a more convenient alternative to separate initialization and push procedures.

Values are automatically delimited using stackage.Stack's Symbol method using the symbolic OR operator (`||`).

Example

This example demonstrates how to create a Target Attributes Rule using a list of AttributeType instances. 

attrs := TAs().Push(
	AT(`cn`),
	AT(`sn`),
	AT(`givenName`),
)
fmt.Printf("%s", attrs)

Output:

cn || sn || givenName

func UAs 

func UAs(x ...any) (a AttributeTypes)

UAs returns a freshly initialized instance of AttributeTypes, configured to store one (1) or more AttributeType instances for the purpose of LDAP Search URI specification of desired AttributeType names. Instances of this design are not generally needed elsewhere.

Optionally, the caller may choose to push one (1) or more (valid) instances of the AttributeType type (or its string equivalent) during initialization. This is merely a more convenient alternative to separate initialization and push procedures.

Values are automatically comma-delimited (ASCII #44) using stackage.Stack's SetDelimiter method in List mode.

func (AttributeTypes) Compare 

func (r AttributeTypes) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example (LikeInstances)

This example demonstrates a basic SHA-1 hash comparison between two like instances of the receiver's type. 

attrs1 := TAs(`cn`, `givenName`, `sn`, `objectClass`, `l`)
attrs2 := TAs(`cn`, `givenName`, `sn`, `objectClass`, `l`)

fmt.Printf("%T instances match: %t", attrs1, attrs1.Compare(attrs2))

Output:

aci.AttributeTypes instances match: true
Example (MultiValueFalse)

This example demonstrates why two seemingly identical instances, though created by separate functions, fail to evaluate as equal when multi-valued. The reason for this is due to the nature of the String method behavior for each of the instances. Use of the TAs package level function guarantees a delimitation scheme using the symbolic OR (||) symbol, while use of the UAs package level function uses comma-delimitation. 

attrs1 := TAs(`cn`, `givenName`, `sn`, `objectClass`, `l`) // <x> || <x> || ...
attrs2 := UAs(`cn`, `givenName`, `sn`, `objectClass`, `l`) // x,x,x ...

fmt.Printf("%T instances match: %t", attrs1, attrs1.Compare(attrs2))

Output:

aci.AttributeTypes instances match: false
Example (SingleValueTrue)

This example demonstrates the contrary condition to that demonstrated in the AttributeTypes CompareMultiValueFalse example. Because the two instances to be evaluated are single-valued, no delimiter scheme comes into play. As such, the two instances produce identical String output. 

attrs1 := TAs(`cn`)
attrs2 := UAs(`cn`)

fmt.Printf("%T instances match: %t", attrs1, attrs1.Compare(attrs2))

Output:

aci.AttributeTypes instances match: true

func (AttributeTypes) Contains 

func (r AttributeTypes) Contains(x any) bool

Contains returns a Boolean value indicative of whether value x, if a string or AttributeType instance, already resides within the receiver instance.

Case is not significant in the matching process.

Example 
attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
	AT(`l`),
)

fmt.Printf("Contains 'l': %t", attrs.Contains(`l`))

Output:

Contains 'l': true

func (AttributeTypes) Eq 

func (r AttributeTypes) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To a `targetattr` keyword context.

Example 
attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
	AT(`l`),
)

fmt.Printf("%s", attrs.Eq())

Output:

( targetattr = "cn || givenName || sn || objectClass || l" )
Example (TargetAttributes)

This example demonstrates how to create a Target Attributes Rule Equality Condition using a list of AttributeType instances. 

attrs := TAs().Push(
	AT(`cn`),
	AT(`sn`),
	AT(`givenName`),
)
fmt.Printf("%s", attrs.Eq())

Output:

( targetattr = "cn || sn || givenName" )

func (AttributeTypes) F 

func (r AttributeTypes) F() func(string) AttributeType

F returns the appropriate instance creator function for crafting individual AttributeType instances for submission to the receiver. This is merely a convenient alternative to maintaining knowledge as to which function applies to the current receiver instance.

As there is only one possibility for instances of this design, the AT function is returned.

Example 
attrs := TAs(
	`l`,
	`cn`,
	`sn`,
	`givenName`,
	`objectClass`,
)

attr := attrs.F()(`homeDirectory`) // We've just executed 'AT' function without having to find it.
fmt.Printf("attr is %T", attr)

Output:

attr is aci.AttributeType

func (AttributeTypes) Index 

func (r AttributeTypes) Index(idx int) (x AttributeType)

Index wraps go-stackage's Stack.Index method. Note that the Boolean OK value returned by go-stackage by default will be shadowed and not obtainable by the caller.

Example 
attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
	AT(`l`),
)

fmt.Printf("%s", attrs.Index(2))

Output:

sn

func (AttributeTypes) IsZero 

func (r AttributeTypes) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example 
fmt.Printf("Empty stack: %t", TAs(`cn`, `sn`, `uid`).IsZero())

Output:

Empty stack: false

func (AttributeTypes) Keyword 

func (r AttributeTypes) Keyword() Keyword

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned shall be either TargetAttr or TargetFilter.

Example (TargetAttributes) 
attrs := TAs(
	`l`,
	`cn`,
	`sn`,
	`givenName`,
	`objectClass`,
)

fmt.Printf("%s", attrs.Keyword())

Output:

targetattr
Example (URIAttributes)

This example demonstrates the incompatibility with an AttributeTypes stack intended for use within an LDAPURI instance. Because this incarnation of AttributeTypes has no direct application within a BindRule or a TargetRule (rather it resides WITHIN another type eligible for such use), the Keyword cannot be inferred and returns a nil instance. This is expected behavior. 

attrs := UAs(
	`l`,
	`cn`,
	`sn`,
	`givenName`,
	`objectClass`,
)

fmt.Printf("Keyword: %s", attrs.Keyword())

Output:

Keyword: targetfilter

func (AttributeTypes) Kind 

func (r AttributeTypes) Kind() string

Kind wraps go-stackage's Stack.Category method for the purpose of identifying the context of the receiver instance.

Example (TargetAttributes) 
attrs := TAs(
	`l`,
	`cn`,
	`sn`,
	`givenName`,
	`objectClass`,
)

fmt.Printf("%s", attrs.Kind())

Output:

targetattr
Example (URIAttributes) 
attrs := UAs(
	`l`,
	`cn`,
	`sn`,
	`givenName`,
	`objectClass`,
)

fmt.Printf("%s", attrs.Kind())

Output:

<uri_search_attributes>
Example (Uninitialized) 
var attrs AttributeTypes
fmt.Printf("%s", attrs.Kind())

Output:

<uninitialized>

func (AttributeTypes) Len 

func (r AttributeTypes) Len() int

Len wraps go-stackage's Stack.Len method.

Example 
fmt.Printf("%d attributeTypes", TAs(`cn`, `sn`, `uid`).Len())

Output:

3 attributeTypes

func (AttributeTypes) Ne 

func (r AttributeTypes) Ne() TargetRule

Ne initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Not-Equal-To a `targetattr` keyword context.

Negated equality TargetRule instances should be used with caution.

Example 
fmt.Printf("%s", TAs(AT(`aci`)).Ne())

Output:

( targetattr != "aci" )

func (AttributeTypes) Pop 

func (r AttributeTypes) Pop() (x AttributeType)

Pop wraps go-stackage's Stack.Pop method.

Example

This example demonstrates the removal of a single slice element from an AttributeTypes instance in LIFO fashion using its Pop method. 

attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
	`l`,
)
popped := attrs.Pop()

fmt.Printf("%s", popped)

Output:

l

func (AttributeTypes) Push 

func (r AttributeTypes) Push(x ...any) AttributeTypes

Push wraps go-stackage's Stack.Push method. Valid input types are string and AttributeType. In the case of a string value, it is automatically cast as an instance of AttributeType, so long as the raw string is of a non-zero length.

Example

This example demonstrates the addition of new slice elements to an AttributeTypes instance using its Push method. 

attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
)
attrs.Push(`l`)

fmt.Printf("%s", attrs)

Output:

cn || givenName || sn || objectClass || l

func (AttributeTypes) String 

func (r AttributeTypes) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example

This example demonstrates the string representation of the receiver instance using its String method. 

attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
)

fmt.Printf("%s", attrs)

Output:

cn || givenName || sn || objectClass

func (AttributeTypes) TRM 

func (r AttributeTypes) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual TargetRuleMethod instance for OPTIONAL use in the creation of a TargetRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example (TargetAttributes)

This example demonstrates the use of the receiver's TRM method in order to determine available comparison operator driven methods available in this context. 

attrs := TAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
)

fmt.Printf("%d available comparison operator methods", attrs.TRM().Len())

Output:

2 available comparison operator methods
Example (URIAttributes)

This example demonstrates the useless nature of the receiver's TRM method in situations where the receiver is intended for use within an LDAPURI instance, rather than as a rule condition unto itself. As a result, a bogus TargetRuleMethods instance will be returned if the receiver was created through any means *OTHER THAN* by execution of the TAs package level function. 

attrs := UAs(
	`cn`,
	AT(`givenName`),
	`sn`,
	`objectClass`,
)

fmt.Printf("%d available comparison operator methods", attrs.TRM().Len())

Output:

0 available comparison operator methods

func (AttributeTypes) Valid 

func (r AttributeTypes) Valid() (err error)

Valid returns an instance of error in the event the receiver is in an aberrant state.

Example 
fmt.Printf("Empty stack: %t", TAs(`cn`, `sn`, `uid`).Valid() == nil)

Output:

Empty stack: true

type AttributeValue 

type AttributeValue struct {
	// contains filtered or unexported fields
}

AttributeValue embeds a pointer value that reflects an attributeType assertion value.

Example 
attr := AT(`homeDirectory`)
value := AV(`/home/jesse`)

fmt.Printf("My %s is '%s'", attr, value)

Output:

My homeDirectory is '/home/jesse'

func AV 

func AV(x string) (A AttributeValue)

AV initializes, sets and returns an AttributeValue instance in one shot. The input value x shall be a known BindType constant, such as USERDN, OR a raw string attributeType value, such as `uid=bob,ou=People,dc=example,dc=com`.

Example 
attr := AT(`homeDirectory`)
value := AV(`/home/jesse`)

fmt.Printf("My %s is '%s'", attr, value)

Output:

My homeDirectory is '/home/jesse'

func (AttributeValue) Compare 

func (r AttributeValue) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates a SHA-1 hash comparison between the receiver and a test value. Note that the SHA-1 comparison is driven by the type instance's stringer output for simplicity in this package. 

var (
	// granted, password values aren't an ACIv3 thing in
	// this context, but its still a fair example ...
	myPassword    AttributeValue = AV(`ALAA¢<ý²áßNß%a.)_ÿ3÷`)
	notMyPassword AttributeValue = AV(`ALAA¢<ýªáßNß%a.)_ÿ3÷`)
)

fmt.Printf("These passwords match: %t", myPassword.Compare(notMyPassword))

Output:

These passwords match: false

func (AttributeValue) String 

func (r AttributeValue) String() (s string)

String returns the string representation of the underlying value within the receiver. The return value should be either an attributeType assertion value, or one (1) of the five (5) possible BindType identifiers (e.g.: USERDN).

Example 
attr := AT(`homeDirectory`)
value := AV(`/home/jesse`)

fmt.Printf("My %s is '%s'", attr, value)

Output:

My homeDirectory is '/home/jesse'

type AuthenticationMethod 

type AuthenticationMethod uint8

AuthenticationMethod is a uint8 type that manifests through predefined package constants, each describing a supported means of LDAP authentication. 

const (
	Anonymous AuthenticationMethod // 0
	Simple                         // 1
	SSL                            // 2
	SASL                           // 3
	EXTERNAL                       // 4
	DIGESTMD5                      // 5
	GSSAPI                         // 6
)

AuthenticationMethod contants define the available LDAP authentication mechanisms that are recognized within the ACI syntax honored by this package.

NOTE: Supported SASL mechanisms vary per impl.

func (AuthenticationMethod) BRM 

func (r AuthenticationMethod) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
meths := Anonymous.BRM()
fmt.Printf("%d available aci.BindRuleMethod instances", meths.Len())

Output:

2 available aci.BindRuleMethod instances

func (AuthenticationMethod) Compare 

func (r AuthenticationMethod) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) AuthenticationMethod instances using the Compare method. 

fmt.Printf("%t", Anonymous.Compare(EXTERNAL))

Output:

false

func (AuthenticationMethod) Eq 

func (r AuthenticationMethod) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To the `authmethod` Bind keyword context.

Example 
fmt.Printf("%s", SASL.Eq())

Output:

authmethod = "SASL"

func (AuthenticationMethod) Ne 

func (r AuthenticationMethod) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To the `authmethod` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example 
fmt.Printf("%s", Anonymous.Ne())

Output:

authmethod != "NONE"

func (AuthenticationMethod) String 

func (r AuthenticationMethod) String() (am string)

String is a stringer method that returns the string representation of the receiver instance.

Example 
fmt.Printf("%s", EXTERNAL)

Output:

SASL EXTERNAL

type BindContext 

type BindContext interface {
	// String returns the string representation of the
	// receiver instance.
	String() string

	// Keyword returns the BindKeyword, enveloped as a
	// Keyword interface value. If the receiver is an
	// instance of BindRule, the value is derived from
	// the Keyword method. If the receiver is an instance
	// of BindRules, the value is derived (and resolved)
	// using the Category method.
	Keyword() Keyword

	// IsZero returns a Boolean value indicative of the
	// receiver instance being nil, or unset.
	IsZero() bool

	// IsParen returns a Boolean value indicative of
	// whether the receiver is parenthetical.
	IsParen() bool

	// Len returns the integer length of the receiver.
	// Only meaningful when run on BindRules instances.
	Len() int

	// IsNesting returns a Boolean value indicative of
	// whether the receiver contains a stack as a value.
	// Only meaningful when run on BindRules instances.
	IsNesting() bool

	// Index returns the Nth slice from the receiver.
	// This method is only meaningful if the underlying
	// instance is BindRules.
	Index(int) BindContext

	// Traverse will walk a structure of BindContext
	// instances using a sequence of index integers.
	// An instance of BindContext is returned, or nil.
	Traverse(...int) BindContext

	// Valid returns an error instance that indicates
	// whether the receiver is in an aberrant state.
	Valid() error

	// ID will report `bind` in all scenarios.
	ID() string

	// Category will report the logical state of a BindRules
	// instance. This will read `and`, `or`, `not`. For an
	// instance of BindRule, however, it will return the string
	// form of the Keyword, if set, else a zero string.
	Category() string

	// Kind will report `stack` for a BindRules instance, or
	// `condition` for a BindRule instance
	Kind() string
	// contains filtered or unexported methods
}

BindContext is a convenient interface type that is qualified by the following types:

• BindRule

• BindRules

The qualifying methods shown below are intended to make the handling of a structure of (likely nested) BindRules instances slightly easier without an absolute need for type assertion at every step. These methods are inherently read-only in nature and represent only a subset of the available methods exported by the underlying qualifier types.

To alter the underlying value, or to gain access to all of a given type's methods, type assertion of qualifying instances shall be necessary.

func ParseBindRules 

func ParseBindRules(raw string) (BindContext, error)

ParseBindRules returns an instance of BindContext alongside an error instance. BindContext may represent either a BindRule or BindRules instance, depending on that which was parsed.

type BindDistinguishedName 

type BindDistinguishedName struct {
	// contains filtered or unexported fields
}

BindDistinguishedName describes a single LDAP distinguished name. For example: 

ou=People,dc=example,dc=com

For efficiency reasons, the LDAP "local scheme" prefix (ldap:///) is not stored in literal form within any DistinguishedName instance, however it will appear during string representation operations, e.g.: 

ldap:///ou=People,dc=example,dc=com

Instances of this kind can be crafted using the DN package-level function with the appropriate Bind keyword as the input argument:

• DN(<dn>, BindUDN) for a `userdn` Distinguished Name

• DN(<dn>, BindGDN) for a `groupdn` Distinguished Name

• DN(<dn>, BindRDN) for a `roledn` Distinguished Name

In order to fashion multi-valued BindRule instances using instances of this type, they must reside within an appropriate stack type instance. See the BindDistinguishedNames and TargetDistinguishedNames types for details. 

var (
	// LocalScheme is the localhost-implicit scheme prefix for a DN. For security
	// reasons, the LDAP scheme should never be non-local within the context of an
	// ACI (even if proxy operations are involved). For instance:
	//
	//   ldap://ldap.example.com/ou=People,dc=example,dc=com??one?(objectClass=*) // BAD
	//
	//   ldap:///ou=People,dc=example,dc=com??one?(objectClass=*) // GOOD
	//
	// This constant is automatically used in any request related to the string
	// representation of DistinguishedName instances. It is exported and visible
	// to users for reference purposes only, and generally need not be accessed
	// directly.
	LocalScheme = `ldap:///`

	// AllDN is the BindRule abstraction of all *known user* DNs; this does not imply ANONYMOUS DNs
	AllDN BindDistinguishedName

	// AnyDN is the BindRule abstraction of all user DNs, known or anonymous
	AnyDN BindDistinguishedName

	// SelfDN is the BindRule abstraction of a user's own DN
	SelfDN BindDistinguishedName

	// ParentDN is the BindRule abstraction of a user's superior DN
	ParentDN BindDistinguishedName
)

Commonly-used distinguished name expression preambles.

func GDN 

func GDN(x string) BindDistinguishedName

GDN initializes, sets and returns an instance of DistinguishedName in one shot.

An LDAP distinguished name, in string form and WITHOUT the leading `ldap:///` scheme, is required.

The return value shall be suitable for use in creating a Bind Rule Condition that bears the `groupdn` keyword.

Example 
dn := GDN(`cn=Executives,ou=Groups,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///cn=Executives,ou=Groups,dc=example,dc=com

func RDN 

func RDN(x string) BindDistinguishedName

RDN initializes, sets and returns an instance of DistinguishedName in one shot.

An LDAP distinguished name, in string form and WITHOUT the leading `ldap:///` scheme, is required.

The return value shall be suitable for use in creating a Bind Rule Condition that bears the `roledn` keyword.

Example 
dn := RDN(`cn=Role Profile,ou=Roles,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///cn=Role Profile,ou=Roles,dc=example,dc=com

func UDN 

func UDN(x string) BindDistinguishedName

UDN initializes, sets and returns an instance of DistinguishedName in one shot.

An LDAP distinguished name, in string form and WITHOUT the leading `ldap:///` scheme, is required.

The return value shall be suitable for use in creating a Bind Rule Condition that bears the `userdn` keyword.

Example 
dn := UDN(`cn=Jesse Coretta,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///cn=Jesse Coretta,ou=People,dc=example,dc=com

func (BindDistinguishedName) BRM 

func (r BindDistinguishedName) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var dn BindDistinguishedName
fmt.Printf("%d available comparison operator methods", dn.BRM().Len())

Output:

2 available comparison operator methods

func (BindDistinguishedName) Compare 

func (r BindDistinguishedName) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) instances of BindDistinguishedName using the Compare method.

These seemingly different distinguished names actually evaluate as equal because the local LDAP prefix (ldap:///) is stripped off when the UDN (or similar) function is run. When the String method is executed for a distinguished name at a later point, said prefix is artificially imposed. Therefore in this scenario, the two values are in fact equal. 

dn1 := UDN(`uid=jesse,ou=People,dc=example,dc=com`)
dn2 := UDN(`ldap:///uid=jesse,ou=People,dc=example,dc=com`)

fmt.Printf("Hashes are equal: %t", dn1.Compare(dn2))

Output:

Hashes are equal: true

func (BindDistinguishedName) Eq 

func (r BindDistinguishedName) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To one (1) of the following keyword contexts:

• `userdn`

• `groupdn`

• `roledn`

Example 
var dn BindDistinguishedName = UDN(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn.Eq())

Output:

userdn = "ldap:///uid=jesse,ou=People,dc=example,dc=com"

func (BindDistinguishedName) IsZero 

func (r BindDistinguishedName) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is considered nil, or unset.

Example 
var dn BindDistinguishedName
fmt.Printf("Zero: %t", dn.IsZero())

Output:

Zero: true

func (BindDistinguishedName) Keyword 

func (r BindDistinguishedName) Keyword() Keyword

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a BindRule bearing the receiver as a condition value.

Example 
var dn BindDistinguishedName = UDN(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("Keyword: %s", dn.Keyword())

Output:

Keyword: userdn

func (BindDistinguishedName) Kind 

func (r BindDistinguishedName) Kind() string

Kind returns the string name `bind`.

Example 
var dn BindDistinguishedName = UDN(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("Kind: %s", dn.Kind())

Output:

Kind: bind

func (BindDistinguishedName) Len 

func (r BindDistinguishedName) Len() int

Len returns 0 or 1 to describe an abstract length of the receiver. This method exists only to satisfy Go's interface signature requirements and need not be used for any legitimate operation.

A length of zero (0) is returned if the receiver is uninitialized or invalid in some way. A length of one (1) is returned otherwise.

Example 
var dn BindDistinguishedName = UDN(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("Length %d", dn.Len())

Output:

Length 1

func (BindDistinguishedName) Ne 

func (r BindDistinguishedName) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To one (1) of the following keyword contexts:

• `userdn`

• `groupdn`

• `roledn`

Negated equality BindRule instances should be used with caution.

Example 
var dn BindDistinguishedName = UDN(`uid=courtney,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn.Ne())

Output:

userdn != "ldap:///uid=courtney,ou=People,dc=example,dc=com"

func (*BindDistinguishedName) Set 

func (r *BindDistinguishedName) Set(x string, kw ...BindKeyword) BindDistinguishedName

Set assigns value x to the receiver to represent an LDAP distinguished name in the context of a BindRule.

This method presents an opportunity for setting a DN at a later point versus doing so during the initialization process alone and is totally optional.

If no keyword is specified, the userdn keyword context is supplied automatically, which may or may not be what the caller wants.

Example 
var dn BindDistinguishedName
dn.Set(`cn=Role Profile,ou=Roles,dc=example,dc=com`, BindRDN)
fmt.Printf("%s", dn.Eq())

Output:

roledn = "ldap:///cn=Role Profile,ou=Roles,dc=example,dc=com"

func (BindDistinguishedName) String 

func (r BindDistinguishedName) String() string

String is a stringer method that returns the string representation of the receiver instance.

The Local LDAP scheme (ldap:///) is automatically imposed during the string representation of the value; this is required by the ACIv3 syntax.

Example 
var dn BindDistinguishedName = UDN(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com

func (BindDistinguishedName) Valid 

func (r BindDistinguishedName) Valid() (err error)

Valid returns an instance of error that reflects whether certain required elements or value combinations were present and deemed valid. A non-nil error indicates an undesirable receiver state.

Example 
var dn BindDistinguishedName
fmt.Printf("Valid: %t", dn.Valid() == nil)

Output:

Valid: false

type BindDistinguishedNames 

type BindDistinguishedNames stackage.Stack

BindDistinguishedNames is an alias type for stackage.Stack, and is intended to house one (1) or more BindDistinguishedName instances for the purpose of expression within a BindRule instance.

func GDNs 

func GDNs(x ...any) (d BindDistinguishedNames)

GDNs returns a new instance of BindDistinguishedNames with an initialized embedded stack configured to function as a simple ORed list containing a single level of LDAP distinguished names. The BindGDN (groupdn) keyword is automatically assigned to the return value.

Only valid instances of BindDistinguishedName which bear the BindGDN keyword are to be considered eligible for push requests. If the input value is a string, it will be accepted and properly branded with the keyword.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the BindDistinguishedName type (or its string equivalent) for push during initialization. This is merely a more convenient alternative to separate init and push procedures.

See also the UDNs and RDNs functions for BindUDN and BindRDN keywords respectively.

Example 
gdns := GDNs(
	`uid=Executives,ou=Groups,dc=example,dc=com`,
	`uid=Executive Assistants,ou=Groups,dc=example,dc=com`,
)
fmt.Printf("%s", gdns)

Output:

ldap:///uid=Executives,ou=Groups,dc=example,dc=com || ldap:///uid=Executive Assistants,ou=Groups,dc=example,dc=com

func RDNs 

func RDNs(x ...any) (d BindDistinguishedNames)

RDNs returns a new instance of BindDistinguishedNames with an initialized embedded stack configured to function as a simple ORed list containing a single level of LDAP distinguished names. The BindRDN (roledn) keyword is automatically assigned to the return value.

Only valid instances of BindDistinguishedName which bear the BindRDN keyword are to be considered eligible for push requests. If the input value is a string, it will be accepted and properly branded with the keyword.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the BindDistinguishedName type (or its string equivalent) for push during initialization. This is merely a more convenient alternative to separate init and push procedures.

See also the UDNs and GDNs functions for BindUDN and BindGDN keywords respectively.

Example 
rdns := RDNs(
	`cn=Default,ou=Profiles,dc=example,dc=com`,
	`cn=Administrative,ou=Profiles,dc=example,dc=com`,
)
fmt.Printf("%d", rdns.Len())

Output:

2

func UDNs 

func UDNs(x ...any) (d BindDistinguishedNames)

UDNs returns a new instance of BindDistinguishedNames with an initialized embedded stack configured to function as a simple ORed list containing a single level of LDAP distinguished names. The BindUDN (userdn) keyword is automatically assigned to the return value.

Only valid instances of BindDistinguishedName which bear the BindUDN keyword are to be considered eligible for push requests. If the input value is a string, it will be accepted and properly branded with the keyword.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the BindDistinguishedName type (or its string equivalent) for push during initialization. This is merely a more convenient alternative to separate init and push procedures.

See also the RDNs and GDNs functions for BindRDN and BindGDN keywords respectively.

Example 
udns := UDNs(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=courtney,ou=People,dc=example,dc=com`,
)
fmt.Printf("%s", udns)

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com || ldap:///uid=courtney,ou=People,dc=example,dc=com

func (BindDistinguishedNames) BRM 

func (r BindDistinguishedNames) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var dn BindDistinguishedNames
fmt.Printf("%d available comparison operator methods", dn.BRM().Len())

Output:

2 available comparison operator methods

func (BindDistinguishedNames) Compare 

func (r BindDistinguishedNames) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) instances of BindDistinguishedNames using the Compare method.

The comparison evaluates as false because, while the contents match, their ordering does not. 

adns := UDNs(`uid=jesse,ou=People,dc=example,dc=com`, `uid=courtney,ou=People,dc=example,dc=com`)
odns := UDNs(`uid=courtney,ou=People,dc=example,dc=com`, `uid=jesse,ou=People,dc=example,dc=com`)

fmt.Printf("Hashes are equal: %t", odns.Compare(adns))

Output:

Hashes are equal: false

func (BindDistinguishedNames) Contains 

func (r BindDistinguishedNames) Contains(x any) bool

Contains returns a Boolean value indicative of whether value x, if a string or BindDistinguishedName instance, already resides within the receiver instance.

Case is not significant in the matching process.

Example 
dn := GDNs(
	`cn=Executives,ou=Groups,dc=example,dc=com`,
	`cn=Executive Assistants,ou=Groups,dc=example,dc=com`,
)

execs := `cn=Executives,ou=Groups,dc=example,dc=com`

fmt.Printf("Found: %t", dn.Contains(execs))

Output:

Found: true

func (BindDistinguishedNames) Eq 

func (r BindDistinguishedNames) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To one (1) of the following keyword contexts:

• `userdn`

• `groupdn`

• `roledn`

Example 
var dn BindDistinguishedNames = UDNs(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn.Eq())

Output:

userdn = "ldap:///uid=jesse,ou=People,dc=example,dc=com"

func (BindDistinguishedNames) F 

func (r BindDistinguishedNames) F() func(string) BindDistinguishedName

F returns the appropriate instance creator function for crafting individual BindDistinguishedName instances for submission to the receiver. This is merely a convenient alternative to maintaining knowledge as to which function applies to the current receiver instance.

The default is UDN, and will be returned if the receiver is uninitialized, or if the Keyword associated with the receiver is invalid somehow. Otherwise, GDN is returned for BindGDN, and RDN for BindRDN.

Example 
var odns BindDistinguishedNames = UDNs()
funk := odns.F()
odns.Push(funk(`uid=jesse,ou=People,dc=example,dc=com`))

fmt.Printf("%s", odns)

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com

func (BindDistinguishedNames) ID 

func (r BindDistinguishedNames) ID() string

ID returns the string literal `bind`.

Example 
var dn BindDistinguishedNames
fmt.Printf("%s", dn.ID())

Output:

bind

func (BindDistinguishedNames) Index 

func (r BindDistinguishedNames) Index(idx int) (b DistinguishedNameContext)

Index wraps go-stackage's Stack.Index method. Note that the Boolean OK value returned by go-stackage's Stack.Index method by default will be shadowed and not obtainable by the caller.

Example

This example demonstrates the call of a select slice member from the receiver using the Index method. 

odns := UDNs(`uid=jesse,ou=People,dc=example,dc=com`, `uid=courtney,ou=People,dc=example,dc=com`)

fmt.Printf("%s", odns.Index(0))

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com

func (BindDistinguishedNames) IsZero 

func (r BindDistinguishedNames) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example 
var odns BindDistinguishedNames
fmt.Printf("Zero: %t", odns.IsZero())

Output:

Zero: true

func (BindDistinguishedNames) Keyword 

func (r BindDistinguishedNames) Keyword() (kw Keyword)

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a BindRule bearing the receiver as a condition value.

Example 
var dn BindDistinguishedNames = UDNs(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("Keyword: %s", dn.Keyword())

Output:

Keyword: userdn

func (BindDistinguishedNames) Len 

func (r BindDistinguishedNames) Len() int

Len wraps go-stackage's Stack.Len method.

Example 
var odns BindDistinguishedNames = UDNs()
funk := odns.F()
odns.Push(funk(`uid=jesse,ou=People,dc=example,dc=com`))

fmt.Printf("Length: %d", odns.Len())

Output:

Length: 1

func (BindDistinguishedNames) Ne 

func (r BindDistinguishedNames) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To one (1) of the following keyword contexts:

• `userdn`

• `groupdn`

• `roledn`

Negated equality BindRule instances should be used with caution.

Example 
var dn BindDistinguishedNames = UDNs(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn.Ne())

Output:

userdn != "ldap:///uid=jesse,ou=People,dc=example,dc=com"

func (BindDistinguishedNames) Pop 

func (r BindDistinguishedNames) Pop() (popped BindDistinguishedName)

Pop wraps go-stackage's Stack.Pop method and performs type assertion to return a proper BindDistinguishedName instance.

Example 
var odns BindDistinguishedNames = UDNs()
odns.Push(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=jimmy,ou=People,dc=example,dc=com`,
)

popped := odns.Pop()

fmt.Printf("%s", popped)

Output:

ldap:///uid=jimmy,ou=People,dc=example,dc=com

func (BindDistinguishedNames) Push 

func (r BindDistinguishedNames) Push(x ...any) BindDistinguishedNames

Push wraps go-stackage's Stack.Push method. Valid input types are string and BindDistinguishedName.

In the case of a string value, it is automatically cast as an instance of BindDistinguishedName using the appropriate keyword, so long as the raw string is of a non-zero length.

Example 
var odns BindDistinguishedNames = UDNs()
odns.Push(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=jimmy,ou=People,dc=example,dc=com`,
)

fmt.Printf("Length: %d", odns.Len())

Output:

Length: 2

func (BindDistinguishedNames) String 

func (r BindDistinguishedNames) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example 
var odns BindDistinguishedNames = UDNs()
odns.Push(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=jimmy,ou=People,dc=example,dc=com`,
)

fmt.Printf("%s", odns)

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com || ldap:///uid=jimmy,ou=People,dc=example,dc=com

func (BindDistinguishedNames) Valid 

func (r BindDistinguishedNames) Valid() error

Valid wraps go-stackage's Stack.Valid method.

Example 
var odns BindDistinguishedNames
fmt.Printf("Valid: %t", odns.Valid() == nil)

Output:

Valid: false

type BindKeyword 

type BindKeyword uint8

BindKeyword contains the value describing a particular Bind Keyword to be used within a Bind Rule.

Example

This example demonstrates the interrogation of BindKeyword const definitions. This type qualifies for the Keyword interface type.

There are a total of eleven (11) such BindKeyword definitions. 

for idx, bk := range []BindKeyword{
	BindUDN,
	BindRDN,
	BindGDN,
	BindUAT,
	BindGAT,
	BindIP,
	BindDNS,
	BindDoW,
	BindToD,
	BindAM,
	BindSSF,
} {
	fmt.Printf("[%s] %02d/%d: %s\n",
		bk.Kind(), idx+1, 11, bk)
}

Output:

[bind] 01/11: userdn
[bind] 02/11: roledn
[bind] 03/11: groupdn
[bind] 04/11: userattr
[bind] 05/11: groupattr
[bind] 06/11: ip
[bind] 07/11: dns
[bind] 08/11: dayofweek
[bind] 09/11: timeofday
[bind] 10/11: authmethod
[bind] 11/11: ssf

const (
	BindUDN BindKeyword // `userdn`
	BindRDN             // `roledn`
	BindGDN             // `groupdn`
	BindUAT             // `userattr`
	BindGAT             // `groupattr`
	BindIP              // `ip`
	BindDNS             // `dns`
	BindDoW             // `dayofweek`
	BindToD             // `timeofday`
	BindAM              // `authmethod`
	BindSSF             // `ssf`
)

BindKeyword constants are intended for singular use within a Bind Rule condition.

func (BindKeyword) Kind 

func (r BindKeyword) Kind() string

Kind returns the string name for the kind of underlying Keyword (`bind`).

Example 
fmt.Printf("%s", BindUDN.Kind())

Output:

bind

func (BindKeyword) String 

func (r BindKeyword) String() (k string)

String is a stringer method that returns the string representation of the receiver instance of Bind Rule Keyword.

Example 
fmt.Printf("%s", BindUDN)

Output:

userdn

type BindRule 

type BindRule stackage.Condition

BindRule is a stackage.Condition type alias intended to represent a single Bind Rule; that is, one (1) Bind Rule keyword, one (1) comparison operator and one (1) or more string values (called an 'expression').

For example: 

ssf >= "128"

Instances of this type may be assembled manually by users, or may be created logically as a result of textual parsing. Users may also want to use convenient Eq, Ne, Gt, Ge, Lt, and Le methods extended through various types (as permitted) for simplicity.

Instances of this type shall appear within BindRules instances and may or may not be parenthetical.

func BR 

func BR(kw, op, ex any) BindRule

BR wraps go-stackage's Cond package-level function. In this context, it is wrapped here to assemble and return a BindRule instance using the so-called "one-shot" procedure. This is an option only when ALL information necessary for the process is in-hand and ready for user input: the keyword, comparison operator and the appropriate value(s) expression.

Use of this function shall not require a subsequent call of BindRule's Init method, which is needed only for so-called "piecemeal" BindRule assembly.

Use of this function is totally optional. Users may, instead, opt to populate the specific value instance(s) needed and execute the type's own Eq, Ne, Ge, Gt, Le and Lt methods (when applicable) to produce an identical return instance. Generally speaking, those methods may prove to be more convenient -- and far safer -- than use of this function.

Example

This example demonstrates the use of the package-level BR function for quick assembly of an instance of BindRule.

This is usually not necessary, and would only be practical when the input and type information is known in advance. It is also nowhere near as safe (regarding the specification of illegal constructs) as the use of type-extended comparison operator methods. See the BRM method extended by such types for further details. 

kw := BindUDN
op := Eq
ex := UDN(`uid=jesse,ou=People,dc=example,dc=com`)

fmt.Printf("%s", BR(kw, op, ex))

Output:

userdn = "ldap:///uid=jesse,ou=People,dc=example,dc=com"

func ParseBindRule 

func ParseBindRule(raw string) (BindRule, error)

ParseBindRule returns an instance of BindRule alongside an error instance.

This function calls the imported antlraci.ParseBindRule function, delegating parsing responsibilities there.

Example

This example demonstrates the parsing of a single BindRule condition.

A textual Bind Keyword, an appropriate ComparisonOperator as well as an appropriate expression value are submitted through the ParseBindRule package-level function, which in turn calls a similarly named antlraci function through which parsing is delegated. 

raw := `( userdn = "ldap:///cn=Jesse Coretta,ou=People,dc=example,dc=com" || "ldap:///cn=Courtney Tolana,ou=People,dc=example,dc=com" )`
br, err := ParseBindRule(raw)
if err != nil {
	fmt.Println(err) // always check your parser errors
	return
}
fmt.Printf("%T is parenthetical: %t", br, br.IsParen())

Output:

aci.BindRule is parenthetical: true

func Weekdays 

func Weekdays(cop any) (b BindRule)

Weekdays is a convenient prefabricator function that returns an instance of BindRule automatically assembled to express a sequence of weekdays. The sequence "Mon through Fri" can also be expressed via the bit-shifted value of sixty-two (62). See the Day constants for the specific numerals used for summation in this manner.

Supplying an invalid or nonapplicable ComparisonOperator to this method shall return a bogus BindRule instance.

Example 
fmt.Printf("%s", Weekdays(Eq))

Output:

dayofweek = "Mon,Tues,Wed,Thur,Fri"

func Weekend 

func Weekend(cop any) (b BindRule)

Weekend is a convenient prefabricator function that returns an instance of BindRule automatically assembled to express a sequence of Sun and Sat Day instances. This sequence can also be expressed via the bit-shifted value of sixty-five (65). See the Day constants for the specific numerals used for summation in this manner.

Supplying an invalid or nonapplicable ComparisonOperator to this method shall return a bogus BindRule instance.

Example 
fmt.Printf("%s", Weekend(Ne))

Output:

dayofweek != "Sun,Sat"

func (BindRule) Category 

func (r BindRule) Category() string

Category wraps go-stackage's Stack.Category method.

Example 
fmt.Printf("%s", SSF(71).Eq().Category())

Output:

ssf

func (BindRule) Compare 

func (r BindRule) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
ssf1 := SSF(128).Eq()
ssf2 := SSF(127).Eq()
fmt.Printf("Equal: %t", ssf1.Compare(ssf2))

Output:

Equal: false

func (BindRule) Expression 

func (r BindRule) Expression() any

Expression wraps go-stackage's Condition.Expression method.

Example 
dn := `uid=jesse,ou=Contractors,ou=People,dc=example,dc=com`
fmt.Printf("%s", UDN(dn).Eq().Expression())

Output:

ldap:///uid=jesse,ou=Contractors,ou=People,dc=example,dc=com

func (BindRule) ID 

func (r BindRule) ID() string

ID wraps go-stackage's Stack.ID method.

Example 
fmt.Printf("%s", IP(`192.168.`).Ne().ID())

Output:

bind

func (BindRule) Index 

func (r BindRule) Index(_ int) BindContext

Index returns the receiver instance. This method only exists to satisfy Go's interface signature requirements for the BindContext interface. See BindRules.Index instead.

func (*BindRule) Init 

func (r *BindRule) Init() BindRule

Init wraps stackage.Condition's Init method. This is a required method for situations involving the piecemeal (step-by-step) assembly of an instance of BindRule as opposed to a one-shot creation using the BR package-level function. It is also an ideal means for the creation of a BindRule instance when one does not immediately possess all of the needed pieces of information (i.e.: uncertain which keyword to use, or when an expression value has not yet been determined, etc).

Call this method after a variable declaration but before your first change, e.g.: 

var br BindRule
... do other things ...
... we're ready to set something now ...
br.Init()
br.SetKeyword("blarg")
br.SetSomethingElse(...)
...

Init need only be executed once within the lifespan of a BindRule instance. Its execution shall result in a completely new embedded pointer instance supplanting the previous one.

One may choose, however, to re-execute this method IF this instance shall be reused (perhaps in a repetative or looped manner), and if it would be desirable to 'wipe the slate clean' for some reason.

Example 
var br BindRule
br.Init() // required when assembly through "piecemeal"

// ... later in your code ...

br.SetKeyword(BindUDN) // set keyword ...
br.SetOperator(Ne)     // ... so operator can be evaluated
fmt.Printf("Operator: %s", br.Operator().Description())

Output:

Operator: Not Equal To

func (BindRule) IsNesting 

func (r BindRule) IsNesting() bool

IsNesting does not perform any useful task, and exists only to satisfy Go's interface signature requirements and to convey this message.

A Boolean value of false is returned in any scenario.

Example

This example demonstrates the useless execution of the IsNesting method, as its primary function does not apply to instances of BindRule, only BindRules.

As such, the execution of this method shall always return false. 

var br BindRule
if err := br.Parse(`(timeofday>="0415")`); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}
fmt.Printf("%T.IsNesting: %t", br, br.IsNesting())

Output:

aci.BindRule.IsNesting: false

func (BindRule) IsParen 

func (r BindRule) IsParen() bool

IsParen wraps go-stackage's Condition.IsParen method.

Example 
var br BindRule
if err := br.Parse(`(timeofday>="0415")`); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}
fmt.Printf("%T.IsParen: %t", br, br.IsParen())

Output:

aci.BindRule.IsParen: true

func (BindRule) IsZero 

func (r BindRule) IsZero() bool

IsZero wraps go-stackage's Condition.IsZero method.

Example 
var tr BindRule
fmt.Printf("Zero: %t", tr.IsZero())

Output:

Zero: true

func (BindRule) Keyword 

func (r BindRule) Keyword() Keyword

Keyword wraps go-stackage's Condition.Keyword method and resolves the raw value into a BindKeyword. Failure to do so will return a bogus Keyword.

Example 
fmt.Printf("%s", SSF(0).Ne().Keyword())

Output:

ssf

func (BindRule) Kind 

func (r BindRule) Kind() string

Kind returns the string literal `condition` to identify the receiver as a stackage.Condition type alias.

Example 
var tr BindRule
fmt.Printf("%s", tr.Kind())

Output:

condition

func (BindRule) Len 

func (r BindRule) Len() int

Len does not perform any useful task, and exists only to satisfy Go's interface signature requirements and to convey this message.

A value of zero (0) is returned if the receiver instance is nil. A value of one (1) otherwise.

Example

This example demonstrates the (mostly) useless execution of the Len method, as singular BindRule instances are generally not judged in terms of length, whether value-based or some other abstraction.

As such, the execution of this method shall always return one (1) when executed on a non-nil instance, and zero (0) otherwise. 

var br BindRule
if err := br.Parse(`(timeofday>="0415")`); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}
fmt.Printf("%T.Len: %d", br, br.Len())

Output:

aci.BindRule.Len: 1

func (BindRule) NoPadding 

func (r BindRule) NoPadding(state ...bool) BindRule

NoPadding wraps go-stackage's Condition.NoPadding method.

Example 
var br BindRule
if err := br.Parse(`(timeofday>="0415")`); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%s", br.NoPadding(false))

Output:

( timeofday >= "0415" )

func (BindRule) Operator 

func (r BindRule) Operator() ComparisonOperator

Operator wraps go-stackage's Condition.Operator method and casts the stackage.ComparisonOperator to the local aci.ComparisonOperator.

Example 
var br BindRule
br.Init() // required when assembly through "piecemeal"

// ... later in your code ...

br.SetKeyword(BindUDN) // set keyword ...
br.SetOperator(Ne)     // ... so operator can be evaluated
fmt.Printf("Operator: %s", br.Operator().Description())

Output:

Operator: Not Equal To

func (BindRule) Paren 

func (r BindRule) Paren(state ...bool) BindRule

Paren wraps go-stackage's Condition.Paren method.

Example 
var br BindRule
if err := br.Parse(`(timeofday>="0415")`); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

// Here we'll turn off parenthetical encaps
// and then verify it was turned off in one
// fmt.Printf call.

fmt.Printf("%T.IsParen: %t", br.Paren(false), br.IsParen())

Output:

aci.BindRule.IsParen: false

func (*BindRule) Parse 

func (r *BindRule) Parse(raw string) error
Example 
raw := `ssf >= "128"`
var br BindRule
if err := br.Parse(raw); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

br.NoPadding(true)
br.Paren(true)

fmt.Printf("%s", br)

Output:

(ssf>="128")

func (BindRule) SetExpression 

func (r BindRule) SetExpression(expr any) BindRule

SetExpression wraps go-stackage's Condition.SetExpression method.

Example 
var br BindRule
br.Init() // required when assembly through "piecemeal"

// ... later in your code ...

br.SetExpression(UDN(`uid=jesse,ou=People,dc=example,dc=com`))
fmt.Printf("Expression: %s", br.Expression().(BindDistinguishedName))

Output:

Expression: ldap:///uid=jesse,ou=People,dc=example,dc=com

func (BindRule) SetKeyword 

func (r BindRule) SetKeyword(kw any) BindRule

SetKeyword wraps go-stackage's Condition.SetKeyword method.

Example 
var br BindRule
br.Init() // required when assembly through "piecemeal"

// ... later in your code ...

br.SetKeyword(BindGDN) // set keyword ...
fmt.Printf("Keyword: %s", br.Keyword())

Output:

Keyword: groupdn

func (BindRule) SetOperator 

func (r BindRule) SetOperator(op any) BindRule

SetOperator wraps go-stackage's Condition.SetOperator method.

Example 
var br BindRule
br.Init() // required when assembly through "piecemeal"

// ... later in your code ...

br.SetKeyword(BindUDN) // set keyword ...
br.SetOperator(Ne)     // ... so operator can be evaluated
fmt.Printf("Operator: %s", br.Operator().Description())

Output:

Operator: Not Equal To

func (BindRule) SetQuoteStyle 

func (r BindRule) SetQuoteStyle(style int) BindRule

SetQuoteStyle allows the election of a particular multivalued quotation style offered by the various adopters of the ACIv3 syntax. In the context of a BindRule, this will only have a meaningful impact if the keyword for the receiver is one (1) of the following:

  • BindUDN (userdn)
  • BindRDN (roledn)
  • BindGDN (groupdn)

Additionally, the underlying type set as the expression value within the receiver MUST be a BindDistinguishedNames instance with two (2) or more distinguished names within.

See the const definitions for MultivalOuterQuotes (default) and MultivalSliceQuotes for details.

Example 
var tgt BindRule
tgt.SetKeyword(BindUDN)

tgt.Init()

tgt.SetKeyword(BindUDN)
tgt.SetOperator(`!=`)
tgt.SetOperator(2)
tgt.SetOperator(54738372)
tgt.SetOperator(Ne)
tgt.SetExpression(UDNs(
	UDN(`ldap:///uid=jesse,ou=People,dc=example,dc=com`),
	UDN(`ldap:///uid=courtney,ou=People,dc=example,dc=com`),
	UDN(`ldap:///uid=jimmy,ou=People,dc=example,dc=com`),
))

tgt.Paren() // optional

tgt.SetQuoteStyle(0)
style1 := tgt.String()

tgt.SetQuoteStyle(1)
style2 := tgt.String()

fmt.Printf("\n0: %s\n1: %s", style1, style2)

Output:

0: ( userdn != "ldap:///uid=jesse,ou=People,dc=example,dc=com" || "ldap:///uid=courtney,ou=People,dc=example,dc=com" || "ldap:///uid=jimmy,ou=People,dc=example,dc=com" )
1: ( userdn != "ldap:///uid=jesse,ou=People,dc=example,dc=com || ldap:///uid=courtney,ou=People,dc=example,dc=com || ldap:///uid=jimmy,ou=People,dc=example,dc=com" )

func (BindRule) String 

func (r BindRule) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Condition.String method.

Example 
var br BindRule
if err := br.Parse(`(timeofday>="0415")`); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%s", br)

Output:

( timeofday >= "0415" )

func (BindRule) Traverse 

func (r BindRule) Traverse(indices ...int) BindContext

Traverse returns the receiver instance. This method only exists to satisfy Go's interface signature requirements for the BindContext interface. See BindRules.Traverse instead.

Example

This example demonstrates the useless nature of the Traverse method for a receiver that is an instance of BindRule. As BindRule is logically "singular", there is no structure in which a traversal would be possible. The Traverse method only exists to satisfy Go's interface signature requirements as they pertain to the BindContext type, and this test exists only to maintain code coverage and to convey this message.

Execution of this method simply returns the receiver. 

br := SSF(71).Eq()
fmt.Printf("%T", br.Traverse(1, 2, 3, 4, 5))

Output:

aci.BindRule

func (BindRule) Valid 

func (r BindRule) Valid() (err error)

Valid wraps go-stackage's Condition.Valid method.

Example 
var tr BindRule
fmt.Printf("Valid: %t", tr.Valid() == nil)

Output:

Valid: false

type BindRuleMethod 

type BindRuleMethod func() BindRule

BindRuleMethod is the closure signature for methods used to build new instances of BindRule.

The signature is qualified by the following methods extended through all eligible types defined in this package:

• Eq

• Ne

• Lt

• Le

• Gt

• Ge

Note that certain types only support a subset of the above list. Very few types support all of the above.

Example 
ssf := SSF(256)
brm := ssf.BRM()

// verify that the receiver (ssf) is copacetic
// and will produce a legal expression if meth
// is executed
if err := brm.Valid(); err != nil {
	fmt.Println(err)
	return
}

for i := 0; i < brm.Len(); i++ {
	// IMPORTANT: Do not call index 0. Either adjust your
	// loop variable (i) to begin at 1, and terminate at
	// brm.Len()+1 --OR-- simply +1 the index call as we
	// are doing here (seems easier). The reason for this
	// is because there is no valid ComparisonOperator
	// with an underlying uint8 value of zero (0). See
	// the ComparisonOperator constants for details.
	idx := i + 1
	cop, meth := brm.Index(idx)

	// execute method to create the bindrule, while
	// also enabling the (optional) parenthetical bit
	rule := meth().Paren()

	// grab the raw string output
	fmt.Printf("[%d] %T instance [%s] execution returned %T: %s\n", idx, meth, cop.Context(), rule, rule)
}

Output:

[1] aci.BindRuleMethod instance [Eq] execution returned aci.BindRule: ( ssf = "256" )
[2] aci.BindRuleMethod instance [Ne] execution returned aci.BindRule: ( ssf != "256" )
[3] aci.BindRuleMethod instance [Lt] execution returned aci.BindRule: ( ssf < "256" )
[4] aci.BindRuleMethod instance [Gt] execution returned aci.BindRule: ( ssf > "256" )
[5] aci.BindRuleMethod instance [Le] execution returned aci.BindRule: ( ssf <= "256" )
[6] aci.BindRuleMethod instance [Ge] execution returned aci.BindRule: ( ssf >= "256" )

type BindRuleMethods 

type BindRuleMethods struct {
	// contains filtered or unexported fields
}

BindRuleMethods contains one (1) or more instances of BindRuleMethod, representing a particular BindRule "builder" method for execution by the caller.

See the Operators method extended through all eligible types for further details.

Example

This example demonstrates the indexing, iteration and execution of the available comparison operator methods for the BindDistinguishedName type. 

var dn BindDistinguishedName = GDN(`cn=X.500 Administrators,ou=Groups,dc=example,dc=com`)
brm := dn.BRM()

for i := 0; i < brm.Len(); i++ {
	cop, meth := brm.Index(i + 1)                              // zero (0) should never be accessed, start at 1
	fmt.Printf("[%s] %s\n", cop.Description(), meth().Paren()) // enable parentheticals, because why not
}

Output:

[Equal To] ( groupdn = "ldap:///cn=X.500 Administrators,ou=Groups,dc=example,dc=com" )
[Not Equal To] ( groupdn != "ldap:///cn=X.500 Administrators,ou=Groups,dc=example,dc=com" )

func (BindRuleMethods) Contains 

func (r BindRuleMethods) Contains(cop any) bool

Contains returns a Boolean value indicative of whether the specified ComparisonOperator, which may be expressed as a string, int or native ComparisonOperator, is allowed for use by the type instance that created the receiver instance. This method offers a convenient alternative to the use of the Index method combined with an assertion value (such as Eq, Ne, "=", "Greater Than", et al).

In other words, if one uses the FQDN.BRM method to create an instance of BindRuleMethods, feeding Gt (Greater Than) to this method shall return false, as mathematical comparison does not apply to instances of the FQDN type.

func (BindRuleMethods) Index 

func (r BindRuleMethods) Index(idx any) (ComparisonOperator, BindRuleMethod)

Index calls the input index (idx) within the internal structure of the receiver instance. If found, an instance of ComparisonOperator and its accompanying BindRuleMethod instance are returned.

Valid input index types are integer (int), ComparisonOperator constant or string identifier. In the case of a string identifier, valid values are as follows:

• For Eq (1): `=`, `Eq`, `Equal To`

• For Ne (2): `=`, `Ne`, `Not Equal To`

• For Lt (3): `=`, `Lt`, `Less Than`

• For Le (4): `=`, `Le`, `Less Than Or Equal`

• For Gt (5): `=`, `Gt`, `Greater Than`

• For Ge (6): `=`, `Ge`, `Greater Than Or Equal`

Case is not significant in the string matching process.

Please note that use of this method by way of integer or ComparisonOperator values utilizes fewer resources than a string lookup.

See the ComparisonOperator type's Context, String and Description methods for accessing the above string values easily.

If the index was not matched, an invalid ComparisonOperator is returned alongside a nil BindRuleMethod. This will also apply to situations in which the type instance which crafted the receiver is uninitialized, or is in an otherwise aberrant state.

Example 
ssf := SSF(256)
brm := ssf.BRM()

for i := 0; i < brm.Len(); i++ {
	// IMPORTANT: Do not call index 0. Either adjust your
	// loop variable (i) to begin at 1, and terminate at
	// brm.Len()+1 --OR-- simply +1 the index call as we
	// are doing here (seems easier). The reason for this
	// is because there is no valid ComparisonOperator
	// with an underlying uint8 value of zero (0). See
	// the ComparisonOperator constants for details.
	idx := i + 1
	cop, meth := brm.Index(idx)

	// execute method to create the bindrule, while
	// also enabling the (optional) parenthetical bit
	rule := meth().Paren()

	// grab the raw string output
	fmt.Printf("[%d] %T instance [%s] execution returned %T: %s\n", idx, meth, cop.Context(), rule, rule)
}

Output:

[1] aci.BindRuleMethod instance [Eq] execution returned aci.BindRule: ( ssf = "256" )
[2] aci.BindRuleMethod instance [Ne] execution returned aci.BindRule: ( ssf != "256" )
[3] aci.BindRuleMethod instance [Lt] execution returned aci.BindRule: ( ssf < "256" )
[4] aci.BindRuleMethod instance [Gt] execution returned aci.BindRule: ( ssf > "256" )
[5] aci.BindRuleMethod instance [Le] execution returned aci.BindRule: ( ssf <= "256" )
[6] aci.BindRuleMethod instance [Ge] execution returned aci.BindRule: ( ssf >= "256" )
Example (ByText) 
ssf := SSF(256)
brm := ssf.BRM()

// Here, we demonstrate calling a particular BindRuleMethod
// not by its numerical index, but rather by its actual
// "symbolic" operator representation. Keep in mind these
// options for text-based searches:
//
// - symbols (e.g.: '=', '>') are available via ComparisonOperator.String()
// - func names (e.g.: 'Eq', 'Gt') are available via ComparisonOperator.Context()
// - descriptions (e.g.: 'Not Equal To', 'Less Than') are available via ComparisonOperator.Description()
//
// As such, feel free to replace these list items with one of the above methods,
// but keep in mind that text based searches are more resource intensive than as
// compared to direct ComparisonOperator numeric calls. If you have performance
// concerns, avoid this text based procedure.
for i, term := range []string{
	`=`,
	`!=`,
	`<`,
	`>`,
	`<=`,
	`>=`,
} {
	// IMPORTANT: Do not call index 0. Either adjust your
	// loop variable (i) to begin at 1, and terminate at
	// brm.Len()+1 --OR-- simply +1 the index call as we
	// are doing here (seems easier). The reason for this
	// is because there is no valid ComparisonOperator
	// with an underlying uint8 value of zero (0). See
	// the ComparisonOperator constants for details.
	cop, meth := brm.Index(term)

	// execute method to create the bindrule, while
	// also enabling the (optional) parenthetical bit
	rule := meth().Paren()

	// grab the raw string output
	fmt.Printf("[%d] %T instance [%s] execution returned %T: %s\n", i+1, meth, cop.Context(), rule, rule)
}

Output:

[1] aci.BindRuleMethod instance [Eq] execution returned aci.BindRule: ( ssf = "256" )
[2] aci.BindRuleMethod instance [Ne] execution returned aci.BindRule: ( ssf != "256" )
[3] aci.BindRuleMethod instance [Lt] execution returned aci.BindRule: ( ssf < "256" )
[4] aci.BindRuleMethod instance [Gt] execution returned aci.BindRule: ( ssf > "256" )
[5] aci.BindRuleMethod instance [Le] execution returned aci.BindRule: ( ssf <= "256" )
[6] aci.BindRuleMethod instance [Ge] execution returned aci.BindRule: ( ssf >= "256" )

func (BindRuleMethods) IsZero 

func (r BindRuleMethods) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var brm BindRuleMethods
fmt.Printf("Zero: %t", brm.IsZero())

Output:

Zero: true

func (BindRuleMethods) Len 

func (r BindRuleMethods) Len() int

Len returns the integer length of the receiver. Note that the return value will NEVER be less than zero (0) nor greater than six (6).

Example 
// Note: we need not populate the value to get a
// BRM list, but the methods in that list won't
// actually work until the instance (ssf) is in
// an acceptable state. Since all we're doing
// here is checking the length, a receiver that
// is nil/zero is totally fine.
var ssf SecurityStrengthFactor // not init'd
total := ssf.BRM().Len()

fmt.Printf("There are %d available aci.BindRuleMethod instances for creating %T BindRules", total, ssf)

Output:

There are 6 available aci.BindRuleMethod instances for creating aci.SecurityStrengthFactor BindRules

func (BindRuleMethods) Valid 

func (r BindRuleMethods) Valid() (err error)

Valid returns the first encountered error returned as a result of execution of the first available BindRuleMethod instance. This is useful in cases where a user wants to see if the desired instance(s) of BindRuleMethod will produce a usable result.

Example 
var brm BindRuleMethods
fmt.Printf("Error: %v", brm.Valid())

Output:

Error: aci.BindRuleMethods instance is nil

type BindRules 

type BindRules stackage.Stack

BindRules is a stackage.Stack type alias intended to store and express one (1) or more Bind Rule statements, with or without nesting and (at least usually) bound by Boolean logical WORD operators 'AND', 'OR' and 'AND NOT'.

For example: 

ssf >= "128" AND ip = "192.168.*"

Instances of this type may be assembled manually by users, or may be created logically as a result of textual parsing. There are also some convenient operator-specific methods available (And() for 'AND', Or() for 'OR' and Not() for 'AND NOT'.

Example

This example demonstrates the various capabilities of a BindRules instance, as well as the use of some so-called "prefabricator" functions for additional convenience.

Note that BindRules should always be initialized before use. The reason for this is because it may be required to set a logical Boolean operating mode, such as 'AND', 'OR' and '(AND) NOT'. This governs how the individual slices (which may descend into other stacks) are string represented in a Boolean expressive statement. 

// Outer BindRules structure (a.k.a.: the "top")
// is a non-parenthetical ORed BindRules stack.
var brs BindRules = Or(

	// First ORed condition (slice #0) is a
	// non-parenthetical ANDed BindRules stack
	// with operator folding enabled.
	And(
		// A single non-parenthetical groupdn
		// equality assertion BindRule occupies
		// slice #0 of the current stack. Note
		// that in this case, calling the needed
		// operator method is necessary, as GDN
		// is not a prefab function.
		//
		// Result:
		GDN(`cn=Accounting,ou=Groups,dc=example,dc=com`).Eq(), // groupdn

		// Timeframe is a BindRules prefab function
		// used to conveniently produce a pair of
		// `timeofday` conditions within an ANDed
		// logical context in order to specify a
		// "time-window" during which access will
		// be granted or withheld in some manner.
		//
		// This expression occupies slice #1 of the
		// current stack and is parenthetical. There
		// is no need to execute the operator method
		// (e.g.: Eq) manually, as this function is
		// a prefabricator and does this for us 😎.
		// Additionally, toggle the Fold bit for the
		// return instance.
		//
		// Result: ( timeofday >= "0900" and timeofday < "1830" )
		Timeframe(
			ToD(`0900`), // notBefore
			ToD(`1830`), // notAfter
		).Paren().Fold(),

		// Weekdays is a BindRule prefab to conveniently
		// produce a sequence of Day instances expressing
		// Monday through Friday. See also Weekend for an
		// inverse of this functionality.
		//
		// This expression occupies slice #2 of the current
		// stack and is parenthetical. There is no need to
		// execute the operator method (e.g:. Eq) manually,
		// as this function automatically crafts the BindRule.
		//
		// Result: ( dayofweek = "Mon,Tues,Wed,Thur,Fri" )
		Weekdays(`=`).Paren(), // comparison operator could also be 1, `eq` or `equal to`
	).Fold(),

	// Second ORed condition (slice #1) is a
	// parenthetically ANDed BindRules stack.
	And(
		// Two (2) individual BindRule instances
		// circumscribed within a parenthetical
		// AND context. Note that in this case,
		// calling the comparison method manually
		// is required, as RDN and GAT (among
		// others) are not prefab functions.
		//
		// result: ( roledn = "ldap:///cn=Superusers,ou=Groups,dc=example,dc=com`" AND groupattr = "privilegeLevel#GAMMA5" )
		RDN(`cn=Superusers,ou=Groups,dc=example,dc=com`).Eq(), // roledn
		GAT(`privilegeLevel`, `GAMMA5`).Eq(),                  // groupattr
	).Paren(),
)

// Let's make some arbitrary changes ...
//
// Make the outer stack (OR) parenthetical
brs.Paren() // no arg = toggle state, else use true/false for explicit set.

fmt.Printf("%s", brs)

Output:

( groupdn = "ldap:///cn=Accounting,ou=Groups,dc=example,dc=com" and ( timeofday >= "0900" and timeofday < "1830" ) and ( dayofweek = "Mon,Tues,Wed,Thur,Fri" ) OR ( roledn = "ldap:///cn=Superusers,ou=Groups,dc=example,dc=com" AND groupattr = "privilegeLevel#GAMMA5" ) )

func And 

func And(x ...any) (b BindRules)

And returns an instance of Rule configured to express Boolean AND logical operations. Instances of this design contain BindContext instances, which are qualified through instances of the following types:

• BindRule

• BindRules

Optionally, the caller may choose to submit one (1) or more (valid) instances of these types during initialization. This is merely a more convenient alternative to separate initialization and push procedures.

The embedded type within the return is stackage.Stack via the go-stackage package's And function.

Example

This example demonstrates the union between a group distinguished name and a timeframe, expressed as a BindRules instance. Parenthetical encapsulation is enabled for inner stack elements, but not the outer (AND) stack itself. 

and := And(
	GDN(`cn=X.500 Administrators,ou=Groups,dc=example,dc=com`).Eq().Paren(),
	Timeframe(ToD(`1730`), ToD(`2330`)).Paren(),
)
fmt.Printf("%s", and)

Output:

( groupdn = "ldap:///cn=X.500 Administrators,ou=Groups,dc=example,dc=com" ) AND ( timeofday >= "1730" AND timeofday < "2330" )

func Not 

func Not(x ...any) (b BindRules)

Not returns an instance of Rule configured to express Boolean NOT logical operations. Instances of this design contain BindContext instances, which are qualified through instances of the following types:

• BindRule

• BindRules

Optionally, the caller may choose to submit one (1) or more (valid) instances of these types during initialization. This is merely a more convenient alternative to separate initialization and push procedures.

The embedded type within the return is stackage.Stack via the go-stackage package's Not function.

Example

This example demonstrates a logical NOT that excludes a value matching userattr context or an LDAPURI bearing the userdn key context. The NOT operation should generally encompass one (1) or more conditions within an OR context. Additionally, NOT operations generally reside within an outer AND context as shown. YMMV. 

and := And(
	IP(`192.168.`).Eq().Paren(),
	Not(Or(
		UAT(`manager`, `LDAPURL`).Eq().Paren(),
		URI(UDN(`ou=People,dc=example,dc=com`), Subtree).Eq().Paren(),
	).Paren()),
)
fmt.Printf("%s", and)

Output:

( ip = "192.168." ) AND NOT ( ( userattr = "manager#LDAPURL" ) OR ( userdn = "ldap:///ou=People,dc=example,dc=com??sub?" ) )

func Or 

func Or(x ...any) (b BindRules)

Or returns an instance of Rule configured to express Boolean OR logical operations. Instances of this design contain BindContext instances, which are qualified through instances of the following types:

• BindRule

• BindRules

Optionally, the caller may choose to submit one (1) or more (valid) instances of these types during initialization. This is merely a more convenient alternative to separate initialization and push procedures.

The embedded type within the return is stackage.Stack via the go-stackage package's Or function.

Example

This example demonstrates a logical OR between a value matching bind rule and an LDAP URI bearing the userdn keyword context. Parentheticals are enabled at every point. 

or := Or(
	UAT(`manager`, `LDAPURL`).Eq().Paren(),
	URI(UDN(`ou=People,dc=example,dc=com`), Subtree).Eq().Paren(),
)
fmt.Printf("%s", or.Paren())

Output:

( ( userattr = "manager#LDAPURL" ) OR ( userdn = "ldap:///ou=People,dc=example,dc=com??sub?" ) )

func Timeframe 

func Timeframe(notBefore, notAfter TimeOfDay) (window BindRules)

Timeframe is a convenience function that returns a BindRules instance for the purpose of expressing a timeframe during which access may (or may not) be granted. This is achieved by combining the two (2) TimeOfDay input values in a Boolean "AND stack".

The notBefore input value defines the so-called "start" of the timeframe. It should be chronologically earlier than notAfter. This value will be used to craft a Greater-Than-Or-Equal (Ge) BindRule expressive statement.

The notAfter input value defines the so-called "end" of the timeframe. It should be chronologically later than notBefore. This value will be used to craft a Less-Than (Lt) BindRule expressive statement.

Example

This example demonstrates the creation of a timeframe BindRules instance using the convenient Timeframe package-level function.

The return value is a Boolean AND stack object containing the start (notBefore) and end (notAfter) TimeOfDay instances. 

notBefore := ToD(`1730`)
notAfter := ToD(`2400`)
tfr := Timeframe(notBefore, notAfter).Paren(true)
fmt.Printf("%s", tfr)

Output:

( timeofday >= "1730" AND timeofday < "2400" )

func (BindRules) Category 

func (r BindRules) Category() string

Category wraps go-stackage's Stack.Category method.

Example 
fmt.Printf("%s", And(SSF(71).Eq()).Category())

Output:

and

func (BindRules) Compare 

func (r BindRules) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
tf1 := Timeframe(ToD(`0130`), ToD(`1605`))
tf2 := Timeframe(ToD(`1215`), ToD(`1605`))

fmt.Printf("Equal: %t", tf1.Compare(tf2))

Output:

Equal: false

func (BindRules) Fold 

func (r BindRules) Fold(state ...bool) BindRules

Fold wraps go-stackage's Stack.Fold method to allow the case folding of logical Boolean 'AND', 'OR' and 'AND NOT' WORD operators to 'and', 'or' and 'and not' respectively, or vice versa.

Example

This example demonstrates the toggling of Boolean WORD operator case-folding of a BindRules instance. 

strong := And(SSF(128).Ge(), EXTERNAL.Eq())
strong.Fold() // we want `AND` to be `and`

fmt.Printf("%s", strong)

Output:

ssf >= "128" and authmethod = "SASL EXTERNAL"

func (BindRules) ID 

func (r BindRules) ID() string

ID wraps go-stackage's Stack.ID method.

Example 
var brs BindRules
fmt.Printf("%s", brs.ID())

Output:

bind

func (BindRules) Index 

func (r BindRules) Index(idx int) (ctx BindContext)

Index wraps go-stackage's Stack.Index method.

Example

This example demonstrates the calling of a specific slice member by its numerical index using the BindRules.Index method. 

brs := And(
	Timeframe(
		ToD(`0900`),
		ToD(`1830`),
	),
	Weekdays(Eq),
)

fmt.Printf("%s", brs.Index(0))

Output:

timeofday >= "0900" AND timeofday < "1830"

func (BindRules) IsNesting 

func (r BindRules) IsNesting() bool

IsNesting wraps go-stackage's Stack.IsNesting method.

Example

This example demonstrates the interrogation of a BindRules instance to determine whether any of its immediate slice members are other stack elements, thereby indicating that a "nesting condition" is in effect. 

brs := And(
	Timeframe(
		ToD(`0900`),
		ToD(`1830`),
	),
	Weekdays(Eq),
)

fmt.Printf("Contains nesting elements: %t", brs.IsNesting())

Output:

Contains nesting elements: true

func (BindRules) IsParen 

func (r BindRules) IsParen() bool

IsParen wraps go-stackage's Stack.IsParen method.

Example 
// Use the convenient timeframe prefabber to
// create a BindRules instance, for which we
// engage parentheticals, all in one shot.
tf := Timeframe(ToD(`0700`), ToD(`1800`)).Paren()

fmt.Printf("%T.IsParen: %t", tf, tf.IsParen())

Output:

aci.BindRules.IsParen: true

func (BindRules) IsZero 

func (r BindRules) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example 
var brs BindRules
fmt.Printf("Zero: %t", brs.IsZero())

Output:

Zero: true

func (BindRules) Keyword 

func (r BindRules) Keyword() Keyword

Keyword wraps go-stackage's Stack.Category method and resolves the raw value into a BindKeyword. Failure to do so will return a bogus Keyword.

Example

This example demonstrates the use of the useless Keyword method that returns a bogus keyword in string representation. Keywords are only directly applicable to BindRule instances. 

tf := Timeframe(
	ToD(`0900`),
	ToD(`1830`),
)

fmt.Printf("%s", tf.Keyword())

Output:

<invalid_bind_keyword>

func (BindRules) Kind 

func (r BindRules) Kind() string

Kind returns the string literal `stack` to identify the receiver as a stackage.Stack type alias.

Example

This example demonstrates the use of the Kind method to reveal the underlying type of the receiver. This is for use during the handling of a combination of BindRules and BindRule instances under the BindContext interface context. 

brs := And(
	Timeframe(
		ToD(`0900`),
		ToD(`1830`),
	),
	Weekdays(Eq),
)

fmt.Printf("%s", brs.Kind())

Output:

stack

func (BindRules) Len 

func (r BindRules) Len() int

Len wraps go-stackage's Stack.Len method.

Example

This example demonstrates the interrogation of a BindRules instance to determine its integer length using its Len method. The return value describes the number of slice elements present within the instance. 

brs := And(
	Timeframe(
		ToD(`0900`),
		ToD(`1830`),
	),
	Weekdays(Eq),
)

fmt.Printf("Contains %d elements", brs.Len())

Output:

Contains 2 elements

func (BindRules) NoPadding 

func (r BindRules) NoPadding(state ...bool) BindRules

NoPadding wraps go-stackage's Stack.NoPadding method.

Example

This example demonstrates the use of the NoPadding method to remove the outer padding of a BindRules instance. Note that parentheticals are enabled for visual aid. 

brs := And(
	Timeframe(
		ToD(`0900`),
		ToD(`1830`),
	),
	Weekdays(Eq),
)

brs.Paren().NoPadding()

fmt.Printf("%s", brs)

Output:

(timeofday >= "0900" AND timeofday < "1830" AND dayofweek = "Mon,Tues,Wed,Thur,Fri")

func (BindRules) Paren 

func (r BindRules) Paren(state ...bool) BindRules

Paren wraps go-stackage's Stack.Paren method.

Example

This example demonstrates the use of the Paren method to enable the parenthetical setting for the receiver instance. 

brs := And(
	Timeframe(
		ToD(`0900`),
		ToD(`1830`),
	),
	Weekdays(Eq),
)

brs.Paren()

fmt.Printf("%s", brs)

Output:

( timeofday >= "0900" AND timeofday < "1830" AND dayofweek = "Mon,Tues,Wed,Thur,Fri" )

func (*BindRules) Parse 

func (r *BindRules) Parse(raw string) error

Parse returns an error based upon an attempt to parse the raw input value into the receiver instance. If successful, any contents within the receiver instance would be obliterated, replaced irrevocably by the freshly parsed values.

Both this method, and the package-level ParseBindRule function, call antlraci's ParseBindRule function in similar fashion. The only real difference here is the process of writing to a receiver, versus writing to an uninitialized variable declaration.

Example 
raw := `( ssf >= "128" AND ( authmethod = "SASL" OR authmethod = "SSL" ) )`
var brs BindRules
if err := brs.Parse(raw); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%s", brs.Traverse(0, 1, 0))

Output:

authmethod = "SASL"
Example (Messy) 
raw := `(
                        (
                                ( userdn = "ldap:///anyone" ) AND
                                ( ssf >= "71" )

                        ) AND NOT (
                                dayofweek = "Wed" OR
                                dayofweek = "Fri"
                        )
        )`

br, err := ParseBindRules(raw)
if err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

called := br.Traverse(0, 0, 0)
fmt.Printf("%s", called)

Output:

( userdn = "ldap:///anyone" )

func (BindRules) Pop 

func (r BindRules) Pop() BindContext

Pop wraps go-stackage's Stack.Pop method. An instance of BindContext, which may or may not be nil, is returned following a call of this method.

Within the context of the receiver type, a BindContext, if non-nil, can represent any of the following instance types:

• BindRule

• BindRules

Example

This example demonstrates the removal of a single slice within a BindRules instance in LIFO fashion using its Pop method. 

// create a single BindRules instance
// with two (2) slices ...
brs := And(
	Timeframe(
		ToD(`0900`), // slice #0
		ToD(`1830`), // slice #1
	),
	Weekdays(Eq),
)

// Remove (by Pop) the Weekdays slice (slice #1)
popped := brs.Pop()

fmt.Printf("%s", popped)

Output:

dayofweek = "Mon,Tues,Wed,Thur,Fri"

func (BindRules) Push 

func (r BindRules) Push(x ...any) BindRules

Push wraps go-stackage's Stack.Push method.

Example

This example demonstrates the addition of new slice elements to a BindRules instance using its Push method. 

// create a single BindRules instance
// with only one (1) slice (Timeframe
// BindRule) ...
brs := And(
	Timeframe(
		ToD(`0900`),
		ToD(`1830`),
	),
)

// Add a Weekdays BindRule prefab
brs.Push(Weekdays(Eq))

fmt.Printf("%s", brs)

Output:

timeofday >= "0900" AND timeofday < "1830" AND dayofweek = "Mon,Tues,Wed,Thur,Fri"

func (BindRules) ReadOnly 

func (r BindRules) ReadOnly(state ...bool) BindRules

ReadOnly wraps go-stackage's Stack.ReadOnly method.

Example

This example demonstrates an attempt to modify a BindRules stack instance while its ReadOnly bit is enabled. 

strong := And(
	SSF(128).Ge(),  // slice #0
	DIGESTMD5.Eq(), // slice #1
)

strong.ReadOnly()

// Try to replace awful Digest-MD5 with
// the SASL/EXTERNAL mechanism.
strong.Replace(EXTERNAL.Eq(), 1)

fmt.Printf("%s", strong)

Output:

ssf >= "128" AND authmethod = "SASL DIGEST-MD5"

func (BindRules) Replace 

func (r BindRules) Replace(x any, idx int) BindRules

Replace wraps go-stackage's Stack.Replace method.

Example

This example demonstrates the selective replacement of a specific BindRules stack slice. 

strong := And(
	SSF(128).Ge(),  // slice #0
	DIGESTMD5.Eq(), // slice #1
)

// Replace awful Digest-MD5 with the
// SASL/EXTERNAL mechanism.
strong.Replace(EXTERNAL.Eq(), 1) // <x> replace slice #1

fmt.Printf("%s", strong)

Output:

ssf >= "128" AND authmethod = "SASL EXTERNAL"

func (BindRules) String 

func (r BindRules) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example 
strong := And(SSF(128).Ge(), EXTERNAL.Eq())

fmt.Printf("%s", strong)

Output:

ssf >= "128" AND authmethod = "SASL EXTERNAL"

func (BindRules) Traverse 

func (r BindRules) Traverse(indices ...int) (B BindContext)

Traverse wraps go-stackage's Stack.Traverse method.

Example

This example demonstrates the traversal of a BindRules structure to obtain a specific nested element, in this case the 'ssf >= "128"' expression. 

// And() is the variable for the outermost stack, don't count it as an index.
// Rather, begin counting its children instead.
rules := And(
	GDN(`cn=X.500 Administrators,ou=Groups,dc=example,dc=com`).Eq().Paren(),
	Timeframe(ToD(`1730`), ToD(`2330`)).Paren(),

	// Enter the Or stack by descending within the third element (AND slice #2)
	Or(
		UAT(`manager`, `LDAPURL`).Eq().Paren(),
		GAT(`owner`, SELFDN).Eq().Paren(),
		URI(UDN(`ou=People,dc=example,dc=com`), Subtree).Eq().Paren(),
		// OR slice #3. This is ILLOGICAL because
		// there's no benefit to placing an AND in
		// this rule, as it does not produce what
		// would be viewed as a "sensible" statement
		// of evaluation.
		And(
			// Inner AND slice #0
			SSF(128).Ge(),
		),
	),
)

ssf := rules.Traverse(2, 3, 0)
fmt.Printf("%s", ssf)

Output:

ssf >= "128"
Example (AndWrite)

This is an identical scenario to the above Traverse example, except in this scenario we will be writing to the slice returned. 

// And() is the variable for the outermost stack, don't count it as an index.
// Rather, begin counting its children instead.
rules := And(
	GDN(`cn=X.500 Administrators,ou=Groups,dc=example,dc=com`).Eq().Paren(),
	Timeframe(ToD(`1730`), ToD(`2330`)).Paren(),

	// Enter the Or stack by descending within the third element (AND slice #2)
	Or(
		UAT(`manager`, `LDAPURL`).Eq().Paren(),
		GAT(`owner`, SELFDN).Eq().Paren(),
		URI(UDN(`ou=People,dc=example,dc=com`), Subtree).Eq().Paren(),
		// OR slice #3
		And(
			// Inner AND slice #0
			SSF(128).Ge(),
		),
	),
)

// Call the specific stack/slice we want. Remember,
// Traverse returns a BindContext interface, which
// will be either BindRule OR BindRules. In this
// demonstration, we know what it is, thus we need
// not perform type switching in a case statement.
raw := rules.Traverse(2, 3, 0)
asserted, ok := raw.(BindRule)
if !ok {
	fmt.Printf("Failed to assert %T", asserted)
	return
}

// Because go-stackage is so heavily pointer-based,
// we need not worry about "writing the updated SSF
// value back to the stack". Just make the changes
// to the condition itself, and be done with it.
asserted.SetExpression(SSF(164)) // set to 164 because I'm so arbitrary

// Do the stack walk again to see if the pointer updated ...
fmt.Printf("%s", rules.Traverse(2, 3, 0))

Output:

ssf >= "164"

func (BindRules) Valid 

func (r BindRules) Valid() (err error)

Valid wraps go-stackage's Stack.Valid method.

Example 
var brs BindRules
fmt.Printf("Valid: %t", brs.Valid() == nil)

Output:

Valid: false

type BindType 

type BindType uint8

BindType describes one (1) of five (5) possible keywords used in certain Bind Rule *Condition values:

• USERDN

• GROUPDN

• ROLEDN

• SELFDN

• LDAPURL

Example

Let's print out each BindType constant defined in this package. 

for idx, bt := range []BindType{
	USERDN,
	GROUPDN,
	ROLEDN,
	SELFDN,
	LDAPURL,
} {
	fmt.Printf("%T %d/%d: %s\n",
		bt, idx+1, 5, bt)
}

Output:

aci.BindType 1/5: USERDN
aci.BindType 2/5: GROUPDN
aci.BindType 3/5: ROLEDN
aci.BindType 4/5: SELFDN
aci.BindType 5/5: LDAPURL

const (
	USERDN BindType
	GROUPDN
	ROLEDN
	SELFDN
	LDAPURL
)

BindType keyword constants are used in value matching definitions that utilizes either the UAT (userattr) or GAT (groupattr) BindKeyword constant within a BindRule *Condition instance.

func (BindType) String 

func (r BindType) String() (b string)

String is a stringer method that returns the string representation of the receiver instance of BindType.

type ComparisonOperator 

type ComparisonOperator stackage.ComparisonOperator

ComparisonOperator is an alias for stackage.ComparisonOperator. Instances of this type are used to contruct TargetRule and BindRule instances, and describe the manner in which abstract contexts are to be evaluated.

Example (Stringers) 
for _, cop := range []ComparisonOperator{
	Eq, Ne, Lt, Gt, Le, Ge,
} {
	fmt.Printf("[%d] %s (%s)[%s]\n",
		int(cop),
		cop.Description(),
		cop.Context(),
		cop)
}

Output:

[1] Equal To (Eq)[=]
[2] Not Equal To (Ne)[!=]
[3] Less Than (Lt)[<]
[4] Greater Than (Gt)[>]
[5] Less Than Or Equal (Le)[<=]
[6] Greater Than Or Equal (Ge)[>=]

const (
	Eq ComparisonOperator = ComparisonOperator(stackage.Eq) // 0x1, "Equal To"
	Ne ComparisonOperator = ComparisonOperator(stackage.Ne) // 0x2, "Not Equal to"     !! USE WITH CAUTION !!
	Lt ComparisonOperator = ComparisonOperator(stackage.Lt) // 0x3, "Less Than"
	Gt ComparisonOperator = ComparisonOperator(stackage.Gt) // 0x4, "Greater Than"
	Le ComparisonOperator = ComparisonOperator(stackage.Le) // 0x5, "Less Than Or Equal"
	Ge ComparisonOperator = ComparisonOperator(stackage.Ge) // 0x6, "Greater Than Or Equal"
)

ComparisonOperator constants defined within the stackage package are aliased within this package for convenience, without the need for user-invoked stackage package import.

func (ComparisonOperator) Compare 

func (r ComparisonOperator) Compare(cop any) bool

Compare shall resolve the input ComparisonOperator candidate (cop) and, if successful, shall perform an equality assertion between it and the receiver instance. The assertion result is returned as a bool instance.

In the case of the string representation of a given candidate input value, case-folding is not a significant factor.

Example 
fmt.Printf("%Ts are identical: %t", Ne, Ne.Compare(Eq))

Output:

aci.ComparisonOperators are identical: false

func (ComparisonOperator) Context 

func (r ComparisonOperator) Context() string

Context returns the "name" of the ComparisonOperator const.

For example, if the receiver represents the Eq ComparisonOperator const, the returned string value shall be `Eq`.

If the receiver is bogus, or describes an unknown ComparisonOperator value, the default go-stackage tag "<invalid_operator>" is returned.

See the ComparisonOperator const definitions for details.

Example

This example demonstrates the use of the Context method to show all the context name for all ComparisonOperator constants. 

for _, cop := range []ComparisonOperator{
	Eq, Ne, Lt, Gt, Le, Ge,
} {
	fmt.Printf("%s\n", cop.Context())
}

Output:

Eq
Ne
Lt
Gt
Le
Ge

func (ComparisonOperator) Description 

func (r ComparisonOperator) Description() string

Description returns a short description of the receiver instance's context.

For instance, if the receiver is the Eq ComparisonOperator const, the returned string value shall be `Equal To`.

If the receiver is bogus, or describes an unknown ComparisonOperator value, the default go-stackage tag "<invalid_operator>" is returned.

This method is largely for convenience, and many individuals may feel it only has any practical applications in the areas of documentation, diagram creation or some other similar activity.

However, a prudent cybersecurity expert may argue that this method can be used to aid in the (critical) area of proofreading newly-devised or modified access control statements. A person could very easily mistake >= and <=, certainly if they're not paying attention. One such mistake could spell disaster.

Additionally, use of this method as a means to auto-generate Instruction comments (for LDIF configurations, or similar) can greatly help an admin more easily READ and UNDERSTAND the statements in question.

See the ComparisonOperator const definitions for details.

Example

This example demonstrates the use of the Description method to show all descriptive text for all ComparisonOperator constants. 

for _, cop := range []ComparisonOperator{
	Eq, Ne, Lt, Gt, Le, Ge,
} {
	fmt.Printf("%s\n", cop.Description())
}

Output:

Equal To
Not Equal To
Less Than
Greater Than
Less Than Or Equal
Greater Than Or Equal

func (ComparisonOperator) String 

func (r ComparisonOperator) String() string

String wraps go-stackage's ComparisonOperator.String method. This will return the comparison operator character(s) required by the ACIv3 syntax for a particular expressive statement.

For example, if the receiver is the Eq ComparisonOperator const, the returned string value shall be `=`.

If the receiver is bogus, or describes an unknown ComparisonOperator value, the default go-stackage tag "<invalid_operator>" is returned.

See the ComparisonOperator const definitions for details.

Example

This example demonstrates the string representation for all known ComparisonOperator constants. 

for _, cop := range []ComparisonOperator{
	Eq, Ne, Lt, Gt, Le, Ge,
} {
	fmt.Printf("%s\n", cop)
}

Output:

=
!=
<
>
<=
>=

func (ComparisonOperator) Valid 

func (r ComparisonOperator) Valid() (err error)

Valid returns an error instance following the process of verifying the receiver to be a known ComparisonOperator instance. This does NOT, however, imply feasibility of use with any particular type in the creation of BindRule or TargetRule instances.

Example 
var unknown ComparisonOperator = ComparisonOperator(12)
fmt.Printf("Is a known %T: %t", unknown, unknown.Valid() == nil)

Output:

Is a known aci.ComparisonOperator: false

type Day 

type Day uint8

Day represents the numerical abstraction of a single day of the week, such as Sunday (1). 

const (
	Sun  Day = 1 << iota // 1
	Mon                  // 2
	Tues                 // 4
	Wed                  // 8
	Thur                 // 16
	Fri                  // 32
	Sat                  // 64
)

Day constants can be shifted into an instance of DayOfWeek, allowing effective expressions such as "Sun,Tues". See the DayOfWeek.Set method.

func (Day) Compare 

func (r Day) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
fmt.Printf("Hashes are equal: %t", Thur.Compare(Sat))

Output:

Hashes are equal: false

func (Day) String 

func (r Day) String() (day string)

String is a stringer method that returns a single string name value for receiver instance of Day.

Example 
fmt.Printf("%s", Sat)

Output:

Sat

type DayOfWeek 

type DayOfWeek shifty.BitValue // 8-bit

DayOfWeek is a type alias of shifty.BitValue, and is used to construct a dayofweek BindRule.

func DoW 

func DoW(x ...any) (d DayOfWeek)

DoW initializes, shifts and returns a new instance of DayOfWeek in one shot. This function an alternative to separate assignment and set procedures.

Example 
fmt.Printf("%s", DoW(Thur, Sat))

Output:

Thur,Sat

func (DayOfWeek) BRM 

func (r DayOfWeek) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var dow DayOfWeek
fmt.Printf("%d available comparison operator methods", dow.BRM().Len())
// 2 available comparison operator methods

func (DayOfWeek) Compare 

func (r DayOfWeek) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) DayOfWeek instances using the Compare method. 

d1 := DoW(Thur, `Sat`, 1)
d2 := DoW(Thur, `saturday`, 1)

fmt.Printf("Hashes are equal: %t", d1.Compare(d2))

Output:

Hashes are equal: true

func (DayOfWeek) Eq 

func (r DayOfWeek) Eq() (b BindRule)

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To the `dayofweek` Bind keyword context.

Example 
var d DayOfWeek
d.Shift(Sat)
d.Shift(Thur)
fmt.Printf("%s", d.Eq())

Output:

dayofweek = "Thur,Sat"

func (DayOfWeek) IsZero 

func (r DayOfWeek) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var d DayOfWeek
fmt.Printf("Zero: %t", d.IsZero())

Output:

Zero: true

func (DayOfWeek) Keyword 

func (r DayOfWeek) Keyword() Keyword
Example 
var d DayOfWeek
fmt.Printf("Keyword: %s", d.Keyword())

Output:

Keyword: dayofweek

func (DayOfWeek) Len 

func (r DayOfWeek) Len() int

Len returns the abstract integer length of the receiver, quantifying the number of Day instances currently being expressed. For example, if the receiver instance has its Mon and Fri Day bits enabled, this would represent an abstract length of two (2).

Example 
var d DayOfWeek = DoW(Thur, `Sat`, 1)
fmt.Printf("%d", d.Len())

Output:

3

func (DayOfWeek) Ne 

func (r DayOfWeek) Ne() (b BindRule)

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To the `dayofweek` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example 
var d DayOfWeek
d.Shift(Mon)
d.Shift(Tues)
fmt.Printf("%s", d.Ne())

Output:

dayofweek != "Mon,Tues"

func (DayOfWeek) Positive 

func (r DayOfWeek) Positive(x Day) (posi bool)

Positive wraps go-shifty's BitValue.Positive method.

Example 
var d DayOfWeek = DoW(Thur, `Sat`, 1)
fmt.Printf("Saturday is set: %t", d.Positive(Sat))

Output:

Saturday is set: true

func (*DayOfWeek) Shift 

func (r *DayOfWeek) Shift(x Day) DayOfWeek

Shift wraps go-shifty's BitValue.Shift method.

Example 
var d DayOfWeek
d.Shift(Mon)
d.Shift(Tues)
fmt.Printf("%s", d)

Output:

Mon,Tues

func (DayOfWeek) String 

func (r DayOfWeek) String() (s string)

String is a stringer method that returns the string representation of the receiver instance. At least one Day's bits should register as positive in order for a valid string return to ensue.

Example 
var d DayOfWeek = DoW(Thur, `Sat`, 1)
fmt.Printf("%s", d)

Output:

Sun,Thur,Sat

func (*DayOfWeek) Unshift 

func (r *DayOfWeek) Unshift(x Day) DayOfWeek

Unshift wraps go-shifty's BitValue.Unshift method.

Example 
var d DayOfWeek
d.Shift(Mon)
d.Shift(Tues)
d.Unshift(Mon)
fmt.Printf("%s", d)

Output:

Tues

func (DayOfWeek) Valid 

func (r DayOfWeek) Valid() (err error)

Valid returns a Boolean value indicative of whether the receiver contains one or more valid bits representing known Day values. At least one Day must be positive within the receiver.

Example 
var d DayOfWeek
fmt.Printf("Valid: %t", d.Valid() == nil)

Output:

Valid: false

type DistinguishedNameContext 

type DistinguishedNameContext interface {
	Len() int
	String() string
	Kind() string
	Compare(any) bool
	Keyword() Keyword
	IsZero() bool
	Valid() error
	// contains filtered or unexported methods
}

DistinguishedNameContext is a convenient interface type that is qualified by the following types:

• LDAPURI (as its only required parameter is a BindDistinguishedName)

• BindDistinguishedName

• TargetDistinguishedName

The qualifying methods shown below are intended to make the generalized handling of distinguished names slightly easier without an absolute need for type assertion at every step. These methods are inherently read-only in nature and may not always return meaningful values depending on the underlying type.

To alter the underlying value, or to gain access to all of a given type's methods, type assertion of qualifying instances shall be necessary.

type FQDN 

type FQDN struct {
	// contains filtered or unexported fields
}

FQDN contains ordered domain labels that form a fully-qualified domain name.

func DNS 

func DNS(label ...string) FQDN

DNS initializes, sets and returns a new instance of FQDN in one shot. This function is an alternative to separate assignment and set procedures.

Example

This example demonstrates the creation of an instance of FQDN, which is used in a variety of contexts.

In this example, a string name is fed to the package level IP function to form a complete FQDN instance, which is then shown in string representation. 

i := DNS(`example.com`)
fmt.Printf("%s", i)

Output:

example.com

func (FQDN) BRM 

func (r FQDN) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var host FQDN
host.Set(`www.example.com`)
cops := host.BRM()
fmt.Printf("%T allows Eq: %t", host, cops.Contains(`=`))

Output:

aci.FQDN allows Eq: true

func (FQDN) Compare 

func (r FQDN) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) FQDN instances using the Compare method. 

addr1 := DNS(`www`, `example`, `com`)
addr2 := DNS(`www.example.com`)

fmt.Printf("Hashes are equal: %t", addr1.Compare(addr2))

Output:

Hashes are equal: true

func (FQDN) Eq 

func (r FQDN) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To the `dns` Bind keyword context.

Example 
var f FQDN = DNS()

// Can be set incrementally ...
f.Set(`www`)
f.Set(`example`)
f.Set(`com`)

// OR as a whole value ...
// f.Set(`www.example.com`)

fmt.Printf("%s", f.Eq())

Output:

dns = "www.example.com"
Example (OneShot) 
fmt.Printf("%s", DNS(`www`, `example`, `com`).Eq())

Output:

dns = "www.example.com"

func (FQDN) IsZero 

func (r FQDN) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example

This example demonstrates a check of the receiver for "nilness". 

fmt.Printf("%t", DNS(`www.www.www.www.www.example.com`).IsZero())

Output:

false

func (FQDN) Keyword 

func (r FQDN) Keyword() Keyword

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a BindRule containing the receiver instance as the expression value.

Example

This example demonstrates the use of the useless Keyword method, as FQDN instances do not have any knowledge of Keywords at this time. 

fmt.Printf("%v", DNS(`example.com`).Keyword())

Output:

dns

func (FQDN) Len 

func (r FQDN) Len() int

Len returns the abstract integer length of the receiver. The value returned represents the number of valid DNS labels within a given instance of FQDN. For example, `www.example.com` has three (3) such labels.

Example 
var host FQDN
host.Set(`www`)
host.Set(`example`)
host.Set(`com`)
//host.Set(`www.example.com`)	// same!

fmt.Printf("%T contains %d DNS labels", host, host.Len())

Output:

aci.FQDN contains 3 DNS labels

func (FQDN) Ne 

func (r FQDN) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To the `dns` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example 
var f FQDN = DNS()

// Can be set incrementally ...
f.Set(`www`)
f.Set(`example`)
f.Set(`com`)

// OR as a whole value ...
// f.Set(`www.example.com`)

fmt.Printf("%s", f.Ne())

Output:

dns != "www.example.com"

func (*FQDN) Set 

func (r *FQDN) Set(label ...string) *FQDN

Set appends one or more domain labels to the receiver. The total character length of a single label CANNOT exceed sixty-three (63) characters. When added up, all domain label instances present within the receiver SHALL NOT collectively exceed two hundred fifty-three (253) characters.

Valid characters within labels:

• a-z

• A-Z

• 0-9

• Hyphen ('-', limited to [1:length-1] slice range)

• Asterisk ('*', use with care for wildcard DNS-based ACI Bind Rule expressions)

• Full Stop ('.', see below for remarks on this character)

Users need not enter full stops (.) manually, given this method supports the use of variadic expressions, i.e.: 

Set(`www`,`example`,`com`)

However, should full stops (.) be used within input values: 

Set(`www.example.com`)

... the parser shall split the input into label components and add them to the receiver piecemeal in the intended order.

Please note that it is not necessary to include a NULL terminating full stop character (.) at the end (TLD?) of the intended FQDN

Example 
var i FQDN
i.Set(`*`).Set(`example`).Set(`com`)
fmt.Printf("%s", i)

Output:

*.example.com

func (FQDN) String 

func (r FQDN) String() string

String is a stringer method that returns the string representation of a fully-qualified domain name.

Example

This example demonstrates the string representation of the receiver instance. 

fmt.Printf("%s", DNS(`example.com`))

Output:

example.com

func (FQDN) Valid 

func (r FQDN) Valid() (err error)

Valid returns a Boolean value indicative of whether the receiver contents represent a legal fully-qualified domain name value.

Example

This example demonstrates a check of the receiver for an aberrant state. 

i := DNS(``)
fmt.Printf("Valid: %t", i.Valid() == nil)

Output:

Valid: false

type IPAddr 

type IPAddr struct {
	// contains filtered or unexported fields
}

IPAddr embeds slices of address values, allowing simple composition of flexible IP-based Bind Rule conditions.

func IP 

func IP(addr ...string) IPAddr

IP initializes, sets and returns a new instance of IPAddr in one shot. This function is an alternative to separate assignment and set procedures.

Example

This example demonstrates the creation of an instance of IPAddr, which is used in a variety of contexts.

In this example, a string name is fed to the package level IP function to form a complete IPAddr instance, which is then shown in string representation. 

ip := IP(`10.0.0.1`)
fmt.Printf("%s", ip)

Output:

10.0.0.1

func (IPAddr) BRM 

func (r IPAddr) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var address IPAddr
address.Set(`192.168.0`)
cops := address.BRM()
fmt.Printf("%T allows Eq: %t", address, cops.Contains(`=`))

Output:

aci.IPAddr allows Eq: true

func (IPAddr) Compare 

func (r IPAddr) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) IPAddr instances using the Compare method. 

addr1 := IP(`10.1.,192.168.`)
addr2 := IP(`10.1.,192.168.1.`)

fmt.Printf("Hashes are equal: %t", addr1.Compare(addr2))

Output:

Hashes are equal: false

func (IPAddr) Eq 

func (r IPAddr) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To the `ip` Bind keyword context.

Example 
var i IPAddr
i.Set(`192.8.`).Set(`10.7.0`)

fmt.Printf("%s", i.Eq())

Output:

ip = "192.8.,10.7.0"
Example (OneShot) 
fmt.Printf("%s", IP(`192.168.0`, `12.3.45.*`, `10.0.0.0/8`).Eq())

Output:

ip = "192.168.0,12.3.45.*,10.0.0.0/8"

func (IPAddr) IsZero 

func (r IPAddr) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is considered nil, or unset.

Example

This example demonstrates a check of the receiver for "nilness". 

fmt.Printf("%t", IP(`192.168.7.*,10.,172.12.*,8.8.8.8`).IsZero())

Output:

false

func (IPAddr) Keyword 

func (r IPAddr) Keyword() Keyword

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a BindRule containing the receiver instance as the expression value.

Example

This example demonstrates the use of the useless Keyword method, as IPAddr instances do not have any knowledge of Keywords at this time. 

fmt.Printf("%v", IP(`10.0`).Keyword())

Output:

ip

func (IPAddr) Kind 

func (r IPAddr) Kind() string

Kind returns the string representation of the receiver's kind.

Example

This example demonstrates the use of the useless Kind method, as this information is normally derived from a Keyword, which the receiver does not have. 

fmt.Printf("%s", IP(`192.168.1`).Kind())

Output:

ip

func (IPAddr) Len 

func (r IPAddr) Len() int

Len returns the integer length of the receiver instance.

Example

This example demonstrates the use of the useless Len method, as this information is only made available to satisfy Go's interface signature requirements as they pertain to the IPAddrContext interface. 

fmt.Printf("%d", IP(`10.8.`).Len())

Output:

1

func (IPAddr) Ne 

func (r IPAddr) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To the `ip` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example 
var i IPAddr
i.Set(`10.8.`)

fmt.Printf("%s", i.Ne())

Output:

ip != "10.8."

func (*IPAddr) Set 

func (r *IPAddr) Set(addr ...string) *IPAddr

Set assigns the provided address component to the receiver and returns the receiver instance in fluent-form.

Multiple values can be provided in variadic form, or piecemeal.

Example 
var i IPAddr
i.Set(`192.168.0`).Set(`12.3.45.*`).Set(`10.0.0.0/8`)
neq := i.Ne()
neq.Paren()
fmt.Printf("%s", neq)

Output:

( ip != "192.168.0,12.3.45.*,10.0.0.0/8" )

func (IPAddr) String 

func (r IPAddr) String() string

String is a stringer method that returns the string representation of an IP address.

Example

This example demonstrates the string representation of the receiver instance. 

fmt.Printf("%s", IP(`192.168.56.7`))

Output:

192.168.56.7

func (IPAddr) Valid 

func (r IPAddr) Valid() error

Valid returns an error indicative of whether the receiver is in an aberrant state.

Example

This example demonstrates a check of the receiver for an aberrant state. 

ip := IP(``)
fmt.Printf("Valid: %t", ip.Valid() == nil)

Output:

Valid: false

type Inheritance 

type Inheritance struct {
	// contains filtered or unexported fields
}

Inheritance describes an inherited BindRule syntax, allowing access control over child entry enumeration below the specified parent.

func Inherit 

func Inherit(x AttributeBindTypeOrValue, lvl ...any) Inheritance

Inherit creates a new instance of Inheritance bearing the provided AttributeBindTypeOrValue instance, as well as zero (0) or more Level instances for shifting.

Example (GAT) 
attr := AT(`owner`)
gat := GAT(attr, USERDN)
inh := Inherit(gat, 3, 4)
fmt.Printf("%s", inh.Eq())

Output:

groupattr = "parent[3,4].owner#USERDN"
Example (UAT) 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
fmt.Printf("%s", inh.Eq())

Output:

userattr = "parent[1,3].manager#uid=frank,ou=People,dc=example,dc=com"
Example (USERDN) 
attr := AT(`manager`)
uat := UAT(attr, AV(`USERDN`))
inh := Inherit(uat, 0, 1, 2, 8)
fmt.Printf("%s", inh.Eq())

Output:

userattr = "parent[0,1,2,8].manager#USERDN"

func (Inheritance) BRM 

func (r Inheritance) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
brm := inh.BRM()
fmt.Printf("%d available comparison operator methods", brm.Len())

Output:

2 available comparison operator methods

func (Inheritance) Compare 

func (r Inheritance) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) Inheritance instances using the Compare method. 

attr := AT(`owner`)
gat := GAT(attr, USERDN)
inh1 := Inherit(gat, 3, 4)

attr = AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh2 := Inherit(uat, 1, 3)

fmt.Printf("Hashes are equal: %t", inh1.Compare(inh2))

Output:

Hashes are equal: false

func (Inheritance) Eq 

func (r Inheritance) Eq() (b BindRule)

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To the `userattr` or `groupattr` Bind keyword context.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
fmt.Printf("%s", inh.Eq())

Output:

userattr = "parent[1,3].manager#uid=frank,ou=People,dc=example,dc=com"

func (Inheritance) IsZero 

func (r Inheritance) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver instance is nil, or unset.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
fmt.Printf("%t", inh.IsZero())

Output:

false

func (Inheritance) Keyword 

func (r Inheritance) Keyword() (kw Keyword)

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned will be either BindUAT or BindGAT.

Example 
var inh Inheritance

//fmt.Printf("Keyword found: %t", inh.Keyword().String() != ``)
// Would return: Keyword found: false

attr := AT(`manager`)
// we'll use the userattr keyword (bestowed
// by UAT), and for a value we'll just give
// it an explicit bind type (USERDN). If it
// is preferable to use groupattr keyword,
// simply supplant UAT with GAT func.
uat := UAT(attr, USERDN)
inh = Inherit(uat, 6, 7) // levels 6 & 7

fmt.Printf("Keyword: %s", inh.Keyword())

Output:

Keyword: userattr

func (Inheritance) Len 

func (r Inheritance) Len() int

Len returns the abstract integer length of the receiver, quantifying the number of Level instances currently being expressed. For example, if the receiver instance has its Level1 and Level5 bits enabled, this would represent an abstract length of two (2).

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
fmt.Printf("Number of levels: %d", inh.Len())

Output:

Number of levels: 2

func (Inheritance) Ne 

func (r Inheritance) Ne() (b BindRule)

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To the `userattr` or `groupattr` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
fmt.Printf("%s", inh.Ne())

Output:

userattr != "parent[1,3].manager#uid=frank,ou=People,dc=example,dc=com"

func (Inheritance) Positive 

func (r Inheritance) Positive(x any) (posi bool)

Positive wraps go-shifty's BitValue.Positive method.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
fmt.Printf("Level 5 positive? %t", inh.Positive(5))

Output:

Level 5 positive? false
Example (ByString) 
attr := AT(`manager`)
// we'll use the userattr keyword (bestowed
// by UAT), and for a value we'll just give
// it an explicit bind type (USERDN). If it
// is preferable to use groupattr keyword,
// simply supplant UAT with GAT func.
uat := UAT(attr, USERDN)
inh := Inherit(uat, 6, 7) // levels 6 & 7
fmt.Printf("Level 6 positive? %t", inh.Positive(`6`))

Output:

Level 6 positive? true

func (Inheritance) Shift 

func (r Inheritance) Shift(x ...any) Inheritance

Shift wraps go-shifty's BitValue.Shift method.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
inh.Shift(7) // add one more we forgot

fmt.Printf("Number of levels: %d", inh.Len())

Output:

Number of levels: 3

func (Inheritance) String 

func (r Inheritance) String() (s string)

String is a stringer method that returns the string name value for receiver instance of Inheritance.

The return value(s) are enclosed within square-brackets, followed by comma delimitation and are prefixed with "parent" before being returned.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3)
fmt.Printf("%s", inh)

Output:

parent[1,3].manager#uid=frank,ou=People,dc=example,dc=com

func (Inheritance) Unshift 

func (r Inheritance) Unshift(x ...any) Inheritance

Unshift wraps go-shifty's BitValue.Unshift method.

Example 
attr := AT(`manager`)
uat := UAT(attr, AV(`uid=frank,ou=People,dc=example,dc=com`))
inh := Inherit(uat, 1, 3, 8)
inh.Unshift(1)      // we changed our mind
inh.Unshift(`1`)    // alternatively
inh.Unshift(Level1) // alternatively

fmt.Printf("Number of levels: %d", inh.Len())

Output:

Number of levels: 2

func (Inheritance) Valid 

func (r Inheritance) Valid() (err error)

Valid returns an error indicative of whether the receiver is in an aberrant state.

Example 
var inh Inheritance
fmt.Printf("%T.Valid: %t", inh, inh.Valid() == nil)

Output:

aci.Inheritance.Valid: false

type Instruction 

type Instruction struct {
	// contains filtered or unexported fields
}

Instruction conforms to the ACI syntax specification associated with the Version constant value of this package.

Instances of this type, when represented in their string form, are intended for submission to an X.500/LDAP DSA for assignment (via the 'aci' LDAP Attribute Type) to the relevant directory entry.

Example (Build) 
// Make a target rule that encompasses any account
// with a DN syntax of "uid=<userid>,ou=People,dc=example,dc=com"
C := TDN(`uid=*,ou=People,dc=example,dc=com`).Eq()

// push into a new instance of Rule automatically
// configured to store Target Rule Condition instances.
tgt := TRs(C).Push(C)

// define a timeframe for our PermissionBindRule
// using two Condition instances
notBefore := ToD(`1730`).Ge()                    // Condition: greater than or equal to time
notAfter := ToD(`2400`).Lt()                     // Condition: less than time
brule := And().Paren().Push(notBefore, notAfter) // our actual bind rule expression

// Define the permission (rights).
perms := Allow(ReadAccess, CompareAccess, SearchAccess)

// Make our PermissionBindRule instance, which defines the
// granting of access within a particular timeframe.
pbrule := PBR(perms, brule)

// The ACI's effective name (should be unique within the directory)
acl := `Limit people access to timeframe`

// Finally, craft the Instruction instance
var i Instruction
i.Set(acl, tgt, pbrule)

fmt.Printf("%s", i)

Output:

( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" );)
Example (BuildNested) 
// Make a target rule that encompasses any account
// with a DN syntax of "uid=<userid>,ou=People,dc=example,dc=com"
C := TDN(`uid=*,ou=People,dc=example,dc=com`).Eq()

// push into a new instance of Rule automatically
// configured to store Target Rule Condition instances.
tgt := TRs().Push(C)

// create an ORed stack, pushing the two specified
// userdn equality conditions into its collection.
ors := Or().Paren().Push(
	UDN(`uid=jesse,ou=admin,dc=example,dc=com`).Eq(),
	UDN(`uid=courtney,ou=admin,dc=example,dc=com`).Eq(),
)

// create our AttributeBindTypeOrValue instance,
// setting the AttributeType as `ninja`, and the
// AttributeValue as `FALSE`
attr := AT(`ninja`)       // attributeType
aval := AV(`FALSE`)       // attributeValue
userat := UAT(attr, aval) // attributeBindTypeOrValue

// create a negated (NOT) stack, pushing
// our AttributeBindTypeOrValue BindRule
// (Eq()) instance into its collection.
// Also, make stack parenthetical.
nots := Not().Paren().Push(userat.Eq())

// define a timeframe for our PermissionBindRule
// using two Condition instances. Make both AND
// stacks parenthetical, and push our OR and NOT
// stacks defined above.
brule := And().Paren().Push(
	And().Paren().Push(
		ToD(`1730`).Ge(), // Condition: greater than or equal to time
		ToD(`2400`).Lt(), // Condition: less than time
	),
	ors,
	nots,
)

// Define the permission (rights).
perms := Allow(ReadAccess, CompareAccess, SearchAccess)

// Make our PermissionBindRule instance, which defines the
// granting of access within a particular timeframe.
pbr := PBR(perms, brule)

// The ACI's effective name (should be unique within the directory)
acl := `Limit people access to timeframe`

// Finally, craft the Instruction instance
var i Instruction
i.Set(acl, tgt, pbr)

fmt.Printf("%s", i)

Output:

( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( ( timeofday >= "1730" AND timeofday < "2400" ) AND ( userdn = "ldap:///uid=jesse,ou=admin,dc=example,dc=com" OR userdn = "ldap:///uid=courtney,ou=admin,dc=example,dc=com" ) AND NOT ( userattr = "ninja#FALSE" ) );)

func ACI 

func ACI(x ...any) Instruction

ACI initializes, (optionally) sets and returns a new instance of the Instruction type.

Input values must conform to the following specifications per the intended field within the return instance:

• A non-zero string value shall be used for the effective Name, or "ACL"

• One (1) or more non-zero and unique PermissionBindRule instances

• One (1) or more non-zero and unique Condition instances bearing the `target` categorical label

Please note the following constraints for the name of the receiver:

• Value cannot be reset (i.e.: renamed)

• Value should not contain the "version <float>" statement, as that is imposed automatically during string representation procedures

Example

This example demonstrates use of the ACI package-level function. An instance of Instruction is created using manually assembled type instances. 

t := TDN(`uid=*,ou=People,dc=example,dc=com`).Eq()
tgt := TRs().Push(t)

userat := UAT(
	AT(`ninja`),
	AV(`FALSE`),
)

ors := Or().Paren().Push(
	UDN(`uid=jesse,ou=admin,dc=example,dc=com`).Eq(),
	UDN(`uid=courtney,ou=admin,dc=example,dc=com`).Eq(),
)

nots := Not().Paren().Push(userat.Eq())
brule := And().Paren().Push(
	Timeframe(
		ToD(`1730`),
		ToD(`2400`),
	).Paren(),
	ors,
	nots,
)

perms := Allow(
	ReadAccess,
	SearchAccess,
	CompareAccess,
)

pbr := PBR(perms, brule)
acl := `Limit people access to timeframe`

var i Instruction
i.Set(acl, tgt, pbr)

fmt.Printf("%s", i)

Output:

( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( ( timeofday >= "1730" AND timeofday < "2400" ) AND ( userdn = "ldap:///uid=jesse,ou=admin,dc=example,dc=com" OR userdn = "ldap:///uid=courtney,ou=admin,dc=example,dc=com" ) AND NOT ( userattr = "ninja#FALSE" ) );)

func (Instruction) ACL 

func (r Instruction) ACL() (acl string)

ACL returns the access control label of the receiver, else a zero string if unset.

Example 
var i Instruction
acl := `This is an access control label`
i.Set(acl)
fmt.Printf("%s", i.ACL())

Output:

This is an access control label

func (Instruction) IsZero 

func (r Instruction) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var i Instruction
fmt.Printf("Zero: %t", i.IsZero())

Output:

Zero: true

func (Instruction) PBRs 

func (r Instruction) PBRs() (pbrs PermissionBindRules)

PBRs returns the PermissionBindRules found within the underlying receiver instance. Note that a bogus Rule is returned if the receiver is nil, or unset.

Example 
t := TDN(`uid=*,ou=People,dc=example,dc=com`).Eq()
tgt := TRs().Push(t)

userat := UAT(AT(`ninja`), AV(`FALSE`))
ors := Or().Paren().Push(
	UDN(`uid=jesse,ou=admin,dc=example,dc=com`).Eq(),
	UDN(`uid=courtney,ou=admin,dc=example,dc=com`).Eq(),
)
nots := Not().Paren().Push(userat.Eq())
brule := And().Paren().Push(
	Timeframe(
		ToD(`1730`),
		ToD(`2400`),
	).Paren(),
	ors,
	nots,
)

perms := Allow(
	ReadAccess,
	SearchAccess,
	CompareAccess,
)

pbr := PBR(perms, brule)
acl := `Limit people access to timeframe`

var i Instruction
i.Set(acl, tgt, pbr)

fmt.Printf("%s", i.PBRs())

Output:

allow(read,search,compare) ( ( timeofday >= "1730" AND timeofday < "2400" ) AND ( userdn = "ldap:///uid=jesse,ou=admin,dc=example,dc=com" OR userdn = "ldap:///uid=courtney,ou=admin,dc=example,dc=com" ) AND NOT ( userattr = "ninja#FALSE" ) );

func (*Instruction) Parse 

func (r *Instruction) Parse(raw string) (err error)

Parse wraps go-antlraci's ParseInstruction package-level function, writing data into the receiver, or returning a non-nil instance of error if processing should fail.

WARNING: Note that the act of successfully parsing an ACIv3 instruction statement will clobber (overwrite) all of the contents present within the receiver, if any.

Example

This example demonstrates a basic parse of an ACIv3 instruction in string representation into a proper instance of Instruction using the Parse method. 

raw := `( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" ); )`

// define a variable into which the
// parser shall deposit data
var ins Instruction
if err := ins.Parse(raw); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%s", ins)

Output:

( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" );)

func (*Instruction) Set 

func (r *Instruction) Set(x ...any) *Instruction

Set assigns one (1) or more values to the receiver. The input value(s) must conform to the following conditions:

• If the value is a string, it shall become the immutable name (or "ACL") of a given Instruction instance; this value cannot be changed once set

• If the value is a TargetRule instance, it shall be appended to the receiver's TargetRules instance

• If the value is a TargetRules instance, it shall have all stack slice members appended to the receiver's TargetRules instance

• If the value is a PermissionBindRule, and if it is valid (i.e.: contains exactly one (1) valid Permission statement and exactly one (1) BindRules), it shall be appended to the receiver's PermissionBindRules stack

Example 
var i Instruction
acl := `This is an access control label`
i.Set(acl)
fmt.Printf("%s", i.ACL())

Output:

This is an access control label

func (Instruction) String 

func (r Instruction) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example 
t := TDN(`uid=*,ou=People,dc=example,dc=com`).Eq()
tgt := TRs().Push(t)

userat := UAT(AT(`ninja`), AV(`FALSE`))
ors := Or().Paren().Push(
	UDN(`uid=jesse,ou=admin,dc=example,dc=com`).Eq(),
	UDN(`uid=courtney,ou=admin,dc=example,dc=com`).Eq(),
)
nots := Not().Paren().Push(userat.Eq())
brule := And().Paren().Push(
	Timeframe(
		ToD(`1730`),
		ToD(`2400`),
	).Paren(),
	ors,
	nots,
)

perms := Allow(
	ReadAccess,
	SearchAccess,
	CompareAccess,
)

pbr := PBR(perms, brule)
acl := `Limit people access to timeframe`

var i Instruction
i.Set(acl, tgt, pbr)

fmt.Printf("%s", i)

Output:

( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( ( timeofday >= "1730" AND timeofday < "2400" ) AND ( userdn = "ldap:///uid=jesse,ou=admin,dc=example,dc=com" OR userdn = "ldap:///uid=courtney,ou=admin,dc=example,dc=com" ) AND NOT ( userattr = "ninja#FALSE" ) );)

func (Instruction) TRs 

func (r Instruction) TRs() (trs TargetRules)

T returns the Target Rule found within the underlying receiver instance. Note that a bogus Rule is returned if the receiver is nil, or unset.

Example 
t := TDN(`uid=*,ou=People,dc=example,dc=com`).Eq()
tgt := TRs().Push(t)

userat := UAT(AT(`ninja`), AV(`FALSE`))
ors := Or().Paren().Push(
	UDN(`uid=jesse,ou=admin,dc=example,dc=com`).Eq(),
	UDN(`uid=courtney,ou=admin,dc=example,dc=com`).Eq(),
)
nots := Not().Paren().Push(userat.Eq())
brule := And().Paren().Push(
	Timeframe(
		ToD(`1730`),
		ToD(`2400`),
	).Paren(),
	ors,
	nots,
)

perms := Allow(
	ReadAccess,
	SearchAccess,
	CompareAccess,
)

pbr := PBR(perms, brule)
acl := `Limit people access to timeframe`

var i Instruction
i.Set(acl, tgt, pbr)

fmt.Printf("%s", i.TRs())

Output:

( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )

func (Instruction) Valid 

func (r Instruction) Valid() (err error)

Valid returns an instance of error that reflects any perceived errors or deficiencies within the receiver instance.

Example 
var i Instruction
fmt.Printf("Valid: %t", i.Valid() == nil)

Output:

Valid: false

type Instructions 

type Instructions stackage.Stack

Instructions is a go-stackage Stack alias type intended to store slices of Instruction instances.

Note that the concept of a "collection" of Instruction instances does not come from the ACIv3 syntax per se, and is implemented here merely for the user's convenience. Use of this type is not required in any scenario.

func ACIs 

func ACIs(x ...any) (i Instructions)

ACIs initializes, optionally sets and returns a new instance of Instructions configured to store valid Instruction instances.

Slice values are delimited using the newline rune (ASCII #10).

Example 
raw1 := `( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe for those ninjas"; allow(read,search,compare) ( ( timeofday >= "1730" AND timeofday < "2400" ) AND ( userdn = "ldap:///uid=jesse,ou=admin,dc=example,dc=com" OR userdn = "ldap:///uid=courtney,ou=admin,dc=example,dc=com" ) AND NOT ( userattr = "ninja#FALSE" ) );)`
raw2 := `( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" );)`

acis := ACIs(
	raw1,
	raw2,
)

fmt.Printf("%T contains %d Instruction instances", acis, acis.Len())

Output:

aci.Instructions contains 2 Instruction instances

func (Instructions) Contains 

func (r Instructions) Contains(x any) bool

Contains returns a Boolean value indicative of whether value x, if a string or Instruction instance, already resides within the receiver instance.

Case is not significant in the matching process.

Example

This example demonstrates doing a literal search for an ACI within a stack of ACIs using its Contains method. Case is not significant in the matching process. 

raw1 := `( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe for those ninjas"; allow(read,search,compare) ( ( timeofday >= "1730" AND timeofday < "2400" ) AND ( userdn = "ldap:///uid=jesse,ou=admin,dc=example,dc=com" OR userdn = "ldap:///uid=courtney,ou=admin,dc=example,dc=com" ) AND NOT ( userattr = "ninja#FALSE" ) );)`
raw2 := `( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" );)`

acis := ACIs(
	raw1,
	raw2,
)

fmt.Printf("%T contains raw1: %t", acis, acis.Contains(raw1))

Output:

aci.Instructions contains raw1: true

func (Instructions) F 

func (r Instructions) F() func(...any) Instruction

F returns the appropriate instance creator function for crafting individual Instruction instances for submission to the receiver. This is merely a convenient alternative to maintaining knowledge as to which function applies to the current receiver instance.

As there is only one possibility for instances of this design, the ACI function is returned.

Example

This example demonstrates use of the F method to obtain the package-level function appropriate for the creation of new stack elements. 

var acis Instructions
funk := acis.F()

ins := funk() // normally you'd want to supply some type instances
fmt.Printf("%T", ins)

Output:

aci.Instruction

func (Instructions) Index 

func (r Instructions) Index(idx int) (x Instruction)

Index wraps go-stackage's Stack.Index method. Note that the Boolean OK value returned by go-stackage by default will be shadowed and not obtainable by the caller.

Example 
raw := []string{
	`( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" );)`,
	`( targetfilter = "(&(objectClass=employee)(objectClass=engineering))" )( targetcontrol = "1.2.3.4" || "5.6.7.8" )( targetscope = "onelevel" )(version 3.0; acl "Allow read and write for anyone using greater than or equal 128 SSF - extra nesting"; allow(read,write) ( ( ( userdn = "ldap:///anyone" ) AND ( ssf >= "71" ) ) AND NOT ( dayofweek = "Wed" OR dayofweek = "Fri" ) ); deny(selfwrite,proxy) ( userdn = "ldap:///all" );)`,
}

ins := ACIs()
for i := 0; i < len(raw); i++ {
	ins.Push(raw[i])
}

fmt.Printf("%s", ins.Index(1))

Output:

( targetfilter = "(&(objectClass=employee)(objectClass=engineering))" )( targetcontrol = "1.2.3.4" || "5.6.7.8" )( targetscope = "onelevel" )(version 3.0; acl "Allow read and write for anyone using greater than or equal 128 SSF - extra nesting"; allow(read,write) ( ( ( userdn = "ldap:///anyone" ) AND ( ssf >= "71" ) ) AND NOT ( dayofweek = "Wed" OR dayofweek = "Fri" ) ); deny(selfwrite,proxy) ( userdn = "ldap:///all" );)

func (Instructions) IsZero 

func (r Instructions) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example 
var i Instructions
fmt.Printf("Zero: %t", i.IsZero())

Output:

Zero: true

func (Instructions) Len 

func (r Instructions) Len() int

Len wraps go-stackage's Stack.Len method.

Example 
var i Instructions
fmt.Printf("Length: %d", i.Len())

Output:

Length: 0

func (Instructions) Pop 

func (r Instructions) Pop() (x Instruction)

Pop wraps go-stackage's Stack.Pop method.

Example 
raw := []string{
	`( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" );)`,
	`( targetfilter = "(&(objectClass=employee)(objectClass=engineering))" )( targetcontrol = "1.2.3.4" || "5.6.7.8" )( targetscope = "onelevel" )(version 3.0; acl "Allow read and write for anyone using greater than or equal 128 SSF - extra nesting"; allow(read,write) ( ( ( userdn = "ldap:///anyone" ) AND ( ssf >= "71" ) ) AND NOT ( dayofweek = "Wed" OR dayofweek = "Fri" ) ); deny(proxy,selfwrite) ( userdn = "ldap:///all" );)`,
}

ins := ACIs()
for i := 0; i < len(raw); i++ {
	ins.Push(raw[i])
}

popped := ins.Pop()
fmt.Printf("%s", popped)

Output:

( targetfilter = "(&(objectClass=employee)(objectClass=engineering))" )( targetcontrol = "1.2.3.4" || "5.6.7.8" )( targetscope = "onelevel" )(version 3.0; acl "Allow read and write for anyone using greater than or equal 128 SSF - extra nesting"; allow(read,write) ( ( ( userdn = "ldap:///anyone" ) AND ( ssf >= "71" ) ) AND NOT ( dayofweek = "Wed" OR dayofweek = "Fri" ) ); deny(selfwrite,proxy) ( userdn = "ldap:///all" );)

func (Instructions) Push 

func (r Instructions) Push(x ...any) Instructions

Push wraps go-stackage's Stack.Push method. Only Instruction instances are permitted for push.

In the case of a string value, it is automatically cast as an instance of BindDistinguishedName using the appropriate keyword, so long as the raw string is of a non-zero length.

Example 
raw := []string{
	`( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" ); )`,
	`( targetfilter = "(&(objectClass=employee)(objectClass=engineering))" )( targetcontrol = "1.2.3.4" || "5.6.7.8" )( targetscope = "onelevel" )(version 3.0; acl "Allow read and write for anyone using greater than or equal 128 SSF - extra nesting"; allow(read,write) ( ( ( userdn = "ldap:///anyone" ) AND ( ssf >= "71" ) ) AND NOT ( dayofweek = "Wed" OR dayofweek = "Fri" ) ); deny(proxy,selfwrite) ( userdn = "ldap:///all" ); )`,
}

ins := ACIs()
for i := 0; i < len(raw); i++ {
	ins.Push(raw[i])
}
fmt.Printf("Length: %d", ins.Len())

Output:

Length: 2

func (Instructions) String 

func (r Instructions) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example 
raw := []string{
	`( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" ); )`,
	`( targetfilter = "(&(objectClass=employee)(objectClass=engineering))" )( targetcontrol = "1.2.3.4" || "5.6.7.8" )( targetscope = "onelevel" )(version 3.0; acl "Allow read and write for anyone using greater than or equal 128 SSF - extra nesting"; allow(read,write) ( ( ( userdn = "ldap:///anyone" ) AND ( ssf >= "71" ) ) AND NOT ( dayofweek = "Wed" OR dayofweek = "Fri" ) ); deny(proxy,selfwrite) ( userdn = "ldap:///all" ); )`,
}

ins := ACIs()
for i := 0; i < len(raw); i++ {
	ins.Push(raw[i])
}

fmt.Printf("%s", ins)

Output:

( target = "ldap:///uid=*,ou=People,dc=example,dc=com" )(version 3.0; acl "Limit people access to timeframe"; allow(read,search,compare) ( timeofday >= "1730" AND timeofday < "2400" );)
( targetfilter = "(&(objectClass=employee)(objectClass=engineering))" )( targetcontrol = "1.2.3.4" || "5.6.7.8" )( targetscope = "onelevel" )(version 3.0; acl "Allow read and write for anyone using greater than or equal 128 SSF - extra nesting"; allow(read,write) ( ( ( userdn = "ldap:///anyone" ) AND ( ssf >= "71" ) ) AND NOT ( dayofweek = "Wed" OR dayofweek = "Fri" ) ); deny(selfwrite,proxy) ( userdn = "ldap:///all" );)

func (Instructions) Valid 

func (r Instructions) Valid() (err error)

Valid wraps go-stackage's Stack.Valid method.

Example 
var i Instructions
fmt.Printf("Valid: %t", i.Valid() == nil)

Output:

Valid: false

type Keyword 

type Keyword interface {
	String() string
	Kind() string
}

Keyword describes the effective "type" within the context of a given Bind or Target Rule. The available keywords vary based on the rule type in which a given Keyword resides.

See the Keyword constants defined in this package for a complete list.

Example

This example demonstrates the interrogation of qualifiers of the Keyword interface type (BindKeyword and TargetKeyword const definitions).

There are a total of twenty (20) qualifying instances (spanning two (2) distinct types) of this interface. 

for idx, k := range []Keyword{
	BindUDN,
	BindRDN,
	BindGDN,
	BindUAT,
	BindGAT,
	BindIP,
	BindDNS,
	BindDoW,
	BindToD,
	BindAM,
	BindSSF,
	Target,
	TargetTo,
	TargetAttr,
	TargetCtrl,
	TargetFrom,
	TargetScope,
	TargetFilter,
	TargetAttrFilters,
	TargetExtOp,
} {
	fmt.Printf("[%s] %02d/%d: %s\n",
		k.Kind(), idx+1, 20, k)
}

Output:

[bind] 01/20: userdn
[bind] 02/20: roledn
[bind] 03/20: groupdn
[bind] 04/20: userattr
[bind] 05/20: groupattr
[bind] 06/20: ip
[bind] 07/20: dns
[bind] 08/20: dayofweek
[bind] 09/20: timeofday
[bind] 10/20: authmethod
[bind] 11/20: ssf
[target] 12/20: target
[target] 13/20: target_to
[target] 14/20: targetattr
[target] 15/20: targetcontrol
[target] 16/20: target_from
[target] 17/20: targetscope
[target] 18/20: targetfilter
[target] 19/20: targattrfilters
[target] 20/20: extop

type LDAPURI 

type LDAPURI struct {
	// contains filtered or unexported fields
}

LDAPURI contains the components of a fully-qualified LDAP Search URI, including:

• An LDAP Distinguished Name

• An LDAP Search Scope

• An AttributeBindTypeOrValue

• A comma-delimited list of AttributeType names

• An LDAP Search Filter

func URI 

func URI(x ...any) LDAPURI

URI initializes, (optionally) sets and returns a new instance of LDAPURI, which represents a fully-qualified LDAP Search URI of the following syntax: 

scheme:///<dn>?<at[,...]>?<scope>?<filter>

As a practical example: 

ldap:///ou=People,dc=example,dc=com?sn,cn,givenName?one?(objectClass=*)

URIs of this format are used within UDN (userdn) and GDN (groupdn) Bind Rules.

Additionally, the ACI syntax specification honored by this package allows the use of an AttributeBindTypeOrValue instance INSTEAD of a comma-delimited list of attributeTypes, a search scope and a search filter: 

scheme:///<dn>?<atbtv>

As a practical example: 

ldap:///ou=People,dc=example,dc=com?owner#GROUPDN

Be advised that only UAT (userattr) Bind Rules will make use of this particular URI format. An instance of AttributeBindTypeOrValue submitted as a URI component bearing the GAT (groupattr) bind keyword will have this keyword IGNORED in favor of UAT automatically.

Example 
dn := UDN(`ou=People,o=example`)
filter := Filter(`(objectClass=employee)`)
scope := Subtree

uri := URI(dn, filter, scope)

fmt.Printf("%s", uri)

Output:

ldap:///ou=People,o=example??sub?(objectClass=employee)

func (LDAPURI) BRM 

func (r LDAPURI) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var uri LDAPURI
fmt.Printf("%d available aci.BindRuleMethod instances", uri.BRM().Len())

Output:

2 available aci.BindRuleMethod instances

func (LDAPURI) Compare 

func (r LDAPURI) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) Inheritance instances using the Compare method. 

raw := `ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))`
uri1 := URI(raw)

raw = `ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?sub?(&(objectClass=distributionList)(status=active))`
uri2 := URI(raw)

fmt.Printf("Hashes are equal: %t", uri1.Compare(uri2))

Output:

Hashes are equal: false

func (LDAPURI) Eq 

func (r LDAPURI) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To one (1) of the following keyword contexts:

• `userdn` (Bind Rule)

• `userattr` (Bind Rule)

• `groupdn` (Bind Rule)

The appropriate keyword is automatically imposed based on the following scenarios:

• If an AttributeBindTypeOrValue (as created by UAT() package-level function) is set within the receiver, the keyword shall be BindUAT; this is regardless to the keyword assigned to the DistinguishedName instance.

• If an AttributeBindTypeOrValue is NOT set within the receiver, the keyword shall fallback to that which is found within the BindDistinguishedName assigned to the receiver; this keyword was set by the UDN() or GDN() package-level functions respectively during BindDistinguishedName creation.

Example 
dn := GDN(`ou=Groups,dc=example,dc=com`)
filter := Filter(`(&(objectClass=distributionList)(status=active))`)
attrs := UAs(`cn`, `sn`, `givenName`, `objectClass`, `uid`)
uri := URI(dn, attrs, filter, SingleLevel)

fmt.Printf("%s", uri.Eq())

Output:

groupdn = "ldap:///ou=Groups,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=distributionList)(status=active))"

func (LDAPURI) IsZero 

func (r LDAPURI) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var uri LDAPURI
fmt.Printf("Zero: %t", uri.IsZero())

Output:

Zero: true

func (LDAPURI) Keyword 

func (r LDAPURI) Keyword() (k Keyword)

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned will be one of the following:

• BindUDN

• BindGDN

• BindRDN

• BindUAT

• BindGAT

Which Keyword is actually used is determined by the underlying type instances that were used to assemble the receiver.

Example 
dn := GDN(`ou=Groups,dc=example,dc=com`)
filter := Filter(`(&(objectClass=distributionList)(status=active))`)
uri := URI(dn, filter)

fmt.Printf("Keyword: %s", uri.Keyword())

Output:

Keyword: groupdn

func (LDAPURI) Kind 

func (r LDAPURI) Kind() (k string)

Kind returns the string form of the receiver's Keyword, if the instance is valid.

Example 
dn := GDN(`ou=Groups,dc=example,dc=com`)
filter := Filter(`(&(objectClass=distributionList)(status=active))`)
uri := URI(dn, filter)

fmt.Printf("Keyword: %s", uri.Keyword())

Output:

Keyword: groupdn

func (LDAPURI) Len 

func (r LDAPURI) Len() int

Len performs no useful task, as the concept of integer length does not apply to the LDAPURI type in this context. Execution of this method shall always return zero (0).

This method exists solely to allow the receiver to qualify for the DistinguishedNameContext interface signature.

Example 
dn := GDN(`ou=Groups,dc=example,dc=com`)
filter := Filter(`(&(objectClass=distributionList)(status=active))`)
uri := URI(dn, filter)

fmt.Printf("Len: %d", uri.Len())

Output:

Len: 0

func (LDAPURI) Ne 

func (r LDAPURI) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To one (1) of the following keywords:

• `userdn` (Bind Rule)

• `userattr` (Bind Rule)

• `groupdn` (Bind Rule)

The appropriate keyword is automatically imposed based on the following scenarios:

• If an AttributeBindTypeOrValue (as created by UAT() package-level function) is set within the receiver, the keyword shall be BindUAT; this is regardless to the keyword assigned to the DistinguishedName instance.

• If an AttributeBindTypeOrValue is NOT set within the receiver, the keyword shall fallback to that which is found within the BindDistinguishedName assigned to the receiver; this keyword was set by the UDN() or GDN() package-level functions respectively during BindDistinguishedName creation.

Negated equality BindRule instances should be used with caution.

Example 
raw := `ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))`
uri := URI(raw)
fmt.Printf("%s", uri.Ne())

Output:

userdn != "ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))"

func (*LDAPURI) Parse 

func (r *LDAPURI) Parse(raw string) (err error)

Parse is a convenient alternative to building the receiver instance using individual instances of the needed types. This method does not use go-antlraci.

An error is returned if the parsing attempt fails for some reason. If successful, the receiver pointer is updated (clobbered) with new information.

Example 
raw := `ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))`

var uri LDAPURI
if err := uri.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("%s", uri)

Output:

ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))

func (*LDAPURI) Set 

func (r *LDAPURI) Set(x ...any) LDAPURI

Set assigns the provided instances to the receiver. The order in which instances are assigned to the receiver is immaterial. The semantics of type instance assignment are as follows:

• An instance of BindDistinguishedName will be set as the URI DN; this is ALWAYS required. Valid DN creator functions are UDN (userdn), and GDN (groupdn) for instances of this type.

• An instance of SearchScope shall be set as the URI Search Scope

• An instance of AttributeBindTypeOrValue shall be set as a component within the receiver. Please see a special remark below related to the use of instances of this type within LDAP URIs.

• An instance of AttributeTypes (created using the UAs package-level function) shall be set as the URI attribute(s) list.

• An instance of SearchFilter shall be set as the URI Search Filter. Please see a special remark below related to the use of instances of this type within LDAP URIs.

• An instance of string (with no other arguments) shall result in an LDAP URI parse operation that, if successful, shall overwrite the receiver in its entirety. This should not be combined with other types of input values as the results will not be compounded.

When an AttributeBindTypeOrValue is specified, an LDAP Search Filter MUST NOT BE SET, as it will supercede the AttributeBindTypeOrValue instance during string representation.

In short, choose:

• DN and AttributeType(s), Scope, Filter

... OR ...

• DN and AttributeBindTypeOrValue

Example 
var uri LDAPURI
uri.Set(`ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))`)
fmt.Printf("%s", uri)

Output:

ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))

func (LDAPURI) String 

func (r LDAPURI) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example 
var uri LDAPURI
uri.Set(`ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))`)
fmt.Printf("%s", uri)

Output:

ldap:///ou=People,dc=example,dc=com?cn,sn,givenName,objectClass,uid?one?(&(objectClass=employee)(terminated=FALSE))

func (LDAPURI) Valid 

func (r LDAPURI) Valid() error

Valid returns an error instance in the event the receiver is in an aberrant state.

Example 
var uri LDAPURI
fmt.Printf("Valid: %t", uri.Valid() == nil)

Output:

Valid: false

type Level 

type Level uint16

Level describes a discrete numerical abstract of a subordinate level. Level describes any single Level definition. Level constants are intended for "storage" within an instance of Inheritance.

Valid Level constants are level zero (0) through level nine (9), though this will vary across implementations. 

const (
	Level0 Level = 1 << iota //   1 - base  (0) (current Object)
	Level1                   //   2 - one   (1) level below baseObject
	Level2                   //   4 - two   (2) levels below baseObject
	Level3                   //   8 - three (3) levels below baseObject
	Level4                   //  16 - four  (4) levels below baseObject
	Level5                   //  32 - five  (5) levels below baseObject
	Level6                   //  64 - six   (6) levels below baseObject
	Level7                   // 128 - seven (7) levels below baseObject
	Level8                   // 256 - eight (8) levels below baseObject
	Level9                   // 512 - nine  (9) levels below baseObject

	AllLevels Level = Level(2046) // ALL levels; zero (0) through nine (9)
)

Level uint16 constants are left-shifted into an instance of Levels to define a range of vertical (depth) rule statements.

func (Level) Compare 

func (r Level) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) Level instances using the Compare method. 

fmt.Printf("Hashes are equal: %t", Level8.Compare(Level7))

Output:

Hashes are equal: false

func (Level) String 

func (r Level) String() (lvl string)

String is a stringer method that returns a single string name value for receiver instance of Level.

Example 
fmt.Printf("%s", Level8)

Output:

8

type ObjectIdentifier 

type ObjectIdentifier struct {
	// contains filtered or unexported fields
}

ObjectIdentifier embeds an instance of go-objectid's DotNotation type.

Within the context of this package, instances of this type are used mainly for Target Rule definitions that bear the targetcontrol or extop keywords.

func Ctrl 

func Ctrl(x ...any) ObjectIdentifier

Ctrl initializes a new instance of ObjectIdentifier, which embeds an instance of go-objectid's DotNotation type.

Instances of this design are used in the creation of Target Rule Conditions that bear the `targetcontrol` keyword. OIDs produced as a result of this function are generally expected to be LDAP Control Object Identifiers.

Example

This example demonstrates the creation of a single LDAP Control Object Identifier, intended for use in the creation of targetcontrol TargetRule expressions. 

o := Ctrl(`1.3.6.1.4.1.56521.999.5`)
fmt.Printf("%s", o)

Output:

1.3.6.1.4.1.56521.999.5

func ExtOp 

func ExtOp(x ...any) ObjectIdentifier

ExtOp initializes a new instance of ObjectIdentifier, which embeds an instance of go-objectid's DotNotation type.

Instances of this design are used in the creation of Target Rule Conditions that bear the `extop` keyword. OIDs produced as a result of this function are generally expected to be LDAP Extended Operation Object Identifiers.

Example

This example demonstrates the creation of a single LDAP Extended Operation Object Identifier, intended for use in the creation of extop TargetRule expressions. 

o := ExtOp(`1.3.6.1.4.1.56521.999.5`)
fmt.Printf("%s", o)

Output:

1.3.6.1.4.1.56521.999.5

func OID 

func OID(x any, kw Keyword) ObjectIdentifier

OID returns a new instance of ObjectIdentifier. Instances of this type are used in the following scenarios:

• For appending (by Push) to an instance of ObjectIdentifers when crafting a multi-valued TargetRule instance containing a sequence of ObjectIdentifier instances, OR ...

• For use directly in creating a unary TargetRule instance

In either case, valid Target keyword contexts are `extop` and `targetcontrol`.

Example

This example demonstrates the manual creation of an ObjectIdentifier instance using the string representation of an ASN.1 Object Identifier in dot notation, and a valid keyword context for a TargetRule. 

o1 := `1.3.6.1.4.1.56521.999.5` // note: phony OID

o := OID(o1, TargetExtOp)
//o := OID(o1, TargetCtrl)	// alternative

fmt.Printf("OID:%s, Type:%s", o, o.Keyword())

Output:

OID:1.3.6.1.4.1.56521.999.5, Type:extop

func (ObjectIdentifier) Compare 

func (r ObjectIdentifier) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
o1 := Ctrl(`1.3.6.1.4.1.56521.999.5`)
o2 := ExtOp(`1.3.6.1.4.1.56521.999.5`)
fmt.Printf("%t", o1.Compare(o2))

Output:

true

func (ObjectIdentifier) Eq 

func (r ObjectIdentifier) Eq() (t TargetRule)

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To an `extop` or `targetcontrol` keyword context.

Example

This example demonstrates the creation of a multi-valued extop (LDAP Extended Operation) equality TargetRule expression. 

fmt.Printf("%s", ExtOp(`1.3.6.1.4.1.56521.999.5`).Eq())

Output:

( extop = "1.3.6.1.4.1.56521.999.5" )

func (ObjectIdentifier) IsZero 

func (r ObjectIdentifier) IsZero() bool

IsZero wraps go-objectid's DotNotation.IsZero method.

Example

This example demonstrates the use of the IsZero method upon a nil receiver. 

var oid ObjectIdentifier
fmt.Printf("Zero: %t", oid.IsZero())

Output:

Zero: true

func (ObjectIdentifier) Keyword 

func (r ObjectIdentifier) Keyword() Keyword

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a TargetRule containing the receiver instance as the expression value.

Example

This example demonstrates use of the Keyword method to obtain the current Keyword context from the receiver. 

fmt.Printf("%s", ExtOp(`1.3.6.1.4.1.56521.999.5`).Keyword())

Output:

extop

func (ObjectIdentifier) Kind 

func (r ObjectIdentifier) Kind() string

Kind returns the string value for the kind of ObjectIdentifier described by the receiver. It will return either `targetcontrol` or `extop`.

Example

This example demonstrates use of the Kind method to obtain the string form of the current Keyword context from the receiver. 

fmt.Printf("%s", ExtOp(`1.3.6.1.4.1.56521.999.5`).Kind())

Output:

extop

func (ObjectIdentifier) Len 

func (r ObjectIdentifier) Len() int

Len returns 0 or 1 to describe an abstract length of the receiver. This method exists only to satisfy Go's interface signature requirements and need not be used.

Example

This example demonstrates the (mostly) useless nature of the Len method, which only exists to satisfy Go's interface signature requirements. 

fmt.Printf("%d", ExtOp(`1.3.6.1.4.1.56521.999.5`).Len())

Output:

1

func (ObjectIdentifier) Ne 

func (r ObjectIdentifier) Ne() (t TargetRule)

Ne initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Not-Equal-To an `extop` or `targetcontrol` keyword context.

Negated equality TargetRule instances should be used with caution.

Example

This example demonstrates the creation of a multi-valued extop (LDAP Extended Operation) negated equality TargetRule expression. 

fmt.Printf("%s", ExtOp(`1.3.6.1.4.1.56521.999.5`).Ne())

Output:

( extop != "1.3.6.1.4.1.56521.999.5" )

func (ObjectIdentifier) String 

func (r ObjectIdentifier) String() string

String wraps go-objectid's DotNotation.String method.

Example

This example demonstrates the string representation of the receiver. 

fmt.Printf("%s", ExtOp(`1.3.6.1.4.1.56521.999.5`))

Output:

1.3.6.1.4.1.56521.999.5

func (ObjectIdentifier) TRM 

func (r ObjectIdentifier) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single ComparisonOperator that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual instance method to -- optionally -- use for the creation of the TargetRule.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example

This example demonstrates the use of the TRM method to obtain a list of available comparison operator identifiers and methods, and a subsequent call of Contains to determine whether Greater Than (Gt) is among them. 

var oid ObjectIdentifier
fmt.Printf("Allows greater-than: %t", oid.TRM().Contains(Gt))

Output:

Allows greater-than: false

func (ObjectIdentifier) Valid 

func (r ObjectIdentifier) Valid() (err error)

Valid returns an instance of error in the event the receiver is in an aberrant state.

Example

This example demonstrates the use of the Valid method upon a nil receiver. 

var oid ObjectIdentifier
fmt.Printf("Valid: %t", oid.Valid() == nil)

Output:

Valid: false

type ObjectIdentifierContext 

type ObjectIdentifierContext interface {
	Len() int
	String() string
	Kind() string
	Keyword() Keyword
	IsZero() bool
	Valid() error
	// contains filtered or unexported methods
}

ObjectIdentifierContext is a convenient interface type that is qualified by the following types:

• ObjectIdentifier

• ObjectIdentifiers

The qualifying methods shown below are intended to make the generalized handling of ASN.1 object identifiers slightly easier without an absolute need for type assertion at every step. These methods are inherently read-only in nature.

To alter the underlying value, or to gain access to all of a given type's methods, type assertion of qualifying instances shall be necessary.

type ObjectIdentifiers 

type ObjectIdentifiers stackage.Stack

ObjectIdentifiers is an alias type for stackage.Stack, and is intended to house one (1) or more ObjectIdentifier instances for the purpose of expression within a TargetRule instance.

func Ctrls 

func Ctrls(x ...any) (o ObjectIdentifiers)

Ctrls returns a freshly initialized instance of ObjectIdentifiers, configured to store one (1) or more ObjectIdentifier instances for the purpose of Target Rule expression when using the targetcontrol keyword.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the ObjectIdentifier type. This is merely a more convenient alternative to separate init and push procedures.

Example

This example demonstrates the creation of a multi-valued targetcontrol (LDAP Control) Target Rule expression. 

// note: these are phony OIDs
o1 := Ctrl(`1.3.6.1.4.1.56521.999.5`)
o2 := Ctrl(`1.3.6.1.4.1.56521.999.7`)

// Initialize the stack (Ctrls) and
// immediately push o1 and o2.
ctrls := Ctrls().Push(o1, o2)

fmt.Printf("%s", ctrls.Eq())

Output:

( targetcontrol = "1.3.6.1.4.1.56521.999.5 || 1.3.6.1.4.1.56521.999.7" )

func ExtOps 

func ExtOps(x ...any) (o ObjectIdentifiers)

ExtOps returns a freshly initialized instance of ObjectIdentifiers, configured to store one (1) or more ObjectIdentifier instances for the purpose of Target Rule expression when using the extop keyword.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the ObjectIdentifier type. This is merely a more convenient alternative to separate init and push procedures.

Example

This example demonstrates the creation of a multi-valued extop (LDAP Extended Operation) TargetRule expression. 

// note: these are phony OIDs
o1 := ExtOp(`1.3.6.1.4.1.56521.999.5`)
o2 := ExtOp(`1.3.6.1.4.1.56521.999.7`)

// Initialize the stack (Ctrls) and
// immediately push o1 and o2.
exop := ExtOps().Push(o1, o2)

fmt.Printf("%s", exop.Eq())

Output:

( extop = "1.3.6.1.4.1.56521.999.5 || 1.3.6.1.4.1.56521.999.7" )
Example (AlternativeQuotationScheme)

This example demonstrates a similar scenario to the one described in the above example, but with an alternative means of quotation demonstrated. Additionally, string primitives are used instead of proper ExtOp style OIDs. 

// Here we set double-quote encapsulation
// upon the Rule instance created by the
// ExtOps function.
ext := ExtOps().Push(
	// These aren't real control OIDs.
	`1.3.6.1.4.1.56521.999.5`,
	`1.3.6.1.4.1.56521.999.6`,
	`1.3.6.1.4.1.56521.999.7`,
)

fmt.Printf("%s", ext.Eq().SetQuoteStyle(0)) // see MultivalSliceQuotes const for details

Output:

( extop = "1.3.6.1.4.1.56521.999.5" || "1.3.6.1.4.1.56521.999.6" || "1.3.6.1.4.1.56521.999.7" )

func (ObjectIdentifiers) Compare 

func (r ObjectIdentifiers) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
o1 := Ctrls(`1.3.6.1.4.1.56521.999.5`, `1.3.6.1.4.1.56521.999.6`)
o2 := Ctrls(`1.3.6.1.4.1.56521.999.7`, `1.3.6.1.4.1.56521.999.6`)
fmt.Printf("%t", o1.Compare(o2))

Output:

false

func (ObjectIdentifiers) Contains 

func (r ObjectIdentifiers) Contains(x any) bool

Contains returns a Boolean value indicative of whether value x, if a string or ObjectIdentifier instance, already resides within the receiver instance.

Case is not significant in the matching process.

Example

This example demonstrates the population of an object identifier stack and a subsequent presence check of one of its members. 

ctrls := Ctrls(
	`1.3.6.1.4.1.56521.999.5`,
	`1.3.6.1.4.1.56521.999.6`,
	`1.3.6.1.4.1.56521.999.7`,
)

fmt.Printf("Contains OID: %t", ctrls.Contains(`1.3.6.1.4.1.56521.999.5`))

Output:

Contains OID: true

func (ObjectIdentifiers) Eq 

func (r ObjectIdentifiers) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To an `extop` or `targetcontrol` keyword context.

Example

This example demonstrates the creation of a multi-valued extop (LDAP Extended Operation) equality TargetRule expression. 

// note: these are phony OIDs
o1 := ExtOp(`1.3.6.1.4.1.56521.999.5`)
o2 := ExtOp(`1.3.6.1.4.1.56521.999.7`)

// Initialize the stack (Ctrls) and
// immediately push o1 and o2.
exop := ExtOps().Push(o1, o2)

fmt.Printf("%s", exop.Eq())

Output:

( extop = "1.3.6.1.4.1.56521.999.5 || 1.3.6.1.4.1.56521.999.7" )

func (ObjectIdentifiers) F 

func (r ObjectIdentifiers) F() func(...any) ObjectIdentifier

F returns the appropriate instance creator function for crafting individual ObjectIdentifier instances for submission to the receiver. This is merely a convenient alternative to maintaining knowledge as to which function applies to the current receiver instance.

The default is Ctrl, and will be returned if the receiver is uninitialized, or if the Keyword associated with the receiver is invalid somehow. Otherwise, ExtOp is returned.

Example

This example demonstrates the use of the F method to obtain the appropriate package level function to be used to craft additional slices for push into the receiver. 

var oids ObjectIdentifiers = Ctrls()
funk := oids.F()
newval := funk(`1.3.6.1.4.1.56521.999.5`)
fmt.Printf("New %T: %s", newval, newval)

Output:

New aci.ObjectIdentifier: 1.3.6.1.4.1.56521.999.5

func (ObjectIdentifiers) ID 

func (r ObjectIdentifiers) ID() (s string)

ID wraps go-stackage's Stack.ID method.

Example

This example demonstrates the use of the ID method. 

var oids ObjectIdentifiers = ExtOps() // must be initialized, as there are two (2) types of OIDs here
fmt.Printf("ID: %s", oids.ID())

Output:

ID: target

func (ObjectIdentifiers) Index 

func (r ObjectIdentifiers) Index(idx int) (x ObjectIdentifier)

Index wraps go-stackage's Stack.Index method. Note that the Boolean OK value returned by go-stackage by default will be shadowed and not obtainable by the caller.

Example

This example demonstrates the use of the Index method to obtain a single slice and print its Keyword value. 

ctrls := Ctrls(
	`1.3.6.1.4.1.56521.999.5`,
	`1.3.6.1.4.1.56521.999.6`,
	`1.3.6.1.4.1.56521.999.7`,
)

fmt.Printf("Slice keyword: %s", ctrls.Index(1).Keyword())

Output:

Slice keyword: targetcontrol

func (ObjectIdentifiers) IsZero 

func (r ObjectIdentifiers) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example

This example demonstrates the use of the IsZero method upon a nil receiver. 

var oids ObjectIdentifiers
fmt.Printf("Zero: %t", oids.IsZero())

Output:

Zero: true

func (ObjectIdentifiers) Keyword 

func (r ObjectIdentifiers) Keyword() Keyword
Example

This example demonstrates use of the Keyword method to obtain the current Keyword context from the receiver. 

ctrls := Ctrls().Push(
	// note: these are phony OIDs
	Ctrl(`1.3.6.1.4.1.56521.999.5`),
	Ctrl(`1.3.6.1.4.1.56521.999.7`),
)
fmt.Printf("%s", ctrls.Keyword())

Output:

targetcontrol

func (ObjectIdentifiers) Kind 

func (r ObjectIdentifiers) Kind() (k string)

Category wraps go-stackage's Stack.Category method.

Example

This example demonstrates use of the Kind method to obtain the string form of the current Keyword context from the receiver. 

ctrls := Ctrls().Push(
	// note: these are phony OIDs
	Ctrl(`1.3.6.1.4.1.56521.999.5`),
	Ctrl(`1.3.6.1.4.1.56521.999.7`),
)
fmt.Printf("%s", ctrls.Kind())

Output:

targetcontrol

func (ObjectIdentifiers) Len 

func (r ObjectIdentifiers) Len() int

Len wraps go-stackage's Stack.Len method.

Example

This example demonstrates use of the Len method to return the number of slices present within the receiver as an integer. 

ctrls := Ctrls().Push(
	// note: these are phony OIDs
	Ctrl(`1.3.6.1.4.1.56521.999.5`),
	Ctrl(`1.3.6.1.4.1.56521.999.7`),
)
fmt.Printf("%d", ctrls.Len())

Output:

2

func (ObjectIdentifiers) Ne 

func (r ObjectIdentifiers) Ne() TargetRule

Ne initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Not-Equal-To an `extop` or `targetcontrol` keyword context.

Negated equality TargetRule instances should be used with caution.

Example

This example demonstrates the creation of a multi-valued targetcontrol (LDAP Controls) negated equality TargetRule expression. 

// note: these are phony OIDs
o1 := Ctrl(`1.3.6.1.4.1.56521.999.5`)
o2 := Ctrl(`1.3.6.1.4.1.56521.999.7`)

// Initialize the stack (Ctrls) and
// immediately push o1 and o2.
ctrls := Ctrls().Push(o1, o2)

fmt.Printf("%s", ctrls.Ne())

Output:

( targetcontrol != "1.3.6.1.4.1.56521.999.5 || 1.3.6.1.4.1.56521.999.7" )

func (ObjectIdentifiers) Pop 

func (r ObjectIdentifiers) Pop() (x ObjectIdentifier)

Pop wraps go-stackage's Stack.Pop method.

Example

This is an example of a LIFO stack slice removal using the Pop method. 

// note: these are phony OIDs
o1 := ExtOp(`1.3.6.1.4.1.56521.999.5`)
o2 := ExtOp(`1.3.6.1.4.1.56521.999.7`)
o3 := ExtOp(`1.3.6.1.4.1.56521.999.9`)

// Initialize the stack (Ctrls) and
// immediately push o1 and o2.
exop := ExtOps().Push(o1, o2, o3)
popped := exop.Pop()

fmt.Printf("Removed %T (%s), stack length now %d", popped, popped, exop.Len())

Output:

Removed aci.ObjectIdentifier (1.3.6.1.4.1.56521.999.9), stack length now 2

func (ObjectIdentifiers) Push 

func (r ObjectIdentifiers) Push(x ...any) ObjectIdentifiers

Push wraps go-stackage's Stack.Push method.

Example

This example demonstrates the creation of a multi-valued extop (LDAP Extended Operation) equality TargetRule expression. Push is used to submit the instances of ObjectIdentifier to the stack. 

// note: these are phony OIDs
o1 := ExtOp(`1.3.6.1.4.1.56521.999.5`)
o2 := ExtOp(`1.3.6.1.4.1.56521.999.7`)

// Initialize the stack (Ctrls) and
// immediately push o1 and o2.
exop := ExtOps().Push(o1, o2)

fmt.Printf("%s", exop.Eq())

Output:

( extop = "1.3.6.1.4.1.56521.999.5 || 1.3.6.1.4.1.56521.999.7" )

func (ObjectIdentifiers) String 

func (r ObjectIdentifiers) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example

This example demonstrates the string representation of the receiver. 

// Initialize the stack (Ctrls) and
// immediately push into it.
ctrls := Ctrls().Push(
	// note: these are phony OIDs
	Ctrl(`1.3.6.1.4.1.56521.999.5`),
	Ctrl(`1.3.6.1.4.1.56521.999.7`),
)

fmt.Printf("%s", ctrls)

Output:

1.3.6.1.4.1.56521.999.5 || 1.3.6.1.4.1.56521.999.7

func (ObjectIdentifiers) TRM 

func (r ObjectIdentifiers) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single ComparisonOperator that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual instance method to -- optionally -- use for the creation of the TargetRule.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example

This example demonstrates the use of the TRM method to obtain a list of available comparison operator identifiers and methods, and a subsequent call of Contains to determine whether Greater Than (Gt) is among them. 

var oids ObjectIdentifiers
fmt.Printf("Allows greater-than: %t", oids.TRM().Contains(Gt))

Output:

Allows greater-than: false

func (ObjectIdentifiers) Valid 

func (r ObjectIdentifiers) Valid() (err error)

Valid returns an instance of error in the event the receiver is in an aberrant state.

Example

This example demonstrates the use of the Valid method upon a nil receiver. 

var oids ObjectIdentifiers
fmt.Printf("Valid: %t", oids.Valid() == nil)

Output:

Valid: false

type Permission 

type Permission struct {
	// contains filtered or unexported fields
}

Permission defines a level of access bestowed (or withheld) by an ACI.

func Allow 

func Allow(x ...any) Permission

Allow returns a granting Permission instance bearing the provided instances of Right.

Example

This example demonstrates the granting (allowance) of read, compare and search access. 

// allow read, compare and search privileges ...
G := Allow(ReadAccess, CompareAccess, SearchAccess)

// order is always fixed for string representation
// regardless of order-of-input ...
fmt.Printf("%s", G)

Output:

allow(read,search,compare)

func Deny 

func Deny(x ...any) Permission

Deny returns a withholding Permission instance bearing the provided instances of Right.

Example

This example demonstrates the withholding (denial) of all privileges except proxy. 

// deny everything (this does not include proxy privilege)
D := Deny(AllAccess)
fmt.Printf("%s", D)

Output:

deny(all)

func (Permission) Compare 

func (r Permission) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

func (Permission) Disposition 

func (r Permission) Disposition() string

Disposition returns the string disposition `allow` or 'deny', depending on the state of the receiver.

Example 
priv := Allow(`read`, `write`, `compare`, `selfwrite`)
fmt.Printf("%s", priv.Disposition())

Output:

allow

func (Permission) IsZero 

func (r Permission) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var priv Permission
fmt.Printf("Privileges are undefined: %t", priv.IsZero())

Output:

Privileges are undefined: true

func (Permission) Len 

func (r Permission) Len() (l int)

Len returns the abstract integer length of the receiver, quantifying the number of Right instances currently being expressed. For example, if the receiver instance has its Read and Delete Right bits enabled, this would represent an abstract length of two (2).

Example 
var priv Permission = Deny() // you MUST initialize Permission explicitly using Allow or Deny funcs
priv.Shift(ReadAccess, WriteAccess, CompareAccess, SearchAccess, ProxyAccess)
fmt.Printf("Number of privileges denied: %d", priv.Len())

Output:

Number of privileges denied: 5

func (*Permission) Parse 

func (r *Permission) Parse(raw string) (err error)

Parse wraps go-antlraci's ParsePermission function, writing valid data into the receiver, or returning an error instance if processing fails.

Example (Granting) 
var perm Permission

raw := `allow(read,write,compare,selfwrite)`

if err := perm.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("Read privileges granted: %t", perm.Positive(ReadAccess) && perm.Disposition() == `allow`)

Output:

Read privileges granted: true
Example (Withholding) 
var perm Permission

raw := `deny(all,proxy)`

if err := perm.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("Proxy privileges denied: %t", perm.Positive(ProxyAccess) && perm.Disposition() == `deny`)

Output:

Proxy privileges denied: true

func (Permission) Positive 

func (r Permission) Positive(x any) (posi bool)

Positive returns a Boolean value indicative of whether a particular bit is positive (is set). Negation implies negative, or unset.

Example 
var priv Permission = Deny(`read`, `write`, `proxy`, `search`) // you MUST initialize Permission explicitly using Allow or Deny funcs
fmt.Printf("Forbids read access: %t", priv.Positive(`read`))

Output:

Forbids read access: true

func (Permission) Shift 

func (r Permission) Shift(x ...any) Permission

Shift left-shifts the receiver instance to include Right x, if not already present.

Example 
var priv Permission = Allow() // you MUST initialize Permission explicitly using Allow or Deny funcs
priv.Shift(ReadAccess, ProxyAccess)
fmt.Printf("Allows proxy: %t", priv.Positive(`proxy`))

Output:

Allows proxy: true

func (Permission) String 

func (r Permission) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example 
priv := Allow(`read`, `write`, `compare`, `selfwrite`)
fmt.Printf("%s", priv)

Output:

allow(read,write,compare,selfwrite)

func (Permission) Unshift 

func (r Permission) Unshift(x ...any) Permission

Unshift right-shifts the receiver instance to remove Right x, if present.

Example 
var priv Permission = Deny() // you MUST initialize Permission explicitly using Allow or Deny funcs
priv.Shift(ReadAccess, WriteAccess, CompareAccess, SearchAccess, ProxyAccess)

priv.Unshift(CompareAccess) // remove the negated compare privilege

fmt.Printf("Forbids compare: %t", priv.Positive(`compare`))

Output:

Forbids compare: false

func (Permission) Valid 

func (r Permission) Valid() (err error)

Valid returns a non-error instance if the receiver fails to pass basic validity checks.

Example 
var priv Permission
fmt.Printf("%T is ready for use: %t", priv, priv.Valid() == nil)

Output:

aci.Permission is ready for use: false

type PermissionBindRule 

type PermissionBindRule struct {
	// contains filtered or unexported fields
}

PB contains one (1) Permission instance and one (1) BindRules instance. Instances of this type are used to create top-level ACI Permission+Bind Rule pairs, of which at least one (1) is required in any given access control instructor definition.

Users may compose instances of this type manually, or using the PB package level function, which automatically invokes value checks.

func PBR 

func PBR(P Permission, B BindContext) (r PermissionBindRule)

PBR returns an instance of PermissionBindRule, bearing the Permission P and the Bind Rule B. The values P and B shall undergo validity checks per the conditions of the PermissionBindRule.Valid method automatically. A bogus PermissionBindRule is returned if such checks fail.

Instances of this kind are intended for submission (via Push) into instances of PermissionBindRules.

Generally, an ACI only has a single PermissionBindRule, though multiple instances of this type are allowed per the syntax specification honored by this package.

Example

This example demonstrates the creation of a PermissionBindRule using the PBR package level function. 

// create a granting (allow)
// permissive statement, in
// which the read, search and
// compare privileges are
// bestowed.
grant := Allow(
	`read`,
	`search`,
	`compare`,
)

// create a timeframe rule to reference.
rule := Timeframe(
	ToD(`1400`), // notBefore
	ToD(`2300`), // notAfter
)

// Assemble the PermissionBindRule
// using the above components. Note
// that using the PBR function (as
// opposed to assembling the struct
// manually) automatically executes
// the Valid method for us.
pbr := PBR(grant, rule)

fmt.Printf("%s", pbr)

Output:

allow(read,search,compare) timeofday >= "1400" AND timeofday < "2300";

func (PermissionBindRule) Compare 

func (r PermissionBindRule) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
var pbr1 PermissionBindRule = PBR(
	Allow(NoAccess),
	UDN(`uid=disgruntled_employees,ou=Group,dc=example,dc=com`).Eq(),
)

var pbr2 PermissionBindRule = PBR(
	Allow(NoAccess),
	UDN(`uid=disgruntled_employee,ou=People,dc=example,dc=com`).Eq(),
)

fmt.Printf("%t", pbr1.Compare(pbr2))

Output:

false

func (PermissionBindRule) IsZero 

func (r PermissionBindRule) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver instance is nil, or unset.

Example 
var pbr PermissionBindRule
fmt.Printf("Zero: %t", pbr.IsZero())

Output:

Zero: true

func (PermissionBindRule) Kind 

func (r PermissionBindRule) Kind() string

Kind returns the string literal `pbr`.

Example 
var pbr PermissionBindRule
fmt.Printf("%s", pbr.Kind())

Output:

pbr

func (*PermissionBindRule) Parse 

func (r *PermissionBindRule) Parse(raw string) error

Parse wraps go-antlraci's ParsePermissionBindRule function, writing valid data into the receiver, or returning an error instance should processing fail.

Example

This example demonstrates the complete parsing of a composite ACIv3 component: the PermissionBindRule. A PermissionBindRule is a single permission statement followed by a BindRule or BindRules statement, and terminated by a semicolon (ASCII #59). 

var privs string = `allow(read,write,search,compare)`
var rules string = `( ( timeofday >= "0900" AND timeofday < "1830" ) AND ( dayofweek = "Mon,Tues,Wed,Thur,Fri" ) )`

// combine the above into one single statement
// with proper termination.
var raw string = sprintf("%s %s;", privs, rules)

// Prepare the 'container' for our new
// PermissionBindRule components.
var pbr PermissionBindRule
if err := pbr.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("%s", pbr)

Output:

allow(read,write,search,compare) ( ( timeofday >= "0900" AND timeofday < "1830" ) AND ( dayofweek = "Mon,Tues,Wed,Thur,Fri" ) );

func (*PermissionBindRule) Set 

func (r *PermissionBindRule) Set(x ...any) PermissionBindRule

Set assigns one (1) or more values (x) to the receiver. Valid types for input are Permission, BindContext or their string equivalents.

Example

This example demonstrates a basic assembly of a PermissionBindRule using actual Permission and BindContext instances assigned through the Set method. 

// Prepare the 'container' for our new
// PermissionBindRule components.
var pbr PermissionBindRule
pbr.Set(
	Allow(NoAccess),
	UDN(`ldap:///uid=disgruntled_employee,ou=People,dc=example,dc=com`).Eq(),
)

fmt.Printf("%s", pbr)

Output:

allow(none) userdn = "ldap:///uid=disgruntled_employee,ou=People,dc=example,dc=com";
Example (WithParse)

This example demonstrates the same outcome as the PermissionBindRule.Parse example, except this time using the Set method on a nil instance. 

var privs string = `allow(read,write,search,compare)`
var rules string = `( ( timeofday >= "0900" AND timeofday < "1830" ) AND ( dayofweek = "Mon,Tues,Wed,Thur,Fri" ) )`

// combine the above into one single statement
// with proper termination.
var raw string = sprintf("%s %s;", privs, rules)

// Prepare the 'container' for our new
// PermissionBindRule components.
var pbr PermissionBindRule
pbr.Set(raw)

fmt.Printf("%s", pbr)

Output:

allow(read,write,search,compare) ( ( timeofday >= "0900" AND timeofday < "1830" ) AND ( dayofweek = "Mon,Tues,Wed,Thur,Fri" ) );

func (PermissionBindRule) String 

func (r PermissionBindRule) String() string

String is a stringer method that returns the string representation of the receiver.

Example 
var pbr PermissionBindRule = PBR(
	Allow(NoAccess),
	UDN(`uid=disgruntled_employee,ou=People,dc=example,dc=com`).Eq(),
)

fmt.Printf("%s", pbr)

Output:

allow(none) userdn = "ldap:///uid=disgruntled_employee,ou=People,dc=example,dc=com";

func (PermissionBindRule) Valid 

func (r PermissionBindRule) Valid() (err error)

Valid returns an error instance should any of the following conditions evaluate as true:

• Permission.Valid returns an error for P

• Rule.Valid returns an error for B

• Rule.Len returns zero (0) for B

Example 
var pbr PermissionBindRule
fmt.Printf("Valid: %t", pbr.Valid() == nil)

Output:

Valid: false

type PermissionBindRules 

type PermissionBindRules stackage.Stack

PermissionBindRules is a stackage.Stack type alias used to store one (1) or more instances of PermissionBindRule. Instances of this kind are used in top-level Instruction (ACI) assembly.

func PBRs 

func PBRs(x ...any) (pbr PermissionBindRules)

PBRs returns a freshly initialized instance of PermissionBindRules, configured to store one (1) or more instances of PermissionBindRule.

Instances of this kind are used as a component in top-level Instruction (ACI) assembly.

Example

This example demonstrates the creation of a PermissionBindRules instance using the PBRs package level function. 

var rule1 PermissionBindRule = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=disgruntled_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

var rule2 PermissionBindRule = PBR(
	Allow(AllAccess),
	UDN(`cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

// Init/Push in one shot
pbrs := PBRs(rule1, rule2)

fmt.Printf("%d %T instances found within %T", pbrs.Len(), rule1, pbrs)

Output:

2 aci.PermissionBindRule instances found within aci.PermissionBindRules

func (PermissionBindRules) Compare 

func (r PermissionBindRules) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
var rule1 PermissionBindRule = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=disgruntled_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

var rule2 PermissionBindRule = PBR(
	Allow(AllAccess),
	UDN(`cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

// Init/Push in one shot
pbrs1 := PBRs()
pbrs1.Push(rule1, rule2)

rule1 = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=onboard_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

rule2 = PBR(
	Allow(AllAccess),
	UDN(`cn=Jesse Coretta,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

pbrs2 := PBRs()
pbrs2.Push(rule1, rule2)

fmt.Printf("%t", pbrs1.Compare(pbrs2))

Output:

false

func (PermissionBindRules) Contains 

func (r PermissionBindRules) Contains(x any) bool

Contains returns a Boolean value indicative of whether value x, if a string or PermissionBindRule instance, already resides within the receiver instance.

Case is not significant in the matching process.

Example 
var rule1 PermissionBindRule = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=disgruntled_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

var rule2 PermissionBindRule = PBR(
	Allow(AllAccess),
	UDN(`cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

// Init/Push in one shot
pbrs := PBRs(rule1, rule2)

fmt.Printf("%T contains rule2: %t", pbrs, pbrs.Contains(rule2))

Output:

aci.PermissionBindRules contains rule2: true

func (PermissionBindRules) Index 

func (r PermissionBindRules) Index(idx int) (pbr PermissionBindRule)

Index wraps go-stackage's Stack.Index method and performs type assertion in order to return an instance of PermissionBindRule.

Example 
var rule1 PermissionBindRule = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=disgruntled_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

var rule2 PermissionBindRule = PBR(
	Allow(AllAccess),
	UDN(`cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

// Init/Push in one shot
pbrs := PBRs()
pbrs.Push(rule1)
pbrs.Push(rule2)

for i := 0; i < pbrs.Len(); i++ {
	slice := pbrs.Index(i)
	fmt.Printf("%s\n", slice)
}

Output:

deny(all,proxy) groupdn = "ldap:///cn=disgruntled_employees,ou=Groups,dc=example,dc=com";
allow(all) userdn = "ldap:///cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com";

func (PermissionBindRules) IsZero 

func (r PermissionBindRules) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example 
var pbrs PermissionBindRules
fmt.Printf("Zero: %t", pbrs.IsZero())

Output:

Zero: true

func (PermissionBindRules) Kind 

func (r PermissionBindRules) Kind() string

Category wraps go-stackage's Stack.ID method.

Example 
var pbrs PermissionBindRules
fmt.Printf("%s", pbrs.Kind())

Output:

pbrs

func (PermissionBindRules) Len 

func (r PermissionBindRules) Len() int

Len wraps go-stackage's Stack.Len method.

Example 
var pbrs PermissionBindRules
fmt.Printf("Length: %d", pbrs.Len())

Output:

Length: 0

func (*PermissionBindRules) Parse 

func (r *PermissionBindRules) Parse(raw string) error

Parse wraps go-antlraci's ParsePermissionBindRules function, writing valid data into the receiver, or returning an error instance should processing fail.

Example

This example demonstrates the acts of parsing a sequence of multiple PermissionBindRule expressive statements. Each individual PermissionBindRule must be valid unto itself, and in particular, must be terminated with ASCII #59 (;). 

var pbrs PermissionBindRules
// this is a sequence of three (3) PermissionBindRule
// expressions in raw text format.
var raw string = `allow(read,write) ( groupdn = "ldap:///cn=Human Resources,dc=example,dc=com" ); allow(read,write,delete,search,compare) ( userdn = "ldap:///all" ); deny(all) ( userdn = "ldap:///anyone" ) AND ( ip != "192.0.2." );`

if err := pbrs.Parse(raw); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%T instance contains %d slices", pbrs, pbrs.Len())

Output:

aci.PermissionBindRules instance contains 3 slices

func (PermissionBindRules) Pop 

func (r PermissionBindRules) Pop() (pbr PermissionBindRule)

Pop wraps go-stackage's Stack.Pop method. An instance of PermissionBindRule, which may or may not be nil, is returned following a call of this method.

Within the context of the receiver type, a PermissionBindRule, if non-nil, can only represent a PermissionBindRule instance.

Example 
var rule1 PermissionBindRule = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=disgruntled_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

var rule2 PermissionBindRule = PBR(
	Allow(AllAccess),
	UDN(`cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

// Init/Push in one shot
pbrs := PBRs()
pbrs.Push(rule1)
pbrs.Push(rule2)

// Pop the most recent (LIFO) slice
// for interrogation. Note that this
// REMOVED it from the above stack.
popped := pbrs.Pop()

fmt.Printf("Popped: %s", popped)

Output:

Popped: allow(all) userdn = "ldap:///cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com";

func (PermissionBindRules) Push 

func (r PermissionBindRules) Push(x ...any) PermissionBindRules

Push wraps go-stackage's Stack.Push method.

Example 
var rule1 PermissionBindRule = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=disgruntled_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

var rule2 PermissionBindRule = PBR(
	Allow(AllAccess),
	UDN(`cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

// Init/Push in one shot
pbrs := PBRs()
pbrs.Push(rule1)
pbrs.Push(rule2)

fmt.Printf("%d %T instances found within %T", pbrs.Len(), rule1, pbrs)

Output:

2 aci.PermissionBindRule instances found within aci.PermissionBindRules

func (PermissionBindRules) String 

func (r PermissionBindRules) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example 
var rule1 PermissionBindRule = PBR(
	Deny(AllAccess, ProxyAccess),
	GDN(`cn=disgruntled_employees,ou=Groups,dc=example,dc=com`).Eq(),
)

var rule2 PermissionBindRule = PBR(
	Allow(AllAccess),
	UDN(`cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com`).Eq(),
)

// Init/Push in one shot
pbrs := PBRs()
pbrs.Push(rule1)
pbrs.Push(rule2)

fmt.Printf("%s", pbrs)

Output:

deny(all,proxy) groupdn = "ldap:///cn=disgruntled_employees,ou=Groups,dc=example,dc=com"; allow(all) userdn = "ldap:///cn=Courtney Tolana,ou=Admin,ou=People,dc=example,dc=com";

func (PermissionBindRules) Valid 

func (r PermissionBindRules) Valid() (err error)

Valid wraps go-stackage's Stack.Valid method.

Example 
var pbrs PermissionBindRules
fmt.Printf("Valid: %t", pbrs.Valid() == nil)

Output:

Valid: false

type Right uint16

Right contains the specific bit value of a single user privilege. Constants of this type are intended for submission to the Permission.Shift, Permission.Unshift and Permission.Positive methods. 

const (
	ReadAccess      Right = 1 << iota // 1
	WriteAccess                       // 2
	AddAccess                         // 4
	DeleteAccess                      // 8
	SearchAccess                      // 16
	CompareAccess                     // 32
	SelfWriteAccess                   // 64
	ProxyAccess                       // 128
	ImportAccess                      // 256
	ExportAccess                      // 512

	NoAccess  Right = 0
	AllAccess Right = 895 // DOES NOT INCLUDE "proxy"
)

Right constants are discrete left-shifted privilege aggregates that can be used in an additive (or subtractive) manner to form a complete Permission.

func (Right) Compare 

func (r Right) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

func (Right) String 

func (r Right) String() (p string)

String is a stringer method that returns a single string name value for receiver instance of Right.

Example 
// iterate all of the known Right definitions
// defined as constants in this package.
for idx, privilege := range []Right{
	NoAccess,
	ReadAccess,
	WriteAccess,
	AddAccess,
	DeleteAccess,
	SearchAccess,
	CompareAccess,
	SelfWriteAccess,
	ProxyAccess,
	ImportAccess,
	ExportAccess,
	AllAccess, // does NOT include proxy access !
} {
	fmt.Printf("Privilege %02d/%d: %s (bit:%d)\n", idx+1, 12, privilege, int(privilege))
}

Output:

Privilege 01/12: none (bit:0)
Privilege 02/12: read (bit:1)
Privilege 03/12: write (bit:2)
Privilege 04/12: add (bit:4)
Privilege 05/12: delete (bit:8)
Privilege 06/12: search (bit:16)
Privilege 07/12: compare (bit:32)
Privilege 08/12: selfwrite (bit:64)
Privilege 09/12: proxy (bit:128)
Privilege 10/12: import (bit:256)
Privilege 11/12: export (bit:512)
Privilege 12/12: all (bit:895)

type SearchFilter 

type SearchFilter struct {
	// contains filtered or unexported fields
}

SearchFilter is a struct type that embeds an LDAP search filter. Instances of this type may be used in a variety of areas, from LDAPURI composition to targetfilter rules.

func Filter 

func Filter(x ...string) (r SearchFilter)

Filter initializes (and optionally sets) a new instance of SearchFilter. Instances of this kind are used in LDAPURIs, as well as certain target rules.

Example

This example demonstrates how to craft a Target Rule Condition bearing the `targetfilter` keyword and an LDAP Search Filter. 

tf := Filter(`(&(uid=jesse)(objectClass=*))`)
fmt.Printf("%s", tf.Eq())

Output:

( targetfilter = "(&(uid=jesse)(objectClass=*))" )

func (SearchFilter) Compare 

func (r SearchFilter) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) SearchFilter instances using the Compare method. 

f1 := Filter(`(|(objectClass=contractor)(objectClass=intern))`)
f2 := Filter(`(|(objectClass=contractor)(objectClass=intern))`)

fmt.Printf("Hashes are equal: %t", f1.Compare(f2))

Output:

Hashes are equal: true

func (SearchFilter) Eq 

func (r SearchFilter) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To a `targetfilter` Target Keyword context.

Example 
var filter SearchFilter
filter.Set(`(|(objectClass=contractor)(objectClass=intern))`)
fmt.Printf("%s", filter.Eq())

Output:

( targetfilter = "(|(objectClass=contractor)(objectClass=intern))" )

func (SearchFilter) IsZero 

func (r SearchFilter) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
filter := Filter(`(|(objectClass=contractor)(objectClass=intern))`)
fmt.Printf("%t", filter.IsZero())

Output:

false

func (SearchFilter) Keyword 

func (r SearchFilter) Keyword() Keyword

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned is always TargetFilter.

Example 
filter := Filter(`(|(objectClass=contractor)(objectClass=intern))`)
fmt.Printf("%s", filter.Keyword())

Output:

targetfilter

func (SearchFilter) Ne 

func (r SearchFilter) Ne() TargetRule

Ne initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Not-Equal-To a `targetfilter` Target Keyword context.

Negated equality TargetRule instances should be used with caution.

Example 
var filter SearchFilter
filter.Set(`(&(objectClass=contractor)(objectClass=intern))`)
fmt.Printf("%s", filter.Ne())

Output:

( targetfilter != "(&(objectClass=contractor)(objectClass=intern))" )

func (*SearchFilter) Set 

func (r *SearchFilter) Set(x string) *SearchFilter

Set assigns the provided value as the LDAP Search Filter instance within the receiver. Note that this should only be done once, as filters cannot easily built "incrementally" by the user.

Example 
var filter SearchFilter
filter.Set(`(|(objectClass=contractor)(objectClass=intern))`)
fmt.Printf("%t", filter.IsZero())

Output:

false

func (SearchFilter) String 

func (r SearchFilter) String() string

String is a stringer method that returns the string representation of an LDAP Search Filter.

Example 
var filter SearchFilter
filter.Set(`(|(objectClass=contractor)(objectClass=intern))`)
fmt.Printf("%s", filter)

Output:

(|(objectClass=contractor)(objectClass=intern))

func (SearchFilter) TRM 

func (r SearchFilter) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual TargetRuleMethod instance for OPTIONAL use in the creation of a TargetRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var filter SearchFilter
filter.Set(`(|(objectClass=contractor)(objectClass=intern))`)
fmt.Printf("%d available aci.TargetRuleMethod instances", filter.TRM().Len())

Output:

2 available aci.TargetRuleMethod instances

func (SearchFilter) Valid 

func (r SearchFilter) Valid() (err error)

Valid -- at the moment -- performs a naïve check on the receiver to determine whether the value is defined. This method may, in the future, introduce more sophisticated checks to increase its value, such as counting (unescaped) parenthetical openers and closers to verify the effective 'balance' of the expression.

For now, this method is little more than an inverse counterpart to IsZero that returns an instance of error instead of a Boolean.

Example 
var filter SearchFilter
fmt.Printf("%v", filter.Valid())

Output:

aci.SearchFilter instance is nil

type SearchScope 

type SearchScope uint8

SearchScope is a type definition used to represent one of the four (4) possible LDAP Search Scope types that are eligible for use within the ACI syntax specification honored by this package.

SearchScope constants are generally used for crafting TargetRule instances that bear the `targetscope` keyword, as well as for crafting fully-qualified LDAP Search URIs.

See the SearchScope constants defined in this package for specific scopes available. 

const (
	BaseObject  SearchScope // 0x0, `base`
	SingleLevel             // 0x1, `one` or `onelevel`
	Subtree                 // 0x2, `sub` or `subtree`
	Subordinate             // 0x3, `subordinate`
)

SearchScope constants define four (4) known LDAP Search Scopes permitted for use per the ACI syntax specification honored by this package.

func Scope 

func Scope(x any) (s SearchScope)

Scope initializes, sets and returns an instance of SearchScope in one shot. Valid input types are as follows:

• Standard scope names as string values (e.g.: `base`, `sub`, `subtree` and others)

• Integer representations of scopes (see the predefined SearchScope constants for details)

This function may only be needed in certain situations where a scope needs to be parsed from values with different representations. Usually the predefined SearchScope constants are sufficient.

func (SearchScope) Compare 

func (r SearchScope) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
fmt.Printf("%s == %s: %t", SingleLevel, BaseObject, SingleLevel.Compare(BaseObject))

Output:

onelevel == base: false

func (SearchScope) Eq 

func (r SearchScope) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To an `targetscope` keyword context.

Example (TargetScopeOneLevel)

This example demonstrates how to craft a Target Scope Rule Condition for a onelevel Search Scope. 

fmt.Printf("%s", SingleLevel.Eq())

Output:

( targetscope = "onelevel" )

func (SearchScope) Keyword 

func (r SearchScope) Keyword() Keyword

Keyword returns the Keyword associated with the receiver instance. In the context of this type instance, the Keyword returned is always TargetScope.

Example 
fmt.Printf("%s", SingleLevel.Keyword())

Output:

targetscope

func (SearchScope) Ne 

func (r SearchScope) Ne() TargetRule

Ne performs no useful task, as negated equality comparison does not apply to TargetRule instances that bear the `targetscope` keyword.

This method exists solely to convey this message. When executed, this method returns a bogus TargetRule instance.

This method SHALL NOT appear within instances of TargetRuleMethods that were crafted through execution of the receiver's TRM method.

Example 
fmt.Printf("%s", SingleLevel.Ne()) // ILLEGAL!!!!

func (SearchScope) String 

func (r SearchScope) String() string

String is a stringer method that returns the string representation of the receiver. In this particular case, the more succinct and standard string variant is returned, e.g.: `one` for SingleLevel. This will normally be used within LDAPURI instances.

See the SearchScope.Target method for Target Rule related scope names.

Example 
fmt.Printf("%s", SingleLevel)

Output:

onelevel

func (SearchScope) TRM 

func (r SearchScope) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single ComparisonOperator that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual instance method to -- optionally -- use for the creation of the TargetRule.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
fmt.Printf("Allows Ne: %t", SingleLevel.TRM().Contains(Ne))

Output:

Allows Ne: false

func (SearchScope) Target 

func (r SearchScope) Target() string

Target is a stringer method that returns the string representation of the receiver.

This method is primarily intended for creation of a new `targetscope`-style TargetRule instance, and is executed automatically during that process.

Example 
fmt.Printf("%s", Subordinate) // only valid for target rule scenarios, never URIs!

Output:

subordinate

type SecurityStrengthFactor 

type SecurityStrengthFactor struct {
	// contains filtered or unexported fields
}

SecurityStrengthFactor embeds a pointer to uint8. A nil uint8 value indicates an effective security strength factor of zero (0). A non-nil uint8 value expresses uint8 + 1, thereby allowing a range of 0-256 "within" a uint8 instance.

func SSF 

func SSF(factor ...any) SecurityStrengthFactor

SSF initializes, sets and returns a new instance of SecurityStrengthFactor in one shot. This function is an alternative to separate assignment and set procedures.

Example 
// convenient alternative to "var X SecurityStrengthFactor, X.Set(...) ..."
fmt.Printf("%s", SSF(128))

Output:

128
Example (SetLater) 
s := SSF() // this is functionally the same ...
// var s SecurityStrengthFactor // ... as this.

// ... later in your code ...

fmt.Printf("%s", s.Set(127))

Output:

127

func (SecurityStrengthFactor) BRM 

func (r SecurityStrengthFactor) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var factor SecurityStrengthFactor = SSF(128)
meths := factor.BRM()
fmt.Printf("%d available aci.BindRuleMethod instances", meths.Len())

Output:

6 available aci.BindRuleMethod instances

func (SecurityStrengthFactor) Compare 

func (r SecurityStrengthFactor) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) SecurityStrengthFactor instances using the Compare method. 

ssf1 := SSF(`101`)
ssf2 := SSF(101)

fmt.Printf("Hashes are equal: %t", ssf1.Compare(ssf2))

Output:

Hashes are equal: true

func (SecurityStrengthFactor) Eq 

func (r SecurityStrengthFactor) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To the `ssf` Bind keyword context.

Example 
var s SecurityStrengthFactor
fmt.Printf("%s", s.Set(128).Eq().Paren())

Output:

( ssf = "128" )

func (SecurityStrengthFactor) Ge 

func (r SecurityStrengthFactor) Ge() BindRule

Ge initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Greater-Than-Or-Equal to the `ssf` Bind keyword context.

Example 
var s SecurityStrengthFactor
fmt.Printf("%s", s.Set(128).Ge().Paren())

Output:

( ssf >= "128" )

func (SecurityStrengthFactor) Gt 

func (r SecurityStrengthFactor) Gt() BindRule

Gt initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Greater-Than the `ssf` Bind keyword context.

Example 
var s SecurityStrengthFactor
fmt.Printf("%s", s.Set(128).Gt().Paren())

Output:

( ssf > "128" )

func (SecurityStrengthFactor) IsZero 

func (r SecurityStrengthFactor) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var s SecurityStrengthFactor
fmt.Printf("Zero: %t", s.IsZero())

Output:

Zero: true

func (SecurityStrengthFactor) Keyword 

func (r SecurityStrengthFactor) Keyword() Keyword

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a BindRule containing the receiver instance as the expression value.

Example 
var s SecurityStrengthFactor
fmt.Printf("Keyword: %s", s.Keyword())

Output:

Keyword: ssf

func (SecurityStrengthFactor) Le 

func (r SecurityStrengthFactor) Le() BindRule

Le initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Less-Than-Or-Equal to the `ssf` Bind keyword context.

Example 
var s SecurityStrengthFactor
fmt.Printf("%s", s.Set(128).Le().Paren())

Output:

( ssf <= "128" )

func (SecurityStrengthFactor) Lt 

func (r SecurityStrengthFactor) Lt() BindRule

Lt initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Less-Than the `ssf` Bind keyword context.

Example 
var s SecurityStrengthFactor
fmt.Printf("%s", s.Set(128).Lt())

Output:

ssf < "128"

func (SecurityStrengthFactor) Ne 

func (r SecurityStrengthFactor) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To the `ssf` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example 
var s SecurityStrengthFactor
fmt.Printf("%s", s.Set(128).Ne().Paren())

Output:

( ssf != "128" )

func (*SecurityStrengthFactor) Set 

func (r *SecurityStrengthFactor) Set(factor any) SecurityStrengthFactor

Set modifies the receiver to reflect the desired security strength factor (SSF), which can represent any numerical value between 0 (off) and 256 (max).

Valid input types are int, string and nil.

A value of nil wipes out any previous value, making the SSF effectively zero (0).

A string value of `full` or `max` sets the SSF to its maximum value. A value of `none` or `off` has the same effect as when providing a nil value. A numerical string value is cast as int and (if valid) will be resubmitted silently. Case is not significant during the string matching process.

An int value less than or equal to zero (0) has the same effect as when providing a nil value. A value between 1 and 256 is acceptable and will be used. A value greater than 256 will be silently reduced back to the maximum.

Example (ByNumber) 
var s SecurityStrengthFactor
s.Set(128)
fmt.Printf("%s\n", s)

Output:

128
Example (ByWordMaxFactor) 
var s SecurityStrengthFactor
s.Set(`FULL`) // case is not significant
//s.Set(`max`) // alternative term
fmt.Printf("%s", s)

Output:

256
Example (ByWordNoFactor) 
var s SecurityStrengthFactor
s.Set(`noNe`) // case is not significant
fmt.Printf("%s", s)

Output:

0

func (SecurityStrengthFactor) String 

func (r SecurityStrengthFactor) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example 
var s SecurityStrengthFactor = SSF(128)
fmt.Printf("%s", s)

Output:

128

func (SecurityStrengthFactor) Valid 

func (r SecurityStrengthFactor) Valid() error

Valid returns nil and, at present, does nothing else. Based on the efficient design of the receiver type, there is no possible state that is technically invalid at ALL times. A nil instance may, in fact, be correct in particular situations.

Thus as there is no room for unforeseen errors with regards to this type specifically, this method has been gutted but remains present merely for the purpose of signature consistency throughout the package.

Example 
var s SecurityStrengthFactor
fmt.Printf("Valid: %t", s.Valid() == nil) // zero IS valid, technically speaking!

Output:

Valid: true

type TargetDistinguishedName 

type TargetDistinguishedName struct {
	// contains filtered or unexported fields
}

TargetDistinguishedName describes a single LDAP distinguished name. For example: 

ou=People,dc=example,dc=com

For efficiency reasons, the LDAP "local scheme" prefix (ldap:///) is not stored in literal form within any DistinguishedName instance, however it will appear during string representation operations, e.g.: 

ldap:///ou=People,dc=example,dc=com

Instances of this kind can be crafted using the DN package-level function with the appropriate Target keyword as the input argument:

• DN(<dn>, Target) for a `target` Distinguished Name

• DN(<dn>, TargetTo) for a `target_to` Distinguished Name

• DN(<dn>, TargetFrom) for a `target_from` Distinguished Name

In order to fashion multi-valued TargetRule instances using values of this type, they must reside within an appropriate stack type instance. For further details, see the BindDistinguishedNames and TargetDistinguishedNames types.

func TDN 

func TDN(x string) TargetDistinguishedName

TDN initializes, sets and returns an instance of DistinguishedName in one shot.

An LDAP distinguished name, in string form and WITHOUT the leading `ldap:///` scheme, is required.

The return value shall be suitable for use in creating a Target Rule Condition that bears the `target` keyword.

Example 
dn := TDN(`cn=Executives,ou=Groups,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///cn=Executives,ou=Groups,dc=example,dc=com

func TFDN 

func TFDN(x string) TargetDistinguishedName

TFDN initializes, sets and returns an instance of DistinguishedName in one shot.

An LDAP distinguished name, in string form and WITHOUT the leading `ldap:///` scheme, is required.

The return value shall be suitable for use in creating a Target Rule Condition that bears the `target_from` keyword.

Example 
dn := TFDN(`cn=Executives,ou=Groups,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///cn=Executives,ou=Groups,dc=example,dc=com

func TTDN 

func TTDN(x string) TargetDistinguishedName

TTDN initializes, sets and returns an instance of DistinguishedName in one shot.

An LDAP distinguished name, in string form and WITHOUT the leading `ldap:///` scheme, is required.

The return value shall be suitable for use in creating a Target Rule Condition that bears the `target_to` keyword.

Example 
dn := TTDN(`cn=Executives,ou=Groups,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///cn=Executives,ou=Groups,dc=example,dc=com

func (TargetDistinguishedName) Compare 

func (r TargetDistinguishedName) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) instances of TargetDistinguishedName using the Compare method.

The comparison evaluates as false because the case folding schemes do not match for the `T` in Tolana. 

dn1 := TDN(`cn=Courtney tolana,ou=People,dc=example,dc=com`)
dn2 := TDN(`cn=Courtney Tolana,ou=People,dc=example,dc=com`)

fmt.Printf("Hashes are equal: %t", dn1.Compare(dn2))

Output:

Hashes are equal: false

func (TargetDistinguishedName) Eq 

func (r TargetDistinguishedName) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To one (1) of the following keyword contexts:

• `target`

• `target_to`

• `target_from`

Example 
var dn TargetDistinguishedName = TTDN(`cn=Distribution List,ou=Groups,dc=example,dc=com`)
fmt.Printf("%s", dn.Eq())

Output:

( target_to = "ldap:///cn=Distribution List,ou=Groups,dc=example,dc=com" )

func (TargetDistinguishedName) IsZero 

func (r TargetDistinguishedName) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is considered nil, or unset.

Example 
var dn TargetDistinguishedName
fmt.Printf("Zero: %t", dn.IsZero())

Output:

Zero: true

func (TargetDistinguishedName) Keyword 

func (r TargetDistinguishedName) Keyword() Keyword

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a TargetRule bearing the receiver as a condition value.

Example 
var dn TargetDistinguishedName = TFDN(`uid=*,ou=People,dc=example,dc=com`)
fmt.Printf("Keyword: %s", dn.Keyword())

Output:

Keyword: target_from

func (TargetDistinguishedName) Kind 

func (r TargetDistinguishedName) Kind() string

Kind returns the string name `target`.

Example 
var dn TargetDistinguishedName = TFDN(`uid=*,ou=People,dc=example,dc=com`)
fmt.Printf("Kind: %s", dn.Kind())

Output:

Kind: target

func (TargetDistinguishedName) Len 

func (r TargetDistinguishedName) Len() int

Len returns 0 or 1 to describe an abstract length of the receiver. This method exists only to satisfy Go's interface signature requirements and need not be used.

Example 
var dn TargetDistinguishedName = TFDN(`uid=*,ou=People,dc=example,dc=com`)
fmt.Printf("Length %d", dn.Len())

Output:

Length 1

func (TargetDistinguishedName) Ne 

func (r TargetDistinguishedName) Ne() TargetRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To one (1) of the following keyword contexts:

• `target`

• `target_to`

• `target_from`

Negated equality TargetRule instances should be used with caution.

Example 
var dn TargetDistinguishedName = TFDN(`uid=courtney,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn.Ne())

Output:

( target_from != "ldap:///uid=courtney,ou=People,dc=example,dc=com" )

func (*TargetDistinguishedName) Set 

func (r *TargetDistinguishedName) Set(x string, kw ...TargetKeyword) TargetDistinguishedName

Set assigns value x to the receiver to represent an LDAP distinguished name in the context of a TargetRule.

This method presents an opportunity for setting a DN at a later point versus doing so during the initialization process alone and is totally optional.

If no keyword is specified, the target keyword context is supplied automatically, which may or may not be what the caller wants.

Example 
var dn TargetDistinguishedName
dn.Set(`cn=*,($attr.ou),dc=example,dc=com`, Target)
fmt.Printf("%s", dn.Ne())

Output:

( target != "ldap:///cn=*,($attr.ou),dc=example,dc=com" )

func (TargetDistinguishedName) String 

func (r TargetDistinguishedName) String() string

String is a stringer method that returns the string representation of the receiver instance.

The Local LDAP scheme (ldap:///) is automatically imposed during the string representation of the value; this is required by the ACIv3 syntax.

Example 
var dn TargetDistinguishedName = TDN(`cn=Executives,ou=Groups,dc=example,dc=com`)
fmt.Printf("%s", dn)

Output:

ldap:///cn=Executives,ou=Groups,dc=example,dc=com

func (TargetDistinguishedName) TRM 

func (r TargetDistinguishedName) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual TargetRuleMethod instance for OPTIONAL use in the creation of a TargetRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var dn TargetDistinguishedName
fmt.Printf("%d available comparison operator methods", dn.TRM().Len())

Output:

2 available comparison operator methods

func (TargetDistinguishedName) Valid 

func (r TargetDistinguishedName) Valid() (err error)

Valid returns an instance of error that reflects whether certain required elements or value combinations were present and deemed valid. A non-nil error indicates an undesirable receiver state.

Example 
var dn TargetDistinguishedName
fmt.Printf("Valid: %t", dn.Valid() == nil)

Output:

Valid: false

type TargetDistinguishedNames 

type TargetDistinguishedNames stackage.Stack

TargetDistinguishedNames is an alias type for stackage.Stack, and is intended to house one (1) or more TargetDistinguishedName instances for the purpose of expression within a TargetRule instance.

func TDNs 

func TDNs(x ...any) (d TargetDistinguishedNames)

TDNs returns a new instance of TargetDistinguishedNames with an initialized embedded stack configured to function as a simple ORed list containing a single level of LDAP distinguished names. The Target (target) keyword is automatically assigned to the return value.

Only valid instances of TargetDistinguishedName which bear the Target keyword are to be considered eligible for push requests. If the input value is a string, it will be accepted and properly branded with the keyword.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the TargetDistinguishedName type (or its string equivalent) for push during initialization. This is merely a more convenient alternative to separate init and push procedures.

See also the TTDNs and TFDNs functions for TargetTo and TargetFrom keywords respectively.

Example 
tdns := TDNs(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=courtney,ou=People,dc=example,dc=com`,
)
fmt.Printf("%s contains %d DNs", tdns.Keyword(), tdns.Len())

Output:

target contains 2 DNs

func TFDNs 

func TFDNs(x ...any) (d TargetDistinguishedNames)

TFDNs returns a new instance of TargetDistinguishedNames with an initialized embedded stack configured to function as a simple ORed list containing a single level of LDAP distinguished names. The TargetFrom (target_from) keyword will be automatically assigned to the return value.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the TargetDistinguishedName type (or its string equivalent) for push during initialization. This is merely a more convenient alternative to separate init and push procedures.

Only valid instances of TargetDistinguishedName which bear the TargetFrom keyword are to be considered eligible for push requests. If the input value is a string, it will be accepted and properly branded with the keyword.

See also the TDNs and TTDNs functions for Target and TargetTo keywords respectively.

Example 
tdns := TFDNs(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=courtney,ou=People,dc=example,dc=com`,
)
fmt.Printf("%s contains %d DNs", tdns.Keyword(), tdns.Len())

Output:

target_from contains 2 DNs

func TTDNs 

func TTDNs(x ...any) (d TargetDistinguishedNames)

TTDNs returns a new instance of TargetDistinguishedNames with an initialized embedded stack configured to function as a simple ORed list containing a single level of LDAP distinguished names. The TargetTo (target_to) keyword is automatically assigned to the return value.

Only valid instances of TargetDistinguishedName which bear the TargetTo keyword are to be considered eligible for push requests. If the input value is a string, it will be accepted and properly branded with the keyword.

Optionally, the caller may choose to submit one (1) or more (valid) instances of the TargetDistinguishedName type (or its string equivalent) for push during initialization. This is merely a more convenient alternative to separate init and push procedures.

See also the TDNs and TFDNs functions for Target and TargetFrom keywords respectively.

Example 
tdns := TTDNs(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=courtney,ou=People,dc=example,dc=com`,
)
fmt.Printf("%s contains %d DNs", tdns.Keyword(), tdns.Len())

Output:

target_to contains 2 DNs

func (TargetDistinguishedNames) Compare 

func (r TargetDistinguishedNames) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) instances of BindDistinguishedNames using the Compare method.

The comparison evaluates as false because, while the contents match, their ordering does not. 

adns := TFDNs(`uid=jesse,ou=People,dc=example,dc=com`, `uid=courtney,ou=People,dc=example,dc=com`)
odns := TFDNs(`uid=courtney,ou=People,dc=example,dc=com`, `uid=jesse,ou=People,dc=example,dc=com`)

fmt.Printf("Hashes are equal: %t", odns.Compare(adns))

Output:

Hashes are equal: false

func (TargetDistinguishedNames) Contains 

func (r TargetDistinguishedNames) Contains(x any) bool

Contains returns a Boolean value indicative of whether value x, if a string or TargetDistinguishedName instance, already resides within the receiver instance.

Case is not significant in the matching process.

Example 
dn := TFDNs(
	`cn=*,ou=Profiles,dc=example,dc=com`,
	`cn=*,ou=People,dc=example,dc=com`,
)

groups := `cn=*,ou=Groups,dc=example,dc=com`

fmt.Printf("Found: %t", dn.Contains(groups))

Output:

Found: false

func (TargetDistinguishedNames) Eq 

func (r TargetDistinguishedNames) Eq() TargetRule

Eq initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Equal-To one (1) of the following keyword contexts:

• `target`

• `target_to`

• `target_from`

Example 
var dn TargetDistinguishedNames = TDNs(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn.Eq())

Output:

( target = "ldap:///uid=jesse,ou=People,dc=example,dc=com" )

func (TargetDistinguishedNames) F 

func (r TargetDistinguishedNames) F() func(string) TargetDistinguishedName

F returns the appropriate instance creator function for crafting individual TargetDistinguishedName instances for submission to the receiver. This is merely a convenient alternative to maintaining knowledge as to which function applies to the current receiver instance.

The default is TDN, and will be returned if the receiver is uninitialized, or if the Keyword associated with the receiver is invalid somehow. Otherwise, TTDN is returned for TargetTo, and TFDN for TargetFrom.

Example 
var odns TargetDistinguishedNames = TDNs()
funk := odns.F()
odns.Push(funk(`uid=jesse,ou=People,dc=example,dc=com`))

fmt.Printf("%s", odns)

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com

func (TargetDistinguishedNames) ID 

func (r TargetDistinguishedNames) ID() string

ID returns the string literal `target`.

Example 
var dn TargetDistinguishedNames
fmt.Printf("%s", dn.ID())

Output:

target

func (TargetDistinguishedNames) Index 

func (r TargetDistinguishedNames) Index(idx int) (t TargetDistinguishedName)

Index wraps go-stackage's Stack.Index method. Note that the Boolean OK value returned by go-stackage by default will be shadowed and not obtainable by the caller.

Example

This example demonstrates the call of a select slice member from the receiver using the Index method. 

odns := TFDNs(`uid=jesse,ou=People,dc=example,dc=com`, `uid=courtney,ou=People,dc=example,dc=com`)

fmt.Printf("%s", odns.Index(0))

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com

func (TargetDistinguishedNames) IsZero 

func (r TargetDistinguishedNames) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example 
var odns TargetDistinguishedNames
fmt.Printf("Zero: %t", odns.IsZero())

Output:

Zero: true

func (TargetDistinguishedNames) Keyword 

func (r TargetDistinguishedNames) Keyword() (kw Keyword)

Keyword returns the Keyword (interface) assigned to the receiver instance. This shall be the keyword that appears in a BindRule bearing the receiver as a condition value.

Example 
var dn TargetDistinguishedNames = TDNs(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("Keyword: %s", dn.Keyword())

Output:

Keyword: target

func (TargetDistinguishedNames) Len 

func (r TargetDistinguishedNames) Len() int

Len wraps go-stackage's Stack.Len method.

Example 
var odns TargetDistinguishedNames = TDNs()
funk := odns.F()
odns.Push(funk(`uid=jesse,ou=People,dc=example,dc=com`))

fmt.Printf("Length: %d", odns.Len())

Output:

Length: 1

func (TargetDistinguishedNames) Ne 

func (r TargetDistinguishedNames) Ne() TargetRule

Ne initializes and returns a new TargetRule instance configured to express the evaluation of the receiver value as Not-Equal-To one (1) of the following keyword contexts:

• `target`

• `target_to`

• `target_from`

Negated equality TargetRule instances should be used with caution.

Example 
var dn TargetDistinguishedNames = TDNs(`uid=jesse,ou=People,dc=example,dc=com`)
fmt.Printf("%s", dn.Ne())

Output:

( target != "ldap:///uid=jesse,ou=People,dc=example,dc=com" )

func (TargetDistinguishedNames) Pop 

func (r TargetDistinguishedNames) Pop() (popped TargetDistinguishedName)

Pop wraps go-stackage's Stack.Pop method and performs type assertion to return a proper TargetDistinguishedName instance.

Example 
var odns TargetDistinguishedNames = TDNs()
odns.Push(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=jimmy,ou=People,dc=example,dc=com`,
)

popped := odns.Pop()

fmt.Printf("%s", popped)

Output:

ldap:///uid=jimmy,ou=People,dc=example,dc=com

func (TargetDistinguishedNames) Push 

func (r TargetDistinguishedNames) Push(x ...any) TargetDistinguishedNames

Push wraps go-stackage's Stack.Push method. Valid input types are string and TargetDistinguishedName.

In the case of a string value, it is automatically cast as an instance of TargetDistinguishedName using the appropriate keyword, so long as the raw string is of a non-zero length.

Example 
var odns TargetDistinguishedNames = TDNs()
odns.Push(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=jimmy,ou=People,dc=example,dc=com`,
)

fmt.Printf("Length: %d", odns.Len())

Output:

Length: 2

func (TargetDistinguishedNames) String 

func (r TargetDistinguishedNames) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example 
var odns TargetDistinguishedNames = TDNs()
odns.Push(
	`uid=jesse,ou=People,dc=example,dc=com`,
	`uid=jimmy,ou=People,dc=example,dc=com`,
)

fmt.Printf("%s", odns)

Output:

ldap:///uid=jesse,ou=People,dc=example,dc=com || ldap:///uid=jimmy,ou=People,dc=example,dc=com

func (TargetDistinguishedNames) TRM 

func (r TargetDistinguishedNames) TRM() TargetRuleMethods

TRM returns an instance of TargetRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of TargetRule instances which bear the receiver instance as an expression value. The value for each key is the actual TargetRuleMethod instance for OPTIONAL use in the creation of a TargetRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus TargetRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var dn TargetDistinguishedNames
fmt.Printf("%d available comparison operator methods", dn.TRM().Len())

Output:

2 available comparison operator methods

func (TargetDistinguishedNames) Valid 

func (r TargetDistinguishedNames) Valid() error

Valid wraps go-stackage's Stack.Valid method.

Example 
var odns TargetDistinguishedNames
fmt.Printf("Valid: %t", odns.Valid() == nil)

Output:

Valid: false

type TargetKeyword 

type TargetKeyword uint8

TargetKeyword contains the value describing a particular Target Keyword to be used within a Target Rule.

Example

This example demonstrates the interrogation of TargetKeyword const definitions. This type qualifies for the Keyword interface type.

There are a total of nine (9) such TargetKeyword definitions. 

for idx, tk := range []TargetKeyword{
	Target,
	TargetTo,
	TargetAttr,
	TargetCtrl,
	TargetFrom,
	TargetScope,
	TargetFilter,
	TargetAttrFilters,
	TargetExtOp,
} {
	fmt.Printf("[%s] %d/%d: %s\n",
		tk.Kind(), idx+1, 9, tk)
}

Output:

[target] 1/9: target
[target] 2/9: target_to
[target] 3/9: targetattr
[target] 4/9: targetcontrol
[target] 5/9: target_from
[target] 6/9: targetscope
[target] 7/9: targetfilter
[target] 8/9: targattrfilters
[target] 9/9: extop

const (
	Target            TargetKeyword // 0x1, target
	TargetTo                        // 0x2, target_to
	TargetAttr                      // 0x3, targetattr
	TargetCtrl                      // 0x4, targetcontrol
	TargetFrom                      // 0x5, target_from
	TargetScope                     // 0x6, targetscope
	TargetFilter                    // 0x7, targetfilter
	TargetAttrFilters               // 0x8, targattrfilters (yes, "targ". As in "wild Klingon boars").
	TargetExtOp                     // 0x9, extop
)

TargetKeyword constants are intended for singular use within a Target Rule condition.

func (TargetKeyword) Kind 

func (r TargetKeyword) Kind() string

Kind returns the string name for the kind of underlying Keyword (`target`).

Example 
fmt.Printf("%s", TargetAttrFilters.Kind())

Output:

target

func (TargetKeyword) String 

func (r TargetKeyword) String() (k string)

String is a stringer method that returns the string representation of the receiver instance of TargetKeyword.

Example 
fmt.Printf("%s", TargetScope)

Output:

targetscope

type TargetRule 

type TargetRule stackage.Condition

TargetRule is a stackage.Condition type alias intended to represent a single Target Rule; that is, one (1) Target Rule keyword, one (1) comparison operator and one (1) or more string values (called an 'expression').

For example: 

( targetscope = "subordinate" )

Instances of this type may be assembled manually by users, or may be created logically as a result of textual parsing. Users may also want to use convenient Eq and Ne methods extended through various types (as permitted) for simplicity.

Instances of this type shall appear within TargetRules instances.

TargetRule instances are always parenthetical. No parenthetical control methods exist for instances of this type.

Example 
var tgt TargetRule = TR(
	TargetScope,
	Eq,
	Subordinate,
)

fmt.Printf("%s", tgt)

Output:

( targetscope = "subordinate" )

func ParseTargetRule 

func ParseTargetRule(raw string) (TargetRule, error)

ParseTargetRule processes the raw input string value, which should represent a single Target Rule expressive statement, into an instance of TargetRule. This, along with an error instance, are returned upom completion of processing.

Example

This example demonstrates the imported ANTLR4-based go-antlraci parser capabilities as they pertain to the handling of raw target rule text. 

// NOTE: padding manually stripped out, and an
// extraneous horizontal tab (ASCII #9) added
// for purely demonstrative reasons ...
raw := `(target_to=     "ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com")`
tr, err := ParseTargetRule(raw)
if err != nil {
	fmt.Println(err) // always check your parser errors.
	return
}
fmt.Printf("%s", tr)

Output:

( target_to = "ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com" )
Example (MultiValuedWithAlternativeQuotation)

This example demonstrates the imported ANTLR4-based go-antlraci parser capabilities as they pertain to the handling of raw target rule text that contains multiple values with specific delimiters and alternative quotation. 

raw := `(target_to="ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com||ldap:///cn=*,ou=X.500 Administrators,ou=People,dc=example,dc=com")`
tr, err := ParseTargetRule(raw)
if err != nil {
	fmt.Println(err) // always check your parser errors.
	return
}
fmt.Printf("%s", tr)

Output:

( target_to = "ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com || ldap:///cn=*,ou=X.500 Administrators,ou=People,dc=example,dc=com" )
Example (MultiValuedWithStandardQuotation)

This example demonstrates the imported ANTLR4-based go-antlraci parser capabilities as they pertain to the handling of raw target rule text that contains multiple values with specific delimiters and standard quotation.

Additionally, upon receiving the returned value, we'll disable padding just for fun. 

raw := `(target_to="ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com"||"ldap:///cn*,ou=X.500 Administrators,ou=People,dc=example,dc=com")`
tr, err := ParseTargetRule(raw)
if err != nil {
	fmt.Println(err) // always check your parser errors.
	return
}
fmt.Printf("%s", tr.NoPadding(true))

Output:

(target_to="ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com" || "ldap:///cn*,ou=X.500 Administrators,ou=People,dc=example,dc=com")

func TR 

func TR(kw, op, ex any) TargetRule

TR wraps go-stackage's Cond package-level function. In this context, it is wrapped here to assemble and return a TargetRule instance using the so-called "one-shot" procedure. This is an option only when ALL information necessary for the process is in-hand and ready for user input: the keyword, comparison operator and the appropriate value(s) expression.

Use of this function shall not require a subsequent call of TargetRule's Init method, which is needed only for so-called "piecemeal" TargetRule assembly.

Use of this function is totally optional. Users may, instead, opt to populate the specific value instance(s) needed and execute the type's own Eq, Ne, Ge, Gt, Le and Lt methods (when applicable) to produce an identical return instance. Generally speaking, those methods may prove to be more convenient -- and far safer -- than use of this function.

Example

This example demonstrates the creation of a TargetRule in a completely manual way. Users will almost certainly want to use the (far easier) methods for Eq, Ne, etc., extended via the very type instances intended for representation within a rule. 

var rule TargetRule = TR(TargetScope, Eq, SingleLevel)
fmt.Printf("%s", rule)

Output:

( targetscope = "onelevel" )

func (TargetRule) Category 

func (r TargetRule) Category() string

Category wraps go-stackage's Condition.Category method.

Example 
fmt.Printf("%s", BaseObject.Eq().Category())

Output:

targetscope

func (TargetRule) Compare 

func (r TargetRule) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
tdn1 := TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq()
tdn2 := TDN(`uid=jesse,ou=People,dc=example,dc=com`).Ne()
fmt.Printf("Equal: %t", tdn1.Compare(tdn2))

Output:

Equal: false

func (TargetRule) Expression 

func (r TargetRule) Expression() any

Expression wraps go-stackage's Condition.Expression method.

Example 
tfdn := `uid=*,ou=Contractors,ou=People,dc=example,dc=com`
fmt.Printf("%s", TFDN(tfdn).Eq().Expression())

Output:

ldap:///uid=*,ou=Contractors,ou=People,dc=example,dc=com

func (TargetRule) ID 

func (r TargetRule) ID() string

ID returns the string literal `target`.

Example 
fmt.Printf("%s", BaseObject.Eq().ID())

Output:

target

func (*TargetRule) Init 

func (r *TargetRule) Init() TargetRule

Init wraps stackage.Condition's Init method. This is a required method for situations involving the piecemeal (step-by-step) assembly of an instance of TargetRule as opposed to a one-shot creation using the TR package-level function. It is also an ideal means for the creation of a TargetRule instance when one does not immediately possess all of the needed pieces of information (i.e.: uncertain which keyword to use, or when an expression value has not yet been determined, etc).

Call this method after a variable declaration but before your first change, e.g.: 

var tr TargetRule
... do other things ...
... we're ready to set something now ...
tr.Init()
tr.SetKeyword("blarg")
tr.SetSomethingElse(...)
...

Init need only be executed once within the lifespan of a TargetRule instance. Its execution shall result in a completely new embedded pointer instance supplanting the previous one.

One may choose, however, to re-execute this method IF this instance shall be reused (perhaps in a repetative or looped manner), and if it would be desirable to 'wipe the slate clean' for some reason.

Example 
var tr TargetRule
tr.Init() // required when assembly through "piecemeal"

// ... later in your code ...

tr.SetKeyword(Target) // set keyword ...
tr.SetOperator(Ne)    // ... so operator can be evaluated
fmt.Printf("Operator: %s", tr.Operator().Description())

Output:

Operator: Not Equal To

func (TargetRule) IsZero 

func (r TargetRule) IsZero() bool

IsZero wraps go-stackage's Condition.IsZero method.

Example 
var tr TargetRule
fmt.Printf("Zero: %t", tr.IsZero())

Output:

Zero: true

func (TargetRule) Keyword 

func (r TargetRule) Keyword() Keyword

Keyword wraps go-stackage's Condition.Keyword method and resolves the raw value into a TargetKeyword. Failure to do so will return a bogus Keyword.

Example 
fmt.Printf("%s", BaseObject.Eq().Keyword())

Output:

targetscope

func (TargetRule) Kind 

func (r TargetRule) Kind() string

Kind returns the string literal `condition` to identify the receiver as a stackage.Condition type alias.

Example 
var tr TargetRule
fmt.Printf("%s", tr.Kind())

Output:

condition

func (TargetRule) Len 

func (r TargetRule) Len() int

Len performs no significantly useful task. This method exists to satisfy Go's interface signature requirements.

When executed on a nil instance, an abstract length of zero (0) is returned. When executed on a non-nil instance, an abstract length of one (1) is returned.

Example

This example demonstrates the (mostly) useless execution of the Len method, as singular TargetRule instances are generally not judged in terms of length, whether value-based or through some other abstraction.

As such, the execution of this method shall always return one (1) when executed on a non-nil instance, and zero (0) otherwise. 

var tr TargetRule
if err := tr.Parse(`( targetscope="onelevel")`); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}
fmt.Printf("%T.Len: %d", tr, tr.Len())

Output:

aci.TargetRule.Len: 1

func (TargetRule) NoPadding 

func (r TargetRule) NoPadding(state ...bool) TargetRule

NoPadding wraps go-stackage's Condition.NoPadding method.

Example 
f := `(&(objectClass=*)(employeeStatus=ACTIVE))`

fmt.Printf("%s", Filter(f).Ne().NoPadding())

Output:

(targetfilter!="(&(objectClass=*)(employeeStatus=ACTIVE))")

func (TargetRule) Operator 

func (r TargetRule) Operator() ComparisonOperator

Operator wraps go-stackage's Condition.Operator method.

Example 
cond := Filter(`(&(objectClass=*)(status=ACTIVE))`).Ne()
fmt.Printf("%s", cond.Operator())

Output:

!=

func (*TargetRule) Parse 

func (r *TargetRule) Parse(raw string) error

Parse returns an error based upon an attempt to parse the raw input value into the receiver instance. If successful, any contents within the receiver instance would be obliterated, replaced irrevocably by the freshly parsed values.

Both this method, and the package-level ParseTargetRule function, call antlraci's ParseTargetRule function in similar fashion. The only real difference here is the process of writing to a receiver, versus writing to an uninitialized variable declaration.

Example

This example demonstrates the parsing of a single TargetRule condition. 

raw := `(targetattr != "aci")"`
var tr TargetRule
if err := tr.Parse(raw); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%s", tr.Expression())

Output:

aci

func (TargetRule) SetExpression 

func (r TargetRule) SetExpression(expr any) TargetRule

SetExpression wraps go-stackage's Condition.SetExpression method.

Example 
var tgt TargetRule
tgt.Init()
tgt.SetKeyword(TargetAttr)
tgt.SetOperator(Ne)
tgt.SetExpression(AT(`aci`))

fmt.Printf("%s", tgt)

Output:

( targetattr != "aci" )

func (TargetRule) SetKeyword 

func (r TargetRule) SetKeyword(kw any) TargetRule

SetKeyword wraps go-stackage's Condition.SetKeyword method.

Example 
var tgt TargetRule
tgt.Init()
tgt.SetKeyword(TargetAttr)
tgt.SetOperator(Ne)
tgt.SetExpression(AT(`aci`))

fmt.Printf("%s", tgt)

Output:

( targetattr != "aci" )

func (TargetRule) SetOperator 

func (r TargetRule) SetOperator(op any) TargetRule

SetOperator wraps go-stackage's Condition.SetOperator method. Valid input types are ComparisonOperator or its string value equivalent (e.g.: `>=` for Ge).

Example 
var tgt TargetRule
tgt.Init()
tgt.SetKeyword(TargetAttr)
tgt.SetOperator(Ne)
tgt.SetExpression(AT(`aci`))

fmt.Printf("%s", tgt)

Output:

( targetattr != "aci" )

func (TargetRule) SetQuoteStyle 

func (r TargetRule) SetQuoteStyle(style int) TargetRule

SetQuoteStyle allows the election of a particular multivalued quotation style offered by the various adopters of the ACIv3 syntax. In the context of a TargetRule, this will only have a meaningful impact if the keyword for the receiver is one (1) of the following:

  • Target (target)
  • TargetTo (target_to)
  • TargetFrom (target_from)
  • TargetAttr (targetattr)
  • TargetCtrl (targetcontrol)
  • TargetExtOp (extop)

The underlying expression type must be a TargetDistinguishedNames instance for Target-related keywords, an ObjectIdentifiers instance for OID-related keywords, or simply an AttributeTypes instance for the TargetAttr keyword.

See the const definitions for MultivalOuterQuotes (default) and MultivalSliceQuotes for details.

Example 
var tgt TargetRule
tgt.Init()

tgt.SetKeyword(Target)
tgt.SetOperator(Ne)
tgt.SetExpression(TDNs(
	TDN(`ldap:///uid=jesse,ou=People,dc=example,dc=com`),
	TDN(`ldap:///uid=courtney,ou=People,dc=example,dc=com`),
	TDN(`ldap:///uid=jimmy,ou=People,dc=example,dc=com`),
))

tgt.SetQuoteStyle(0)
style1 := tgt.String()

tgt.SetQuoteStyle(1)
style2 := tgt.String()

fmt.Printf("\n0: %s\n1: %s", style1, style2)

Output:

0: ( target != "ldap:///uid=jesse,ou=People,dc=example,dc=com" || "ldap:///uid=courtney,ou=People,dc=example,dc=com" || "ldap:///uid=jimmy,ou=People,dc=example,dc=com" )
1: ( target != "ldap:///uid=jesse,ou=People,dc=example,dc=com || ldap:///uid=courtney,ou=People,dc=example,dc=com || ldap:///uid=jimmy,ou=People,dc=example,dc=com" )

func (TargetRule) String 

func (r TargetRule) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Condition.String method.

Example (NegatedTargetFilter) 
fmt.Printf("%s", Filter(`(&(objectClass=*)(employeeStatus=ACTIVE))`).Ne())

Output:

( targetfilter != "(&(objectClass=*)(employeeStatus=ACTIVE))" )
Example (TargetScope) 
fmt.Printf("%s", BaseObject.Eq())

Output:

( targetscope = "base" )
Example (Traditional) 
var tgt TargetRule = TR(
	TargetFrom,
	Ne,
	TFDN(`uid=*,ou=Contractors,ou=People,dc=example,dc=com`),
)

fmt.Printf("%s", tgt)

Output:

( target_from != "ldap:///uid=*,ou=Contractors,ou=People,dc=example,dc=com" )

func (TargetRule) Valid 

func (r TargetRule) Valid() (err error)

Valid wraps go-stackage's Condition.Valid method.

Example 
var tr TargetRule
fmt.Printf("Valid: %t", tr.Valid() == nil)

Output:

Valid: false

type TargetRuleMethod 

type TargetRuleMethod func() TargetRule

TargetRuleMethod is the closure signature for methods used to build new instances of TargetRule.

The signature is qualified by the following methods extended through all eligible types defined in this package:

• Eq

• Ne

Note that TargetRule instances only support a very limited subset of these methods when compared to BindRule instances. In fact, some TargetRule instances only support ONE such method: Eq.

Example 
tfil := Filter(`(&(objectClass=employee)(terminated=FALSE))`)
trm := tfil.TRM()

// verify that the receiver (ssf) is copacetic
// and will produce a legal expression if meth
// is executed
if err := trm.Valid(); err != nil {
	fmt.Println(err)
	return
}

for i := 0; i < trm.Len(); i++ {
	// IMPORTANT: Do not call index 0. Either adjust your
	// loop variable (i) to begin at 1, and terminate at
	// trm.Len()+1 --OR-- simply +1 the index call as we
	// are doing here (seems easier). The reason for this
	// is because there is no valid ComparisonOperator
	// with an underlying uint8 value of zero (0). See
	// the ComparisonOperator constants for details.
	idx := i + 1
	cop, meth := trm.Index(idx)

	// execute method to create the targetrule
	rule := meth()

	// grab the raw string output
	fmt.Printf("[%d] %T instance [%s] execution returned %T: %s\n", idx, meth, cop.Context(), rule, rule)
}

Output:

[1] aci.TargetRuleMethod instance [Eq] execution returned aci.TargetRule: ( targetfilter = "(&(objectClass=employee)(terminated=FALSE))" )
[2] aci.TargetRuleMethod instance [Ne] execution returned aci.TargetRule: ( targetfilter != "(&(objectClass=employee)(terminated=FALSE))" )

type TargetRuleMethods 

type TargetRuleMethods struct {
	// contains filtered or unexported fields
}

TargetRuleMethods contains one (1) or more instances of TargetRuleMethod, representing a particular TargetRule "builder" method for execution by the caller.

See the Operators method extended through all eligible types for further details.

Example

This example demonstrates the indexing, iteration and execution of the available TargetRuleMethod instances for the TargetDistinguishedName type. 

var tdn TargetDistinguishedName = TTDN(`uid=*,ou=People,dc=example,dc=com`)
trm := tdn.TRM()

for i := 0; i < trm.Len(); i++ {
	cop, meth := trm.Index(i + 1) // zero (0) should never be accessed, start at 1
	fmt.Printf("[%s] %s\n", cop.Description(), meth())
}

Output:

[Equal To] ( target_to = "ldap:///uid=*,ou=People,dc=example,dc=com" )
[Not Equal To] ( target_to != "ldap:///uid=*,ou=People,dc=example,dc=com" )

func (TargetRuleMethods) Contains 

func (r TargetRuleMethods) Contains(cop any) bool

Contains returns a Boolean value indicative of whether the specified ComparisonOperator, which may be expressed as a string, int or native ComparisonOperator, is allowed for use by the type instance that created the receiver instance. This method offers a convenient alternative to the use of the Index method combined with an assertion value (such as Eq, Ne, "=", "Greater Than", et al).

In other words, if one uses the TargetDistinguishedName.TRM method to create an instance of TargetRuleMethods, feeding Gt (Greater Than) to this method shall return false, as no TargetRule context allows mathematical comparison.

func (TargetRuleMethods) Index 

func (r TargetRuleMethods) Index(idx any) (ComparisonOperator, TargetRuleMethod)

Index calls the input index (idx) within the internal structure of the receiver instance. If found, an instance of ComparisonOperator and its accompanying TargetRuleMethod instance are returned.

Valid input index types are integer (int), ComparisonOperator constant or string identifier. In the case of a string identifier, valid values are as follows:

• For Eq (1): `=`, `Eq`, `Equal To`

• For Ne (2): `=`, `Ne`, `Not Equal To`

• For Lt (3): `=`, `Lt`, `Less Than`

• For Le (4): `=`, `Le`, `Less Than Or Equal`

• For Gt (5): `=`, `Gt`, `Greater Than`

• For Ge (6): `=`, `Ge`, `Greater Than Or Equal`

Case is not significant in the string matching process.

Please note that use of this method by way of integer or ComparisonOperator values utilizes fewer resources than a string lookup.

See the ComparisonOperator type's Context, String and Description methods for accessing the above string values easily.

If the index was not matched, an invalid ComparisonOperator is returned alongside a nil TargetRuleMethod. This will also apply to situations in which the type instance which crafted the receiver is uninitialized, or is in an otherwise aberrant state.

Example 
var dn TargetDistinguishedName = TFDN(`uid=*,ou=People,dc=example,dc=com`)
trm := dn.TRM()

for i := 0; i < trm.Len(); i++ {
	// IMPORTANT: Do not call index 0. Either adjust your
	// loop variable (i) to begin at 1, and terminate at
	// trm.Len()+1 --OR-- simply +1 the index call as we
	// are doing here (seems easier). The reason for this
	// is because there is no valid ComparisonOperator
	// with an underlying uint8 value of zero (0). See
	// the ComparisonOperator constants for details.
	idx := i + 1
	cop, meth := trm.Index(idx)

	// execute method to create the targetrule
	rule := meth()

	// grab the raw string output
	fmt.Printf("[%d] %T instance [%s] execution returned %T: %s\n", idx, meth, cop.Context(), rule, rule)
}

Output:

[1] aci.TargetRuleMethod instance [Eq] execution returned aci.TargetRule: ( target_from = "ldap:///uid=*,ou=People,dc=example,dc=com" )
[2] aci.TargetRuleMethod instance [Ne] execution returned aci.TargetRule: ( target_from != "ldap:///uid=*,ou=People,dc=example,dc=com" )
Example (ByText) 
attrs := TAs(`cn`, `sn`, `givenName`, `objectClass`, `uid`, `homeDirectory`)
trm := attrs.TRM()

// Here, we demonstrate calling a particular TargetRuleMethod
// not by its numerical index, but rather by its actual
// "symbolic" operator representation. Keep in mind these
// options for text-based searches:
//
// - symbols (e.g.: '=', '>') are available via ComparisonOperator.String()
// - func names (e.g.: 'Eq', 'Gt') are available via ComparisonOperator.Context()
// - descriptions (e.g.: 'Not Equal To', 'Less Than') are available via ComparisonOperator.Description()
//
// As such, feel free to replace these list items with one of the above methods,
// but keep in mind that text based searches are more resource intensive than as
// compared to direct ComparisonOperator numeric calls. If you have performance
// concerns, avoid this text based procedure.
for i, term := range []string{
	`=`,
	`!=`,
} {
	// IMPORTANT: Do not call index 0. Either adjust your
	// loop variable (i) to begin at 1, and terminate at
	// trm.Len()+1 --OR-- simply +1 the index call as we
	// are doing here (seems easier). The reason for this
	// is because there is no valid ComparisonOperator
	// with an underlying uint8 value of zero (0). See
	// the ComparisonOperator constants for details.
	cop, meth := trm.Index(term)

	// execute method to create the TargetRule, while
	// enabling the so-called "Slice Quotation scheme"
	// for one of the iterations (just for fun!)
	rule := meth().SetQuoteStyle(i)

	// grab the raw string output
	fmt.Printf("[%d] %T instance [%s] execution returned %T: %s\n", i+1, meth, cop.Context(), rule, rule)
}

Output:

[1] aci.TargetRuleMethod instance [Eq] execution returned aci.TargetRule: ( targetattr = "cn" || "sn" || "givenName" || "objectClass" || "uid" || "homeDirectory" )
[2] aci.TargetRuleMethod instance [Ne] execution returned aci.TargetRule: ( targetattr != "cn || sn || givenName || objectClass || uid || homeDirectory" )

func (TargetRuleMethods) IsZero 

func (r TargetRuleMethods) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var trm TargetRuleMethods
fmt.Printf("Zero: %t", trm.IsZero())

Output:

Zero: true

func (TargetRuleMethods) Len 

func (r TargetRuleMethods) Len() int

Len returns the integer length of the receiver. Note that the return value will NEVER be less than zero (0) nor greater than six (6).

Example 
// Note: we need not populate the value to get a
// TRM list, but the methods in that list won't
// actually work until the instance (ssf) is in
// an acceptable state. Since all we're doing
// here is checking the length, a receiver that
// is nil/zero is totally fine.
var sco SearchScope = SingleLevel // any would do
total := sco.TRM().Len()

fmt.Printf("There is one (%d) available aci.TargetRuleMethod instance for creating %T TargetRules", total, sco)

Output:

There is one (1) available aci.TargetRuleMethod instance for creating aci.SearchScope TargetRules

func (TargetRuleMethods) Valid 

func (r TargetRuleMethods) Valid() (err error)

Valid returns the first encountered error returned as a result of execution of the first available TargetRuleMethod instance. This is useful in cases where a user wants to see if the desired instance(s) of TargetRuleMethod will produce a usable result.

Example 
var trm TargetRuleMethods
fmt.Printf("Error: %v", trm.Valid())

Output:

Error: aci.TargetRuleMethods instance is nil

type TargetRules 

type TargetRules stackage.Stack

TargetRules is a stackage.Stack type alias intended to store and express one (1) or more Target Rule statements.

For example: 

( targetscope = "subordinate" )( targetattr = "cn || sn || givenName || objectClass" )

Instances of this type may be assembled manually by users, or may be created logically as a result of textual parsing. See the T function for easily initializing and returning instances of this type.

Instances of this type will not allow nesting (i.e.: the addition of any stackage.Stack type alias instances). Only individual TargetRule instances may be pushed into instances of this type.

func ParseTargetRules 

func ParseTargetRules(raw string) (TargetRules, error)

ParseTargetRules processes the raw input string value, which should represent one (1) or more valid Target Rule expressive statements, into an instance of TargetRules. This, alongside an error instance, are returned at the completion of processing.

Example

This example demonstrates the imported ANTLR4-based go-antlraci parser capabilities as they pertain to the handling of a sequence of raw target rule text values. Note in this example, we've added awkward spacing mixed-in with fair attempts to make the sequence of TargetRule expressions easier to read. This includes newline characters (ASCII #10) to really try and mess things up. 😈 

omg := `(
                target_to=
                        "ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com"               ||
                        "ldap:///cn=*,ou=X.500 Administrators,ou=People,dc=example,dc=com"      ||
                        "ldap:///cn=*,ou=Executives,ou=People,dc=example,dc=com"
                )

                ( targetscope="subordinate"  )

                (
                        targattrfilters =
                                "add=nsroleDN:(!(nsroledn=cn=X.500 Administrator)) && employeeStatus:(!(drink=beer)) && telephoneNumber:(telephoneNumber=612*)"
                )`

tr, err := ParseTargetRules(omg)
if err != nil {
	fmt.Println(err) // always check your parser errors.
	return
}

fmt.Printf("%s", tr)

Output:

( target_to = "ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com" || "ldap:///cn=*,ou=X.500 Administrators,ou=People,dc=example,dc=com" || "ldap:///cn=*,ou=Executives,ou=People,dc=example,dc=com" )( targetscope = "subordinate" )( targattrfilters = "add=nsroleDN:(!(nsroledn=cn=X.500 Administrator)) && employeeStatus:(!(drink=beer)) && telephoneNumber:(telephoneNumber=612*)" )
Example (AlternativeQuotation)

This example is the same as the TargetRules example, except with the alternative quotation scheme in effect. 

omg := `(
                target_to=
                        "ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com                ||
                         ldap:///cn=*,ou=X.500 Administrators,ou=People,dc=example,dc=com       ||
                         ldap:///cn=*,ou=Executives,ou=People,dc=example,dc=com"
                )

                ( targetscope=
                                "subordinate"
                )

                ( targattrfilters =
                                "add=nsroleDN:(!(nsroledn=cn=X.500 Administrator))      &&
                                 employeeStatus:(!(drink=beer))                         &&
                                 telephoneNumber:(telephoneNumber=612*)"
                )`

tr, err := ParseTargetRules(omg)
if err != nil {
	fmt.Println(err) // always check your parser errors.
	return
}

fmt.Printf("%s", tr)

Output:

( target_to = "ldap:///cn=*,ou=Contractors,ou=People,dc=example,dc=com || ldap:///cn=*,ou=X.500 Administrators,ou=People,dc=example,dc=com || ldap:///cn=*,ou=Executives,ou=People,dc=example,dc=com" )( targetscope = "subordinate" )( targattrfilters = "add=nsroleDN:(!(nsroledn=cn=X.500 Administrator)) && employeeStatus:(!(drink=beer)) && telephoneNumber:(telephoneNumber=612*)" )

func TRs 

func TRs(x ...any) (t TargetRules)

TRs creates and returns a new instance of TargetRules with an initialized embedded stack configured to function as a Target Rule store that is meant to contain one (1) or more Condition instances, each of which bear one (1) of the following Target Rule keyword constants:

• Target

• TargetTo

• TargetFrom

• TargetAttr

• TargetCtrl

• TargetScope

• TargetFilter

• TargetAttrFilters

• TargetExtOp

Optionally, the caller may choose to submit one (1) or more (valid) instances of the TargetRule type (or its string equivalent) during initialization. This is merely a more convenient alternative to separate initialization and push procedures.

Please note that instances of this design are set with a maximum capacity of nine (9) for both the following reasons:

• There are only said number of Target Rule keywords supported within the ACI syntax specification honored by this package, and ...

• Individual Target Rule keywords can only be used once per ACI; in other words, one cannot specify multiple `target` conditions within the same TargetRules instance.

Instances of this design generally are assigned to top-level instances of Instruction, and never allow nesting elements (e.g.: other stackage.Stack derived type aliases).

Padding is disabled by default, meaning there shall be no whitespace residing between individual TargetRule instances. This behavior can be altered using the NoPadding method.

Example

This example demonstrates how to craft a set of Target Rule Conditions. 

t := TRs().Push(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	Filter(`(&(uid=jesse)(objectClass=*))`).Eq(),
	ExtOp(`1.3.6.1.4.1.56521.999.5`).Eq(),
)
fmt.Printf("%s", t)

Output:

( target = "ldap:///uid=jesse,ou=People,dc=example,dc=com" )( targetfilter = "(&(uid=jesse)(objectClass=*))" )( extop = "1.3.6.1.4.1.56521.999.5" )

func (TargetRules) Category 

func (r TargetRules) Category() string

Category returns the string literal `target`.

Example 
var trs TargetRules
fmt.Printf("%s", trs.Category())

Output:

target

func (TargetRules) Compare 

func (r TargetRules) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example 
trs1 := TRs()
tdn1 := TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq()
tfdn1 := TFDN(`ou=People,dc=example,dc=com`).Eq()

trs2 := TRs()
tf2 := Filter(`(objectClass=*`).Eq()
tsc2 := SingleLevel.Eq()

trs1.Push(tdn1, tfdn1)
trs2.Push(tf2, tsc2)

fmt.Printf("Equal: %t", trs1.Compare(trs2))

Output:

Equal: false

func (TargetRules) Contains 

func (r TargetRules) Contains(x any) bool

Contains returns a Boolean value indicative of whether value x, if a string or TargetKeyword instance, already resides within the receiver instance.

Case is not significant in the matching process.

Example

This example demonstrates the assembly and interrogation of a TargetRules instance using the TRs function's variadic expression to submit two (2) components for storage within the receiver. The `target` context value as well as the `targetscope` context value are pushed successfully, at which point we conduct a check to determine whether a `targetscope` rule was in fact written to the underlying stack. 

tdns := TRs(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	Subordinate.Eq(),
)
fmt.Printf("Contains: %t", tdns.Contains(TargetScope))

Output:

Contains: true

func (TargetRules) Index 

func (r TargetRules) Index(idx int) TargetRule

Index wraps go-stackage's Stack.Index method.

Example 
trs := TRs(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	TFDN(`ou=People,dc=example,dc=com`).Eq(),
	Filter(`(objectClass=*`).Ne(),
	SingleLevel.Eq(),
)

fmt.Printf("%s", trs.Index(2).Operator())

Output:

!=

func (TargetRules) IsZero 

func (r TargetRules) IsZero() bool

IsZero wraps go-stackage's Stack.IsZero method.

Example 
var trs TargetRules
fmt.Printf("Zero: %t", trs.IsZero())

Output:

Zero: true

func (TargetRules) Kind 

func (r TargetRules) Kind() string

Kind returns the string literal `stack` to identify the receiver as a stackage.Stack type alias.

Example 
var trs TargetRules
fmt.Printf("%s", trs.Kind())

Output:

stack

func (TargetRules) Len 

func (r TargetRules) Len() int

Len wraps go-stackage's Stack.Len method.

Example 
var trs TargetRules = TRs()

trs.Push(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	TFDN(`ou=People,dc=example,dc=com`).Eq(),
	Filter(`(objectClass=*`).Ne(),
	TAs(`cn`, `sn`, `givenName`, `objectClass`, `uid`, `uidNumber`, `homeDirectory`, `gecos`).Eq(),
	SingleLevel.Eq(),
)

fmt.Printf("%d %T stack members", trs.Len(), trs)

Output:

5 aci.TargetRules stack members

func (TargetRules) NoPadding 

func (r TargetRules) NoPadding(state ...bool) TargetRules

NoPadding sets the delimiter to a SPACE (ASCII #32 ) or to a zero-string depending on the state input.

Example 
trs := TRs(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	TFDN(`ou=People,dc=example,dc=com`).Eq(),
	Filter(`(&(objectClass=restricted)(roleSuffix=executive))`).Ne(),
	SingleLevel.Eq(),
)

fmt.Printf("%s", trs.NoPadding(false))

Output:

( target = "ldap:///uid=jesse,ou=People,dc=example,dc=com" ) ( target_from = "ldap:///ou=People,dc=example,dc=com" ) ( targetfilter != "(&(objectClass=restricted)(roleSuffix=executive))" ) ( targetscope = "onelevel" )

func (*TargetRules) Parse 

func (r *TargetRules) Parse(raw string) error

Parse returns an error based upon an attempt to parse the raw input value into the receiver instance. If successful, any contents within the receiver instance would be obliterated, replaced irrevocably by the freshly parsed values.

Both this method, and the package-level ParseTargetRules function, call antlraci's ParseTargetRules function in similar fashion. The only real difference here is the process of writing to a receiver, versus writing to an uninitialized variable declaration.

Example

This example demonstrates the parsing of a TargetRules expressive statement containing multiple TargetRule conditions. 

raw := `( targetscope="base" )(targetfilter="(&(objectClass=employee)(status=terminated))")(targetattr != "aci")"`
var trs TargetRules
if err := trs.Parse(raw); err != nil {
	fmt.Println(err) // always check your parser errors
	return
}

fmt.Printf("%s", trs.Index(1))

Output:

( targetfilter = "(&(objectClass=employee)(status=terminated))" )

func (TargetRules) Pop 

func (r TargetRules) Pop() TargetRule

Pop wraps go-stackage's Stack.Pop method. An instance of TargetRule is returned following a call of this method.

Within the context of the receiver type, a RuleContext, if non-nil, can only represent a TargetRule instance.

Example 
trs := TRs(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	TFDN(`ou=People,dc=example,dc=com`).Eq(),
	Filter(`(objectClass=*`).Ne(),
	SingleLevel.Eq(), // this will be removed
)

was := trs.Len()
popped := trs.Pop()
cur := trs.Len()

fmt.Printf("Stack length was %d, is now %d: popped element: %s", was, cur, popped)

Output:

Stack length was 4, is now 3: popped element: ( targetscope = "onelevel" )

func (TargetRules) Push 

func (r TargetRules) Push(x ...any) TargetRules

Push wraps go-stackage's Stack.Push method.

Example 
var trs TargetRules = TRs()

trs.Push(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	TFDN(`ou=People,dc=example,dc=com`).Eq(),
	Filter(`(objectClass=*`).Ne(),
	SingleLevel.Eq(),
)

fmt.Printf("%s", trs.Index(3).Keyword())

Output:

targetscope

func (TargetRules) ReadOnly 

func (r TargetRules) ReadOnly(state ...bool) TargetRules

ReadOnly wraps go-stackage's Stack.ReadOnly method.

Example 
var trs TargetRules = TRs(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	TFDN(`ou=People,dc=example,dc=com`).Eq(),
	Filter(`(objectClass=*`).Ne(),
)

trs.ReadOnly()

trs.Push(
	TAs(`cn`, `sn`, `givenName`, `objectClass`, `uid`, `uidNumber`, `homeDirectory`, `gecos`).Eq(),
	SingleLevel.Eq(),
)

fmt.Printf("%d %T stack members", trs.Len(), trs)

Output:

3 aci.TargetRules stack members

func (TargetRules) String 

func (r TargetRules) String() string

String is a stringer method that returns the string representation of the receiver instance.

This method wraps go-stackage's Stack.String method.

Example 
trs := TRs(
	TDN(`uid=jesse,ou=People,dc=example,dc=com`).Eq(),
	TFDN(`ou=People,dc=example,dc=com`).Eq(),
	Filter(`(&(objectClass=restricted)(roleSuffix=executive))`).Ne(),
	SingleLevel.Eq(),
)

fmt.Printf("%s", trs)

Output:

( target = "ldap:///uid=jesse,ou=People,dc=example,dc=com" )( target_from = "ldap:///ou=People,dc=example,dc=com" )( targetfilter != "(&(objectClass=restricted)(roleSuffix=executive))" )( targetscope = "onelevel" )

func (TargetRules) Valid 

func (r TargetRules) Valid() (err error)

Valid wraps go-stackage's Stack.Valid method.

Example 
var trs TargetRules
fmt.Printf("Valid: %t", trs.Valid() == nil)

Output:

Valid: false

type TimeOfDay 

type TimeOfDay struct {
	// contains filtered or unexported fields
}

TimeOfDay is a [2]byte type used to represent a specific point in 24-hour time using hours and minutes (such as 1215 for 12:15 PM, or 1945 for 7:45 PM). Instances of this type contain a big endian unsigned 16-bit integer value, one that utilizes the first (1st) and second (2nd) slices. The value is used within "timeofday" Bind Rule statements.

Example (SetLater) 
var t TimeOfDay
t.Set(`2301`)
fmt.Printf("%s", t)

Output:

2301

func ToD 

func ToD(x ...any) TimeOfDay

ToD initializes, sets and returns a new instance of TimeOfDay in one shot. This function is an alternative to separate assignment and set procedures.

Example 
fmt.Printf("%s", ToD(`2301`))

Output:

2301

func (TimeOfDay) BRM 

func (r TimeOfDay) BRM() BindRuleMethods

BRM returns an instance of BindRuleMethods.

Each of the return instance's key values represent a single instance of the ComparisonOperator type that is allowed for use in the creation of BindRule instances which bear the receiver instance as an expression value. The value for each key is the actual BindRuleMethod instance for OPTIONAL use in the creation of a BindRule instance.

This is merely a convenient alternative to maintaining knowledge of which ComparisonOperator instances apply to which types. Instances of this type are also used to streamline package unit tests.

Please note that if the receiver is in an aberrant state, or if it has not yet been initialized, the execution of ANY of the return instance's value methods will return bogus BindRule instances. While this is useful in unit testing, the end user must only execute this method IF and WHEN the receiver has been properly populated and prepared for such activity.

Example 
var tod TimeOfDay
fmt.Printf("%d available comparison operator methods", tod.BRM().Len())
// 6 available comparison operator methods

func (TimeOfDay) Compare 

func (r TimeOfDay) Compare(x any) bool

Compare returns a Boolean value indicative of a SHA-1 comparison between the receiver (r) and input value x.

Example

This example demonstrates the SHA-1 hash comparison between two (2) TimeOfDay instances using the Compare method. 

d1 := ToD(`1134`)
d2 := ToD(`1136`)

fmt.Printf("Hashes are equal: %t", d1.Compare(d2))

Output:

Hashes are equal: false

func (TimeOfDay) Eq 

func (r TimeOfDay) Eq() BindRule

Eq initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Equal-To the `timeofday` Bind keyword context.

Example 
var thyme TimeOfDay = ToD(`2106`)
fmt.Printf("%s", thyme.Eq())

Output:

timeofday = "2106"

func (TimeOfDay) Ge 

func (r TimeOfDay) Ge() BindRule

Ge initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Greater-Than-Or-Equal to the `timeofday` Bind keyword context.

Example 
var thyme TimeOfDay = ToD(`1003`)
fmt.Printf("%s", thyme.Ge())

Output:

timeofday >= "1003"

func (TimeOfDay) Gt 

func (r TimeOfDay) Gt() BindRule

Gt initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Greater-Than the `timeofday` Bind keyword context.

Example 
var thyme TimeOfDay = ToD(`0901`)
fmt.Printf("%s", thyme.Gt())

Output:

timeofday > "0901"

func (TimeOfDay) IsZero 

func (r TimeOfDay) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

Example 
var thyme TimeOfDay
fmt.Printf("%t", thyme.IsZero())

Output:

true

func (TimeOfDay) Keyword 

func (r TimeOfDay) Keyword() Keyword
Example 
var thyme TimeOfDay
fmt.Printf("%s", thyme.Keyword())

Output:

timeofday

func (TimeOfDay) Le 

func (r TimeOfDay) Le() BindRule

Le initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Less-Than-Or-Equal to the `timeofday` Bind keyword context.

Example 
var thyme TimeOfDay = ToD(`0001`)
fmt.Printf("%s", thyme.Le())

Output:

timeofday <= "0001"

func (TimeOfDay) Lt 

func (r TimeOfDay) Lt() BindRule

Lt initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Less-Than the `timeofday` Bind keyword context.

Example 
var thyme TimeOfDay = ToD(`0100`)
fmt.Printf("%s", thyme.Lt())

Output:

timeofday < "0100"

func (TimeOfDay) Ne 

func (r TimeOfDay) Ne() BindRule

Ne initializes and returns a new BindRule instance configured to express the evaluation of the receiver value as Not-Equal-To the `timeofday` Bind keyword context.

Negated equality BindRule instances should be used with caution.

Example 
var thyme TimeOfDay = ToD(`1543`)
fmt.Printf("%s", thyme.Ne())

Output:

timeofday != "1543"

func (*TimeOfDay) Set 

func (r *TimeOfDay) Set(t any) TimeOfDay

Set encodes the specified 24-hour (a.k.a.: military) time value into the receiver instance.

Valid input types are string and time.Time. The effective hour and minute values, when combined, should ALWAYS fall within the valid clock range of 0000 up to and including 2400. Bogus values within said range, such as 0477, will return an error.

Example 
var tod TimeOfDay
tod.Set(`1401`)
fmt.Printf("Time: %s", tod)

Output:

Time: 1401

func (TimeOfDay) String 

func (r TimeOfDay) String() string

String is a stringer method that returns the string representation of the receiver instance.

Example 
var thyme TimeOfDay = ToD(`2359`)
fmt.Printf("%s", thyme)

Output:

2359

func (TimeOfDay) Valid 

func (r TimeOfDay) Valid() (err error)

Valid returns a Boolean value indicative of whether the receiver is believed to be in a valid state.

Example 
var thyme TimeOfDay
fmt.Printf("Valid: %t", thyme.Valid() == nil)

Output:

Valid: false

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.