schemax

package module
v1.5.7 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2024 License: MIT Imports: 27 Imported by: 0

README

go-schemax

Package schemax incorporates a powerful RFC 4512 parser, wrapped with convenient, reflective features for creating and interrogating directory schemas.

Forked from JesseCoretta's go-schemax.

Requires Go version 1.22 or higher.

Go Report Card CodeQL Reference License Help Animals

License

The schemax package is available under the terms of the MIT license. For further details, see the LICENSE file within the root of the repository.

Releases

Two (2) releases are available for end-users:

Version Notes
1.1.6 Legacy, custom parser
>= 1.5.0 Current, ANTLR parser

History of schemax

The goal of schemax has always been to provide a reliable parsing subsystem for directory schema definitions that allows transformation into usable Go objects.

The original design of schemax (version < 1.5.0) involved a custom-made parser. While this design performed remarkably well for years, it was not without its shortcomings.

The newly released build of schemax involves the import of an ANTLR4-based RFC 4512 lexer/parser solution. This is made possible using a newly released "sister" package -- go-antlr4512 -- which handles all of the low-level ANTLR actions such as tokenization.

Therefore, the new build of schemax is of a simpler fundamental design thanks to offloading the bulk of the parser to another package. This also keeps all code-grading penalties (due to ANTLR's characteristically high cyclomatic factors) confined elsewhere, and allows schemax to focus on extending the slick features users have come to expect.

Users who are only interested in tokenization and do not require the advanced features of this package should consider use of go-antlr4512 exclusively.

The Parser

The (ANTLR) parsing subsystem imported by the aforementioned sister package is flexible in terms of the following:

  • Presence of header, footer and line-terminating Bash comments surrounding a given definition is acceptable
    • Note that comments are entirely discarded by ANTLR
  • Support for (escaped!) ' and \ characters within quoted strings ('this isn\'t a bad example')
  • Support for linebreaks within definitions
  • Definition prefixing allows variations of the standard RFC 4512 "labels" during file and directory parsing
    • "attributeTypes", "attributeType" and other variations are permitted for AttributeType definitions
  • Definition delimitation -- using colon (:), equals (=) or whitespace ( , \t) of any sensible combination -- are permitted for the purpose of separating a definition prefix (label) from its definition statement
    • "attributeTypes: ...", "attributeType=...", "attributeType ..." are valid expressions
  • Multiple files are joined using an ASCII #10 during directory parsing
    • Users need not worry about adding a trailing newline to each file to be read; schemax will do this for you if needed

File and Directory Readers

The legacy release branches of schemax did not offer a robust file and directory parsing solution, rather it focused on the byte representations of a given definition and the tokens derived therein, leaving it to the end-user to devise a delivery method.

The new (>=1.5.0) release branches introduce proper ParseRaw, ParseFile and ParseDirectory methods that greatly simplify use of this package in the midst of an established schema "library". For example:

func main() {
	r := NewSchema()

	// Let's parse a directory into our
	// receiver instance of Schema (r).
	schemaDir := "/home/you/ds/schema"
	if err := r.ParseDirectory(schemaDir); err != nil {
		fmt.Println(err)
		return
	}

	// Check our definition counters
	fmt.Printf("%s", r.Counters())
	// Output:
	// LS: 67
	// MR: 44
	// AT: 131
	// MU: 29
	// OC: 39
	// DC: 1
	// NF: 1
	// DS: 1
}

Though the ParseFile function operates identically to the above-demonstrated ParseDirectory function, it is important to order the respective files and directories according to any applicable dependencies. In other words, if "fileB.schema" requires definitions from "fileA.schema", "fileA.schema" must be parsed first.

Sub-directories encountered shall be traversed indefinitely. The effective name of a given directory is not significant.

Files encountered through directory traversal shall only be read and parsed IF the extension is ".schema". This prevents other files -- such as text or README.md files -- from interfering with the parsing process needlessly.

An eligible schema file may contain one definition, or many. The effective name of an eligible schema file is significant, unlike directories. Each schema file must be named in a manner that fosters the correct ordering of dependent definitions -- whether or not subdirectories are involved. To offer a real-world example, the 389DS/Netscape schema directory deployed during a typical installation is defined and governed in a similar manner.

The general rule-of-thumb is suggests that if the ls -l Bash command consistently lists the indicated schema files in correct order, and assuming those files contain properly ordered and well-formed definitions, the parsing process should work nicely.

Alternatively, the ParseRaw method is ideal for parsing []byte instances that have already been read from the filesystem in some manner, or written "in-line" such as for unit testing.

The Schema Itself

The Schema type defined within this package is a stackage.Stack derivative type. An instance of a Schema can manifest in any of the following manners:

  • As an empty (unpopulated) Schema, initialized by way of the NewEmptySchema function
  • As a basic (minimally populated) Schema, initialized by way of the NewBasicSchema function
  • As a complete (fully populated) Schema, initialized by way of the NewSchema function

There are certain scenarios which call for one of the above initialization procedures:

  • An empty Schema is ideal for LDAP professionals, and allows for the creation of a Schema of particularly narrow focus for R&D, testing or product development
  • A basic Schema resembles the foundational (starting) Schema context observed in most directory server products, in that it comes "pre-loaded" with official LDAPSyntax and MatchingRule definitions -- but few to no AttributeTypes -- making it a most suitable empty canvas upon which a new Schema may be devised from scratch
  • A full Schema is the most obvious choice for "Quick Start" scenarios, in that a Schema is produced containing a very large portion of the standard AttributeType and ObjectClass definitions used in the wild by most (if not all) directory products

Regardless of the content present, a given Schema is capable of storing definitions from all eight (8) RFC 4512 "categories". These are known as "collections", and are stored in nested stackage.Stack derivative types, accessed using any of the following methods:

  • Schema.LDAPSyntaxes
  • Schema.MatchingRules
  • Schema.AttributeTypes
  • Schema.MatchingRuleUses
  • Schema.ObjectClasses
  • Schema.DITContentRules
  • Schema.NameForms
  • Schema.DITStructureRules

Definition instances produced by way of parsing -- namely using one of the Schema.Parse<Type> methods-- will automatically gain internal access to the Schema instance in which it is stored.

However, definitions produced manually by way of the various Set<Item> methods or by way of localized Parse method extended through types defined within this package will require manual execution of the SetSchema method, using the intended Schema instance as the input argument. Ideally this should occur early in the definition composition.

In either case, this internal reference is used for seamless verification of any reference, such as an LDAPSyntax, when introduced to a given type instance. This ensures definition pointer references remain valid.

Closure Methods

This package is closure-friendly with regards to user-authored closure functions or methods meant to perform specific tasks:

  • Assertion matching, by way of an instance of MatchingRule applicable to two assertion values within a AssertionMatcher closure (i.e.: is "value1" equal to "value2"?)
  • Syntax qualification, by way of an instance of LDAPSyntax to be honored by a value within a SyntaxQualifier closure (i.e.: does value qualify for specified syntax?)
  • General-use value qualification, by way of an instance of AttributeType to be analyzed in specialized scenarios within a ValueQualifier closure (i.e: company/user-specific value processing)
  • Definition string representation, through assignment of a custom Stringer closure to eligible definition instances

Understand that assertion, syntax and general-use qualifying closures are entirely user-defined; this package does not provide such predefined instances itself, leaving that to the user or another package which may be imported and used in a "pluggable" manner in this context.

See RFC 4517, et al, for some practical guidelines relating to certain syntax and assertion matching procedures that may guide users in creating such closures.

This package does, however, include a default Stringer, which can be invoked for an instance simply by running the instance's SetStringer method in niladic form.

Fluent Methods

This package extends fluent methods that are write-based in nature. Typically these methods are prefaced with Set or Push. This means such methods may be "chained" together using the standard Go command "." delimiter.

Fluency does not extend to methods that are interrogative in nature, in that they return bool, string or error values. Fluency also precludes use of the Registration interface due to unique return signatures.

Built-In Definitions

The following table describes the contents and coverage of the so-called "built-in" schema definitions, all of which are sourced from recognized RFCs only. These can be imported en masse by users, or in piece-meal fashion.

DOCUMENT LS MR AT OC DC NF DS
RFC 2307 ✅ ✅ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 2589 ⁿ/ₐ ⁿ/ₐ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 2798 ⁿ/ₐ ⁿ/ₐ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 3045 ⁿ/ₐ ⁿ/ₐ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 3671 ⁿ/ₐ ⁿ/ₐ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 3672 ⁿ/ₐ ⁿ/ₐ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 4512 ⁿ/ₐ ⁿ/ₐ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 4517 ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 4519 ⁿ/ₐ ⁿ/ₐ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 4523 ✅ ✅ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 4524 ⁿ/ₐ ⁿ/ₐ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 4530 ✅ ✅ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ
RFC 5020 ⁿ/ₐ ⁿ/ₐ ✅ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ ⁿ/ₐ

Documentation

Index

Examples

Constants

View Source 
const (
	UserApplicationsUsage     uint = iota // RFC 4512 § 4.1.2
	DirectoryOperationUsage               // RFC 4512 § 4.1.2
	DistributedOperationUsage             // RFC 4512 § 4.1.2
	DSAOperationUsage                     // RFC 4512 § 4.1.2
)
View Source 
const (
	StructuralKind uint = iota // RFC 4512 § 2.4.2, 4.1.1
	AbstractKind               // RFC 4512 § 2.4.1, 4.1.1
	AuxiliaryKind              // RFC 4512 § 2.4.3, 4.1.1
)

Variables

View Source 
var (
	ErrNilSyntaxQualifier  error = errors.New("No SyntaxQualifier instance assigned to LDAPSyntax")
	ErrNilValueQualifier   error = errors.New("No ValueQualifier instance assigned to AttributeType")
	ErrNilAssertionMatcher error = errors.New("No AssertionMatcher instance assigned to MatchingRule")
	ErrNilReceiver         error = errors.New("Receiver instance is nil")
	ErrNilInput            error = errors.New("Input instance is nil")
	ErrNilDef              error = errors.New("Referenced definition is nil or not specified")
	ErrNilSchemaRef        error = errors.New("Receiver instance lacks a Schema reference")
	ErrDefNonCompliant     error = errors.New("Definition failed compliancy checks")
	ErrInvalidInput        error = errors.New("Input instance not compatible")
	ErrInvalidSyntax       error = errors.New("Value does not meet the prescribed syntax qualifications")
	ErrInvalidValue        error = errors.New("Value does not meet the prescribed value qualifications")
	ErrNoMatch             error = errors.New("Values do not match according to prescribed assertion match")
	ErrInvalidType         error = errors.New("Incompatible type for operation")
	ErrTypeAssert          error = errors.New("Type assertion failed")
	ErrNotUnique           error = errors.New("Definition is already defined")
	ErrNotEqual            error = errors.New("Values are not equal")
	ErrMissingNumericOID   error = errors.New("Missing or invalid numeric OID for definition")

	ErrOrderingRuleNotFound  error = errors.New("ORDERING MatchingRule not found")
	ErrSubstringRuleNotFound error = errors.New("SUBSTR MatchingRule not found")
	ErrEqualityRuleNotFound  error = errors.New("EQUALITY MatchingRule not found")

	ErrAttributeTypeNotFound    error = errors.New("AttributeType not found")
	ErrObjectClassNotFound      error = errors.New("ObjectClass not found")
	ErrNameFormNotFound         error = errors.New("NameForm not found")
	ErrMatchingRuleNotFound     error = errors.New("MatchingRule not found")
	ErrMatchingRuleUseNotFound  error = errors.New("MatchingRuleUse not found")
	ErrLDAPSyntaxNotFound       error = errors.New("LDAPSyntax not found")
	ErrDITContentRuleNotFound   error = errors.New("DITContentRule not found")
	ErrDITStructureRuleNotFound error = errors.New("DITStructureRule not found")
)

Functions

func IsDescriptor 

func IsDescriptor(val string) bool

IsDescriptor scans the input string val and judges whether it qualifies as an RFC 4512 "descr", in that all of the following evaluate as true:

  • Non-zero in length
  • Begins with an alphabetical character
  • Ends in an alphanumeric character
  • Contains only alphanumeric characters or hyphens
  • No contiguous hyphens

This function is an alternative to engaging the antlr4512 parsing subsystem.

Example 
fmt.Printf("%t", IsDescriptor(`telephoneNumber`))

Output:

true

func IsNumericOID 

func IsNumericOID(id string) bool

IsNumericOID wraps objectid.NewDotNotation to parse input value id in order to assess its validity as an ASN.1 OBJECT IDENTIFIER in dot form, e.g.: 

1.3.6.1.4.1.56521.999

The qualifications are as follows:

  • Must only consist of digits (arcs) and dot (ASCII FULL STOP) delimiters
  • Must begin with a root arc: 0, 1 or 2
  • Second-level arcs below root arcs 0 and 1 cannot be greater than 39
  • Cannot end with a dot
  • Dots cannot be contiguous
  • Though arcs are unbounded, no arc may ever be negative
  • OID must consist of at least two (2) arcs
Example 
fmt.Printf("%t", IsNumericOID(`1.3.6.1.4.1`))

Output:

true

Types

type AssertionMatcher 

type AssertionMatcher func(any, any) error

AssertionMatcher is an optional closure function or method signature which may be honored by the end user for assertion match controls with respect to a MatchingRule instance. This signature is used in up to three (3) distinct scenarios:

  • Equality matching (e.g.: jesse=Jesse / caseIgnoreMatch)
  • Substring matching (e.g.: jess*=Jesse / caseIgnoreSubstringMatch)
  • Ordering matching (e.g.: 20210814135117Z>=20210428081809Z / generalizedTimeOrderingMatch)

The main use case for instances of this type is to define the basis of comparing or evaluating two (2) values with respect to the MatchingRule indicated.

type AttributeType 

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

AttributeType implements § 4.1.2 of RFC 4512. 

AttributeTypeDescription = LPAREN WSP
    numericoid                    ; object identifier
    [ SP "NAME" SP qdescrs ]      ; short names (descriptors)
    [ SP "DESC" SP qdstring ]     ; description
    [ SP "OBSOLETE" ]             ; not active
    [ SP "SUP" SP oid ]           ; supertype
    [ SP "EQUALITY" SP oid ]      ; equality matching rule
    [ SP "ORDERING" SP oid ]      ; ordering matching rule
    [ SP "SUBSTR" SP oid ]        ; substrings matching rule
    [ SP "SYNTAX" SP noidlen ]    ; value syntax
    [ SP "SINGLE-VALUE" ]         ; single-value
    [ SP "COLLECTIVE" ]           ; collective
    [ SP "NO-USER-MODIFICATION" ] ; not user modifiable
    [ SP "USAGE" SP usage ]       ; usage
    extensions WSP RPAREN         ; extensions

usage = "userApplications"     /  ; user
        "directoryOperation"   /  ; directory operational
        "distributedOperation" /  ; DSA-shared operational
        "dSAOperation"            ; DSA-specific operational

From clause 13.4.8 of ITU-T Rec. X.501: 

ATTRIBUTE ::= CLASS {
	&derivation ATTRIBUTE OPTIONAL,
	&Type OPTIONAL, -- either &Type or &derivation required
	&equality-match MATCHING-RULE OPTIONAL,
	&ordering-match MATCHING-RULE OPTIONAL,
	&substrings-match MATCHING-RULE OPTIONAL,
	&single-valued BOOLEAN DEFAULT FALSE,
	&collective BOOLEAN DEFAULT FALSE,
	&dummy BOOLEAN DEFAULT FALSE,
	-- operational extensions
	&no-user-modification BOOLEAN DEFAULT FALSE,
	&usage AttributeUsage DEFAULT userApplications,
	&ldapSyntax SYNTAX-NAME.&id OPTIONAL,
	&ldapName SEQUENCE SIZE(1..MAX) OF UTF8String OPTIONAL,
	&ldapDesc UTF8String OPTIONAL,
	&obsolete BOOLEAN DEFAULT FALSE,
	&id OBJECT IDENTIFIER UNIQUE }

WITH SYNTAX {
	[SUBTYPE OF &derivation]
	[WITH SYNTAX &Type]
	[EQUALITY MATCHING RULE &equality-match]
	[ORDERING MATCHING RULE &ordering-match]
	[SUBSTRINGS MATCHING RULE &substrings-match]
	[SINGLE VALUE &single-valued]
	[COLLECTIVE &collective]
	[DUMMY &dummy]
	[NO USER MODIFICATION &no-user-modification]
	[USAGE &usage]
	[LDAP-SYNTAX &ldapSyntax]
	[LDAP-NAME &ldapName]
	[LDAP-DESC &ldapDesc]
	[OBSOLETE &obsolete]
	ID &id }

	AttributeUsage ::= ENUMERATED {
		userApplications (0),
		directoryOperation (1),
		distributedOperation (2),
		dSAOperation (3),
		... }

func NewAttributeType 

func NewAttributeType() AttributeType

NewAttributeType initializes and returns a new instance of AttributeType, ready for manual assembly. This method need not be used when creating new AttributeType instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the AttributeType.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewAttributeType method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of AttributeType instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an AttributeType instance.

Example

This example demonstrates an alternative to Schema.NewAttributeType. The return value must be manually configured and must also be manually associated with the relevant Schema instance. Use of this function is only meaningful when dealing with multiple Schema instances.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// lookup and get the Directory String syntax
dStr := mySchema.LDAPSyntaxes().Get(`1.3.6.1.4.1.1466.115.121.1.15`)
if dStr.IsZero() {
	return
}

// lookup and get the caseIgnoreMatch equality matching rule
cIM := mySchema.MatchingRules().Get(`caseIgnoreMatch`)
if cIM.IsZero() {
	return
}

// prepare new var instance
var def AttributeType = NewAttributeType()

// set values in fluent form
def.SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetName(`cb`).
	SetDescription(`Celestial Body`).
	SetMinimumUpperBounds(64).
	SetSyntax(dStr).
	SetEquality(cIM).
	SetSingleValue(true).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer() // use default stringer

fmt.Printf("%s", def)

Output:

( 1.3.6.1.4.1.56521.999.5
    NAME 'cb'
    DESC 'Celestial Body'
    EQUALITY caseIgnoreMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{64}
    SINGLE-VALUE
    X-ORIGIN 'NOWHERE' )

func (AttributeType) Collective 

func (r AttributeType) Collective() (o bool)

Collective returns a Boolean value indicative of whether the receiver is COLLECTIVE. A value of true is mutually exclusive of SINGLE-VALUE'd AttributeType instances.

func (AttributeType) Compliant 

func (r AttributeType) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.2 of RFC 4512:

  • Numeric OID must be present and valid
  • Specified EQUALITY, SUBSTR and ORDERING MatchingRule instances must be COMPLIANT
  • Specified LDAPSyntax MUST be COMPLIANT

Additional consideration is given to RFC 3671 in that an AttributeType shall not be both COLLECTIVE and SINGLE-VALUE'd.

Example

This example demonstrates a compliancy check of the "name" AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

name := mySchema.AttributeTypes().Get(`name`)
fmt.Println(name.Compliant())

Output:

true

func (AttributeType) Data 

func (r AttributeType) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the AttributeType.SetData method.

func (AttributeType) Description 

func (r AttributeType) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

Example 
cn := mySchema.AttributeTypes().Get(`cn`)
fmt.Println(cn.Description())

Output:

RFC4519: common name(s) for which the entity is known by

func (AttributeType) EffectiveEquality 

func (r AttributeType) EffectiveEquality() MatchingRule

EffectiveEquality returns the EQUALITY MatchingRule instance held (directly or indirectly) by the receiver.

If the receiver does not directly reference an MatchingRule instance, this method walks the super type chain until it encounters a superior AttributeType which directly references an EQUALITY MatchingRule.

If the return instance returns a Boolean value of true following an execution of MatchingRule.IsZero, this means there is NO effective EQUALITY MatchingRule specified anywhere in the receiver's super type chain.

Example

This example demonstrates the means of walking the super type chain to determine the effective EQUALITY MatchingRule instance held by an AttributeType instance, whether direct or indirect. 

at := mySchema.AttributeTypes().Get(`registeredAddress`)
fmt.Println(at.EffectiveEquality().OID())

Output:

caseIgnoreListMatch

func (AttributeType) EffectiveOrdering 

func (r AttributeType) EffectiveOrdering() MatchingRule

EffectiveOrdering returns the ORDERING MatchingRule instance held (directly or indirectly) by the receiver.

If the receiver does not directly reference an MatchingRule instance, this method walks the super type chain until it encounters a superior AttributeType which directly references an ORDERING MatchingRule.

If the return instance returns a Boolean value of true following an execution of MatchingRule.IsZero, this means there is NO effective ORDERING MatchingRule specified anywhere in the receiver's super type chain.

Example

This example demonstrates the means of walking the super type chain to determine the effective ORDERING MatchingRule instance held by an AttributeType instance, whether direct or indirect. 

at := mySchema.AttributeTypes().Get(`createTimestamp`)
fmt.Println(at.EffectiveOrdering().OID())

Output:

generalizedTimeOrderingMatch

func (AttributeType) EffectiveSubstring 

func (r AttributeType) EffectiveSubstring() MatchingRule

EffectiveSubstring returns the SUBSTR MatchingRule instance held (directly or indirectly) by the receiver.

If the receiver does not directly reference an MatchingRule instance, this method walks the super type chain until it encounters a superior AttributeType which directly references a SUBSTR MatchingRule.

If the return instance returns a Boolean value of true following an execution of MatchingRule.IsZero, this means there is NO effective SUBSTR MatchingRule specified anywhere in the receiver's super type chain.

Example

This example demonstrates the means of walking the super type chain to determine the effective SUBSTR MatchingRule instance held by an AttributeType instance, whether direct or indirect. 

at := mySchema.AttributeTypes().Get(`registeredAddress`)
fmt.Println(at.EffectiveSubstring().OID())

Output:

caseIgnoreListSubstringsMatch

func (AttributeType) EffectiveSyntax 

func (r AttributeType) EffectiveSyntax() LDAPSyntax

EffectiveSyntax returns the LDAPSyntax instance held (directly or indirectly) by the receiver.

If the receiver does not directly reference an LDAPSyntax instance, this method walks the super type chain until it encounters a superior AttributeType which directly references an LDAPSyntax.

If the return instance returns a Boolean value of true following an execution of LDAPSyntax.IsZero, this means there is NO effective LDAPSyntax specified anywhere in the receiver's super type chain.

Example

This example demonstrates the means of walking the super type chain to determine the effective LDAPSyntax instance held by an AttributeType instance, whether direct or indirect.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

at := mySchema.AttributeTypes().Get(`roleOccupant`)
fmt.Println(at.EffectiveSyntax().Description())

Output:

DN

func (AttributeType) Equality 

func (r AttributeType) Equality() (eql MatchingRule)

Equality returns the underlying instance of MatchingRule if set within the receiver instance. If unset, a zero instance is returned.

func (AttributeType) EqualityAssertion 

func (r AttributeType) EqualityAssertion(value1, value2 any) (err error)

EqualityAssertion returns an error following an attempt to perform an EQUALITY assertion match upon value1 and value2 using the effective MatchingRule honored by the receiver instance.

Example

This example demonstrates the means of performing an equality match assertion between two values by way of an AssertionMatcher closure assigned to the relevant MatchingRule instance in use by one or more AttributeType instances.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Obtain the syntax of interest
cim := mySchema.MatchingRules().Get(`caseIgnoreMatch`)

// Assign a new assertion matcher to our matching rule to
// allow caseless equality matching between two values.
cim.SetAssertionMatcher(func(x, y any) (err error) {

	// Type assert x, allowing string or
	// byte values to be processed.
	var X, Y string
	switch tv := x.(type) {
	case string:
		X = tv
	case []byte:
		X = string(tv)
	default:
		err = ErrInvalidType
		return
	}

	// Now type assert y similarly.
	switch tv := y.(type) {
	case string:
		Y = tv
	case []byte:
		Y = string(tv)
	default:
		err = ErrInvalidType
		return
	}

	if !strings.EqualFold(X, Y) {
		err = ErrNoMatch
	}

	return
})

// Check an attribute that is known to use the above
// matching rule.
cn := mySchema.AttributeTypes().Get(`2.5.4.3`) // or "cn"

// Compare two values via the EqualityAssertion method.
ok := cn.EqualityAssertion(`kenny`, `Kenny`) == nil

fmt.Printf("Values match: %t", ok)

Output:

Values match: true

func (AttributeType) Extensions 

func (r AttributeType) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver.

Example

This example demonstrates a means of accessing the underlying Extensions stack instance within the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

cn := mySchema.AttributeTypes().Get(`cn`)
fmt.Println(cn.Extensions())

Output:

X-ORIGIN 'RFC4519'

func (AttributeType) IsIdentifiedAs 

func (r AttributeType) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or descriptor of the receiver instance. Case is not significant in the matching process.

Example

This example demonstrates a means of determining whether an AttributeType instance is known by the numeric OID or descriptor input.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

surprise := mySchema.AttributeTypes().Get(`0.9.2342.19200300.100.1.5`)
knownBy := surprise.IsIdentifiedAs(`drink`)
fmt.Printf("Definition is known by 'drink': %t", knownBy)

Output:

Definition is known by 'drink': true

func (AttributeType) IsZero 

func (r AttributeType) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (AttributeType) Map 

func (r AttributeType) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example

This example demonstrates the means of transferring an AttributeType into an instance of DefinitionMap.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.AttributeTypes().Get(`cn`)
fmt.Println(def.Map()[`NUMERICOID`][0]) // risky, just for simplicity

Output:

2.5.4.3

func (AttributeType) MinimumUpperBounds 

func (r AttributeType) MinimumUpperBounds() (mub uint)

MinimumUpperBounds returns the unsigned integer form of the receiver's "size limit", if set. A non-zero value indicates a specific maximum has been declared.

Example

This example demonstrates accessing the minimum upper bounds of an instance of AttributeType, if set.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

ip := mySchema.AttributeTypes().Get(`ipHostNumber`)
fmt.Println(ip.MinimumUpperBounds())

Output:

128

func (AttributeType) Name 

func (r AttributeType) Name() (id string)

Name returns the string form of the principal name of the receiver instance, if set.

func (AttributeType) Names 

func (r AttributeType) Names() (names QuotedDescriptorList)

Names returns the underlying instance of QuotedDescriptorList from within the receiver.

Example 
cn := mySchema.AttributeTypes().Get(`2.5.4.3`)
fmt.Println(cn.Names())

Output:

( 'cn' 'commonName' )

func (AttributeType) NoUserModification 

func (r AttributeType) NoUserModification() (o bool)

NoUserModification returns a Boolean value indicative of whether the receiver instance's NO-USER-MODIFICATION clause evaluates as TRUE. In such a scenario, only the DSA may manage such values.

Example 
modTime := mySchema.AttributeTypes().Get(`modifyTimestamp`)
fmt.Printf("Definition is immutable: %t", modTime.NoUserModification())

Output:

Definition is immutable: true

func (AttributeType) NumericOID 

func (r AttributeType) NumericOID() (noid string)

NumericOID returns the string representation of the numeric OID held by the receiver instance.

func (AttributeType) OID 

func (r AttributeType) OID() (oid string)

OID returns the string representation of an OID -- which is either a numeric OID or descriptor -- that is held by the receiver instance.

func (AttributeType) Obsolete 

func (r AttributeType) Obsolete() (o bool)

Obsolete returns a Boolean value indicative of definition obsolescence.

Example 
modTime := mySchema.AttributeTypes().Get(`modifyTimestamp`)
fmt.Printf("Definition is obsolete: %t", modTime.Obsolete())

Output:

Definition is obsolete: false

func (AttributeType) Ordering 

func (r AttributeType) Ordering() (ord MatchingRule)

Ordering returns the underlying instance of MatchingRule if set within the receiver instance. If unset, a zero instance is returned.

func (AttributeType) OrderingAssertion 

func (r AttributeType) OrderingAssertion(value1, value2 any) (err error)

OrderingAssertion returns an error following an attempt to perform an ORDERING assertion match upon value1 and value2 using the effective MatchingRule honored by the receiver instance.

Example

This example demonstrates the means of performing an ordering match assertion between two values by way of an AssertionMatcher closure assigned to the relevant MatchingRule instance in use by one or more AttributeType instances.

For this example, we'll be comparing two string-based timestamps in "YYYYMMDDHHmmss" timestamp format. The values are marshaled into proper time.Time instances and then compared ordering-wise.

The first input value is the higher order value, while the second value is the lower order value. A comparison error returned indicates that the first value is NOT greater or equal to the second.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Obtain the syntax of interest
cism := mySchema.MatchingRules().Get(`generalizedTimeOrderingMatch`)

// Assign a new assertion matcher to our matching rule to allow
// time ordering matching (e.g.: is timeA later than timeB).
cism.SetAssertionMatcher(func(after, before any) (err error) {

	// Type assert x, allowing string or
	// byte values to be processed.
	var A, B string
	switch tv := after.(type) {
	case string:
		A = tv
	case []byte:
		A = string(tv)
	default:
		err = ErrInvalidType
		return
	}

	// Now type assert y similarly.
	switch tv := before.(type) {
	case string:
		B = tv
	case []byte:
		B = string(tv)
	default:
		err = ErrInvalidType
		return
	}

	format := `20060102150405`

	After, _ := time.Parse(format, A)
	Before, _ := time.Parse(format, B)

	if !(After.After(Before) || (After.Equal(Before))) {
		err = ErrNoMatch
	}

	return
})

// Check an attribute that is known to use the above matching rule.
modTime := mySchema.AttributeTypes().Get(`modifyTimestamp`)

// Compare two values via the SubstringAssertion method.
// In the context of an assertion check via LDAP, the
// first value (Kenny) could represent a value within
// the database being compared, while the second value
// (k*NN*) is the substring statement input by the user,
// ostensibly within an LDAP Search Filter.
timeA := `20150107145309`
timeB := `20090417110844`
ok := modTime.OrderingAssertion(timeA, timeB) == nil

fmt.Printf("Values match: %t", ok)

Output:

Values match: true

func (AttributeType) Parse 

func (r AttributeType) Parse(raw string) (err error)

Parse returns an error following an attempt to parse raw into the receiver instance.

Note that the receiver MUST possess a Schema reference prior to the execution of this method.

Also note that successful execution of this method does NOT automatically push the receiver into any AttributeTypes stack, nor does it automatically execute the AttributeType.SetStringer method, leaving these tasks to the user. If the automatic handling of these tasks is desired, see the Schema.ParseAttributeType method as an alternative.

Example

This example demonstrates a means of parsing a raw definition into a new instance of AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

nattr := mySchema.NewAttributeType()

// feed the parser a subtly bogus definition ...
err := nattr.Parse(`( 1.3.6.1.4.1.56521.999.14.56.1
		NAME 'fakeAttribute'
		DESC 'It\'s not real'
		SINGLE-VALUE
		COLLECTIVE
		X-ORIGIN 'YOUR FACE'
	)`)

fmt.Println(err)

Output:

AttributeType is both single-valued and collective; aborting (1.3.6.1.4.1.56521.999.14.56.1)

func (AttributeType) QualifySyntax 

func (r AttributeType) QualifySyntax(value any) (err error)

QualifySyntax wraps LDAPSyntax.QualifySyntax.

Example 
// Obtain the syntax of interest
dstr := mySchema.LDAPSyntaxes().Get(`directoryString`)

// Assign a new syntax qualifier to our syntax
// to perform a naïve assessment of x in order
// to determine whether it is UTF8.
dstr.SetSyntaxQualifier(func(x any) (err error) {

	// Type assert, allowing string or
	// byte values to be processed.
	switch tv := x.(type) {
	case string:
		if !utf8.ValidString(tv) {
			err = ErrInvalidSyntax
		}
	case []byte:
		if !utf8.ValidString(string(tv)) {
			err = ErrInvalidSyntax
		}
	default:
		err = ErrInvalidType
	}

	return
})

// Check an attribute that is known to use the above syntax
cn := mySchema.AttributeTypes().Get(`2.5.4.3`) // or "cn"

// Test a value against the qualifier function
ok := cn.QualifySyntax(`Coolie McLoach`) == nil

fmt.Printf("Syntax ok: %t", ok)

Output:

Syntax ok: true

func (AttributeType) QualifyValue 

func (r AttributeType) QualifyValue(value any) (err error)

QualifyValue returns an error instance following an analysis of the input value using the ValueQualifier instance previously assigned to the receiver instance.

If a ValueQualifier is not assigned to the receiver instance, the ErrNilValueQualifier error is returned if and when this method is executed. Otherwise, an error is returned based on the custom ValueQualifier error handler devised by the author.

A nil error return always indicates valid input value syntax.

See the AttributeType.SetValueQualifier for information regarding the assignment of an instance of ValueQualifier to the receiver.

Example (WithSet)

This example demonstrates a conventional means of checking a given value under the terms of a specific AttributeType's assigned ValueQualifier.

Naturally this example is overly simplified, with support extended for nil value states purely for educational purposes only. A real life implementation would likely be more stringent.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Let's use "hasSubordinates" due to its common
// use within multiple popular directory products.
hS := mySchema.AttributeTypes().Get(`hasSubordinates`)
if hS.IsZero() {
	fmt.Println("hasSubordinates not found!")
	return
}

// hasSubordinates is a BOOLEAN type, so let's make
// a very "forgiving" handler for such values, both
// for string and (Go) bool/*bool values.
hS.SetValueQualifier(func(x any) error {
	var err error

	switch tv := x.(type) {
	case string:
		switch strings.ToLower(tv) {
		case `true`, `false`, `undefined`, ``:
			// OK: Match all valid string values in one shot
			// in a manner compliant with the caseIgnoreMatch
			// equality matching rule.
		default:
			// BAD: No other string value is applicable here.
			err = ErrInvalidSyntax
		}
	case bool, *bool, nil:
		// OK: Guaranteed to be valid, with a nil instance
		// equivalent to the LDAP "Undefined" BOOLEAN state.
	default:
		// BAD: no other type is applicable here.
		err = ErrInvalidType
	}

	return err
})

// Let's subject our newly-assigned SyntaxQualifier to
// a series of valid values of supported types.
for _, possibleValue := range []any{
	`True`,
	false,
	`False`,
	true,
	`FALSE`,
	`fALse`,
	``,
	`undefineD`,
	nil,
} {
	// None of these should return errors.
	if err := hS.QualifyValue(possibleValue); err != nil {
		fmt.Println(err)
		return
	}
}

// Let's pass a known bogus value just to
// make sure this thing is indeed working.
err := hS.QualifyValue(`falsch`) // Entschuldigung, kein deutscher support :(
fmt.Println(err)

Output:

Value does not meet the prescribed syntax qualifications

func (AttributeType) Replace 

func (r AttributeType) Replace(x AttributeType) AttributeType

Replace overrides the receiver with x. Both must bear an identical numeric OID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the AttributeType envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

Example

This example demonstrates the replacement process of an AttributeType instance within an instance of AttributeTypes.

For reasons of oversight, we've added a custom extension X-WARNING to remind users and admin alike of the modification.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Lets create a new attributeType: coolattr
attr := mySchema.NewAttributeType()
goodraw := `( 1.3.6.1.4.1.56521.999.14.56.1 NAME 'coolattr' SUP cn )`
if err := attr.Parse(goodraw); err != nil {
	fmt.Println(err)
	return
}

// Parsing says its valid, so let's push this
// new type into our official type stack.
mySchema.AttributeTypes().Push(attr)

// Oh no! We realized we used the wrong supertype.
// We wanted name, not cn :(

// Retrieve the type
attr = mySchema.AttributeTypes().Get(`coolattr`)

// Craft a near identical type instance, changing
// the supertype to name. Also, for good measure,
// lets make a note of this modification using
// an "X-WARNING" extension...
nattr := mySchema.NewAttributeType().
	SetName(attr.Name()).
	SetNumericOID(attr.NumericOID()).
	SetSuperType(`name`).
	SetExtension(`X-WARNING`, `MODIFIED`). // optional
	SetStringer()

// Replace attr with nattr, while preserving its pointer
// address so that references within stacks do not fail.
attr.Replace(nattr)

// call the new one (just to be sure)
fmt.Println(mySchema.AttributeTypes().Get(`coolattr`))

Output:

( 1.3.6.1.4.1.56521.999.14.56.1
    NAME 'coolattr'
    SUP name
    X-WARNING 'MODIFIED' )

func (AttributeType) Schema 

func (r AttributeType) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (AttributeType) SetCollective 

func (r AttributeType) SetCollective(x any) AttributeType

SetCollective assigns the input value to the underlying COLLECTIVE clause within the receiver.

Input types may be bool, or string representations of bool. When strings are used, case is not significant.

Note that a value of true will be ignored if the receiver is a single-valued AttributeType.

This is a fluent method.

func (AttributeType) SetData 

func (r AttributeType) SetData(x any) AttributeType

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the AttributeType.Data method.

This is a fluent method.

Example

This example demonstrates the assignment of arbitrary data to an instance of AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// The value can be any type, but we'll
// use a string for simplicity.
documentation := `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`

// Obtain the target attribute type to bear
// the assigned value.
drink := mySchema.AttributeTypes().Get(`drink`)

// Set it.
drink.SetData(documentation)

// Get it and compare to the original.
equal := documentation == drink.Data().(string)

fmt.Printf("Values are equal: %t", equal)

Output:

Values are equal: true

func (AttributeType) SetDescription 

func (r AttributeType) SetDescription(desc string) AttributeType

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

This is a fluent method.

func (AttributeType) SetEquality 

func (r AttributeType) SetEquality(x any) AttributeType

SetEquality sets the equality MatchingRule of the receiver instance.

Input x may be the string representation of the desired equality matchingRule, by name or numeric OID. This requires an underlying instance of Schema set within the receiver instance. The Schema instance is expected to possess the referenced MatchingRule, else a zero instance will ultimately be returned and discarded.

Input x may also be a bonafide, non-zero instance of an equality MatchingRule. This requires no underlying Schema instance, but may allow the introduction of bogus MatchingRule instances.

This is a fluent method.

Example

This example demonstrates the assignment of an EQUALITY MatchingRule instance to an AttributeType instance during assembly.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// First we'll craft a fake attribute
raw := `( 1.3.6.1.4.1.56521.999.14.56.1
                NAME 'coolattr'
		SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )`

var attr AttributeType = mySchema.NewAttributeType()
if err := attr.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

// Oh no! We forgot to specify the desired equality matching
// rule! No worries, it can be done after the fact:
attr.SetEquality(`caseIgnoreMatch`)

fmt.Println(attr.Equality().NumericOID())

Output:

2.5.13.2

func (AttributeType) SetExtension 

func (r AttributeType) SetExtension(x string, xstrs ...string) AttributeType

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (AttributeType) SetMinimumUpperBounds 

func (r AttributeType) SetMinimumUpperBounds(mub any) AttributeType

SetMinimumUpperBounds assigns the provided value -- which may be an int or uint -- to the receiver instance.

This is a fluent method.

Example

This example demonstrates the assignment of a minimum upper bounds value, meant to declare the maximum limit for a value of this AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// First we'll craft a fake attribute
raw := `( 1.3.6.1.4.1.56521.999.14.56.1
		NAME 'coolattr'
		SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )`

var attr AttributeType = mySchema.NewAttributeType()
if err := attr.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

// Oh no! We forgot to specify the min. upper bounds!
// No worries, it can be done after the fact:
attr.SetMinimumUpperBounds(128)

fmt.Println(attr.MinimumUpperBounds())

Output:

128

func (AttributeType) SetName 

func (r AttributeType) SetName(x ...string) AttributeType

SetName assigns the provided names to the receiver instance.

Name instances must conform to RFC 4512 descriptor format but need not be quoted.

This is a fluent method.

func (AttributeType) SetNoUserModification 

func (r AttributeType) SetNoUserModification(x any) AttributeType

SetNoUserModification assigns the input value to the underlying NO-USER-MODIFICATION clause within the receiver.

Input types may be bool, or string representations of bool. When strings are used, case is not significant.

This is a fluent method.

func (AttributeType) SetNumericOID 

func (r AttributeType) SetNumericOID(id string) AttributeType

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (AttributeType) SetObsolete 

func (r AttributeType) SetObsolete(x any) AttributeType

SetObsolete assigns the input value to the underlying OBSOLETE clause within the receiver.

Input types may be bool, or string representations of bool. When strings are used, case is not significant.

Obsolescence cannot be unset.

This is a fluent method.

func (AttributeType) SetOrdering 

func (r AttributeType) SetOrdering(x any) AttributeType

SetOrdering sets the ordering MatchingRule of the receiver instance.

Input x may be the string representation of the desired ordering matchingRule, by name or numeric OID. This requires an underlying instance of Schema set within the receiver instance. The Schema instance is expected to possess the referenced MatchingRule, else a zero instance will ultimately be returned and discarded.

Input x may also be a bonafide, non-zero instance of an ordering MatchingRule. This requires no underlying Schema instance, but may allow the introduction of bogus MatchingRule instances.

This is a fluent method.

Example

This example demonstrates the assignment of an ORDERING MatchingRule instance to an AttributeType instance during assembly.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// First we'll craft a fake attribute
raw := `( 1.3.6.1.4.1.56521.999.14.56.1
                NAME 'coolattr'
                SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )`

var attr AttributeType = mySchema.NewAttributeType()
if err := attr.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

// Oh no! We forgot to specify the desired ordering matching
// rule! No worries, it can be done after the fact:
attr.SetOrdering(`integerOrderingMatch`)

fmt.Println(attr.Ordering().NumericOID())

Output:

2.5.13.15

func (AttributeType) SetSchema 

func (r AttributeType) SetSchema(schema Schema) AttributeType

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewAttributeType method.

This is a fluent method.

func (AttributeType) SetSingleValue 

func (r AttributeType) SetSingleValue(x any) AttributeType

SetSingleValue assigns the input value to the underlying SINGLE-VALUE clause within the receiver.

Input types may be bool, or string representations of bool. When strings are used, case is not significant.

Note that a value of true will be ignored if the receiver is a collective AttributeType.

This is a fluent method.

func (AttributeType) SetStringer 

func (r AttributeType) SetStringer(function ...Stringer) AttributeType

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the AttributeType.SetStringer method to impose a custom Stringer closure over the default instance.

Naturally the end-user would opt for a more useful stringer, such as one that produces singular CSV rows per instance.

To avoid impacting other unit tests, we reset the default stringer via the AttributeType.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

cn := mySchema.AttributeTypes().Get(`cn`)
cn.SetStringer(func() string {
	return "This useless message brought to you by a dumb stringer"
})

msg := fmt.Sprintln(cn)
cn.SetStringer() // return it to its previous state if need be ...

fmt.Printf("Original: %s\nOld: %s", cn, msg)

Output:

Original: ( 2.5.4.3
    NAME ( 'cn' 'commonName' )
    DESC 'RFC4519: common name(s) for which the entity is known by'
    SUP name
    X-ORIGIN 'RFC4519' )
Old: This useless message brought to you by a dumb stringer

func (AttributeType) SetSubstring 

func (r AttributeType) SetSubstring(x any) AttributeType

SetSubstring sets the substring MatchingRule of the receiver instance.

Input x may be the string representation of the desired substring matchingRule, by name or numeric OID. This requires an underlying instance of Schema set within the receiver instance. The Schema instance is expected to possess the referenced MatchingRule, else a zero instance will ultimately be returned and discarded.

Input x may also be a bonafide, non-zero instance of a substring MatchingRule. This requires no underlying Schema instance, but may allow the introduction of bogus MatchingRule instances.

This is a fluent method.

Example

This example demonstrates the assignment of a SUBSTR MatchingRule instance to an AttributeType instance during assembly.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// First we'll craft a fake attribute
raw := `( 1.3.6.1.4.1.56521.999.14.56.1
                NAME 'coolattr'
                SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )`

var attr AttributeType = mySchema.NewAttributeType()
if err := attr.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

// Oh no! We forgot to specify the desired substring matching
// rule! No worries, it can be done after the fact:
attr.SetSubstring(`caseIgnoreSubstringsMatch`)

fmt.Println(attr.Substring().NumericOID())

Output:

2.5.13.4

func (AttributeType) SetSuperType 

func (r AttributeType) SetSuperType(x any) AttributeType

SetSuperType sets the super type of the receiver to the value provided. Valid input types are string, to represent an RFC 4512 OID residing in the underlying Schema instance, or an actual AttributeType instance already obtained or crafted.

This is a fluent method.

func (AttributeType) SetSyntax 

func (r AttributeType) SetSyntax(x any) AttributeType

SetSyntax assigns x to the receiver instance as an instance of LDAPSyntax.

This is a fluent method.

Example

This example demonstrates the assignment of an LDAPSyntax instance to an AttributeType instance during assembly.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// First we'll craft a fake attribute
raw := `( 1.3.6.1.4.1.56521.999.14.56.1
                NAME 'coolattr'
		EQUALITY caseIgnoreMatch )`

var attr AttributeType = mySchema.NewAttributeType()
if err := attr.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

// Oh no! We forgot to specify the desired syntax!
// No worries, it can be done after the fact:
attr.SetSyntax(`1.3.6.1.4.1.1466.115.121.1.26`)

fmt.Println(attr.Syntax().Description())

Output:

IA5 String

func (AttributeType) SetUsage 

func (r AttributeType) SetUsage(u any) AttributeType

SetUsage assigns the specified USAGE to the receiver. Input types may be string, int or uint. 

1, or directoryOperation
2, or distributedOperation
3, or dSAOperation

Any other value results in assignment of the userApplications USAGE.

This is a fluent method.

func (AttributeType) SetValueQualifier 

func (r AttributeType) SetValueQualifier(function ValueQualifier) AttributeType

SetValueQualifier assigns an instance of ValueQualifier to the receiver instance. A nil value may be passed to disable general value qualification capabilities.

See the AttributeType.QualifyValue method for details on making active use of the ValueQualifier capabilities.

This is a fluent method.

func (AttributeType) SingleValue 

func (r AttributeType) SingleValue() (o bool)

SingleValue returns a Boolean value indicative of whether the receiver is set to only allow one (1) value to be assigned to an entry using this type. A value of true is mutually exclusive of COLLECTIVE AttributeType instances.

func (AttributeType) String 

func (r AttributeType) String() (def string)

String is a stringer method that returns the string representation of the receiver instance. A zero-value indicates an invalid receiver, or that the AttributeType.SetStringer method was not used during MANUAL composition of the receiver.

func (AttributeType) SubTypes added in v1.5.7 

func (r AttributeType) SubTypes() (subs AttributeTypes)

SubTypes returns an instance of AttributeTypes containing slices of AttributeType instances that are direct subordinates to the receiver instance. As such, this method is essentially the inverse of the AttributeType.SuperType method.

The super chain is NOT traversed beyond immediate subordinate instances.

Note that the relevant Schema instance must have been set using the AttributeType.SetSchema method prior to invocation of this method. Should this requirement remain unfulfilled, the return instance will be a zero instance.

func (AttributeType) Substring 

func (r AttributeType) Substring() (sub MatchingRule)

Substring returns the underlying instance of MatchingRule if set within the receiver instance. If unset, a zero instance is returned.

func (AttributeType) SubstringAssertion 

func (r AttributeType) SubstringAssertion(value1, value2 any) (err error)

SubstringAssertion returns an error following an attempt to perform an SUBSTR assertion match upon value1 and value2 using the effective MatchingRule honored by the receiver instance.

Example

This example demonstrates the means of performing a substring match assertion between two values by way of an AssertionMatcher closure assigned to the relevant MatchingRule instance in use by one or more AttributeType instances.

For this example, we'll use the regexp package for brevity.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Obtain the syntax of interest
cism := mySchema.MatchingRules().Get(`caseIgnoreSubstringsMatch`)

// Assign a new assertion matcher to our matching rule to
// allow caseless substring matching between two values.
cism.SetAssertionMatcher(func(val, substr any) (err error) {

	// Type assert x, allowing string or
	// byte values to be processed.
	var value, substring string
	switch tv := val.(type) {
	case string:
		value = tv
	case []byte:
		value = string(tv)
	default:
		err = ErrInvalidType
		return
	}

	// Now type assert y similarly.
	switch tv := substr.(type) {
	case string:
		substring = tv
	case []byte:
		substring = string(tv)
	default:
		err = ErrInvalidType
		return
	}

	// create expression, altering wildcards
	// to conform to regexp.
	pat := strings.ReplaceAll(substring, "*", ".*")

	// Compile the expression.
	re, _ := regexp.Compile("(?i)" + pat)
	if match := re.MatchString(value); !match {
		err = ErrNoMatch
	}

	return
})

// Check an attribute that is known to use the above
// matching rule.
cn := mySchema.AttributeTypes().Get(`2.5.4.3`) // or "cn"

// Compare two values via the SubstringAssertion method.
// In the context of an assertion check via LDAP, the
// first value (Kenny) could represent a value within
// the database being compared, while the second value
// (k*NN*) is the substring statement input by the user,
// ostensibly within an LDAP Search Filter.
ok := cn.SubstringAssertion(`Kenny`, `k*NN*`) == nil

fmt.Printf("Values match: %t", ok)

Output:

Values match: true

func (AttributeType) SuperChain 

func (r AttributeType) SuperChain() (sups AttributeTypes)

SuperChain returns an AttributeTypes stack of AttributeType instances which make up the super type chain of the receiver instance.

Example

This example demonstrates the means of gathering references to every superior AttributeType in the relevant super type chain.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

cn := mySchema.AttributeTypes().Get(`nisMapName`)
chain := cn.SuperChain()

for i := 0; i < chain.Len(); i++ {
	fmt.Println(chain.Index(i).OID())
}

Output:

name

func (AttributeType) SuperType 

func (r AttributeType) SuperType() (sup AttributeType)

SuperType returns the underlying instance of AttributeType if set within the receiver instance as its super type. If unset, a zero instance is returned.

func (AttributeType) Syntax 

func (r AttributeType) Syntax() (syntax LDAPSyntax)

Syntax returns the LDAPSyntax instance held (directly) by the receiver.

func (AttributeType) Type 

func (r AttributeType) Type() string

Type returns the string literal "attributeType".

Example 
var def AttributeType
fmt.Println(def.Type())

Output:

attributeType

func (AttributeType) Usage 

func (r AttributeType) Usage() (usage string)

Usage returns the string representation of the underlying USAGE if set within the receiver instance. If unset, a zero string -- which implies use of the UserApplicationsUsage USAGE value by default -- is returned.

Example

This example demonstrates determining the USAGE of an AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

ctime := mySchema.AttributeTypes().Get(`createTimestamp`)
fmt.Println(ctime.Usage())

Output:

directoryOperation

type AttributeTypes 

type AttributeTypes collection // RFC 4512 § 4.2.2

func NewAttributeTypeOIDList 

func NewAttributeTypeOIDList(label ...string) AttributeTypes

NewAttributeTypeOIDList initializes and returns a new AttributeTypes that has been cast from an instance of [OIDList] and configured to allow the storage of arbitrary AttributeType instances.

func NewAttributeTypes 

func NewAttributeTypes() AttributeTypes

NewAttributeTypes initializes and returns a new AttributeTypes instance, configured to allow the storage of all AttributeType instances.

func (AttributeTypes) Compliant 

func (r AttributeTypes) Compliant() bool

Compliant returns a Boolean value indicative of every AttributeType returning a compliant response from the AttributeType.Compliant method.

Example

This example demonstrates a compliancy check of the "name" AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

attrs := mySchema.AttributeTypes()
fmt.Println(attrs.Compliant())

Output:

true

func (AttributeTypes) Contains 

func (r AttributeTypes) Contains(id string) bool

Contains calls AttributeTypes.Get to return a Boolean value indicative of a successful, non-zero retrieval of an AttributeType instance -- matching the provided id -- from within the receiver stack instance.

Example

This example demonstrates a means of checking whether a particular instance of AttributeType is present within an instance of AttributeTypes.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

attrs := mySchema.AttributeTypes()
fmt.Println(attrs.Contains(`cn`)) // or "2.5.4.3"

Output:

true

func (AttributeTypes) Get 

func (r AttributeTypes) Get(id string) AttributeType

Get returns an instance of AttributeType based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of the principal identifier of an AttributeType and the provided id.

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (AttributeTypes) Index 

func (r AttributeTypes) Index(idx int) AttributeType

Index returns the instance of AttributeType found within the receiver stack instance at index N. If no instance is found at the index specified, a zero AttributeType instance is returned.

func (AttributeTypes) Inventory 

func (r AttributeTypes) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of AttributeType instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example

This example demonstrates the creation of an Inventory instance based upon the current contents of an AttributeTypes stack instance. Use of an Inventory instance is convenient in cases where a receiver of schema information may not be able to directly receive working stack instances and requires a more portable and generalized type.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

at := mySchema.AttributeTypes().Inventory()
fmt.Println(at[`2.5.4.3`][0])

Output:

cn

func (AttributeTypes) IsZero 

func (r AttributeTypes) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (AttributeTypes) Len 

func (r AttributeTypes) Len() int

Len returns the current integer length of the receiver instance.

func (AttributeTypes) Maps 

func (r AttributeTypes) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the AttributeTypes.Maps method, which produces slices of DefinitionMap instances containing AttributeType derived values

Here, we (quite recklessly) call index three (3) and reference index zero (0) of its `SYNTAX` key to obtain the relevant LDAPSyntax OID string value.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

defs := mySchema.AttributeTypes().Maps()
fmt.Println(defs[3][`SYNTAX`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.1466.115.121.1.24

func (AttributeTypes) Push 

func (r AttributeTypes) Push(at any) error

Push returns an error following an attempt to push an AttributeType into the receiver stack instance.

func (AttributeTypes) SetStringer 

func (r AttributeTypes) SetStringer(function ...Stringer) AttributeTypes

SetStringer allows the assignment of an individual Stringer function or method to all AttributeType slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the AttributeTypes.SetStringer method to impose a custom Stringer closure upon all stack members.

Naturally the end-user would opt for a more useful stringer, such as one that produces a CSV file containing all AttributeType instances.

To avoid impacting other unit tests, we reset the default stringer via the AttributeTypes.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

attrs := mySchema.AttributeTypes()
attrs.SetStringer(func() string {
	return "" // make a null stringer
})

output := attrs.String()
attrs.SetStringer() // return to default

fmt.Println(output)

Output:

func (AttributeTypes) String 

func (r AttributeTypes) String() string

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

func (AttributeTypes) Type 

func (r AttributeTypes) Type() string

Type returns the string literal "attributeTypes".

Example 
at := mySchema.AttributeTypes()
fmt.Println(at.Type())

Output:

attributeTypes

type Counters 

type Counters struct {
	LS int
	MR int
	AT int
	MU int
	OC int
	DC int
	NF int
	DS int
}

Counters is a simple struct type defined to store the current number of definition instances within an instance of Schema.

Instances of this type are NOT thread-safe.

type DITContentRule 

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

DITContentRule implements § 4.1.6 of RFC 4512. 

DITContentRuleDescription = LPAREN WSP
    numericoid                 ; object identifier
    [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
    [ SP "DESC" SP qdstring ]  ; description
    [ SP "OBSOLETE" ]          ; not active
    [ SP "AUX" SP oids ]       ; auxiliary object classes
    [ SP "MUST" SP oids ]      ; attribute types
    [ SP "MAY" SP oids ]       ; attribute types
    [ SP "NOT" SP oids ]       ; attribute types
    extensions WSP RPAREN      ; extensions

From clause 13.8.2 of ITU-T Rec. X.501: 

CONTENT-RULE ::= CLASS {
	&structuralClass OBJECT-CLASS.&id UNIQUE,
	&Auxiliaries OBJECT-CLASS OPTIONAL,
	&Mandatory ATTRIBUTE OPTIONAL,
	&Optional ATTRIBUTE OPTIONAL,
	&Precluded ATTRIBUTE OPTIONAL }

WITH SYNTAX {
	STRUCTURAL OBJECT-CLASS &structuralClass
	[AUXILIARY OBJECT-CLASSES &Auxiliaries]
	[MUST CONTAIN &Mandatory]
	[MAY CONTAIN &Optional]
	[MUST-NOT CONTAIN &Precluded] }

func NewDITContentRule 

func NewDITContentRule() DITContentRule

NewDITContentRule initializes and returns a new instance of DITContentRule, ready for manual assembly. This method need not be used when creating new DITContentRule instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the DITContentRule.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewDITContentRule method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of DITContentRule instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an DITContentRule instance.

Example

This example demonstrates the manual (non-parsed) assembly of a new ObjectClass instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

oc := NewDITContentRule() // Important! Initializes internal stacks

// Conveniently input values in fluent form ...
oc.SetSchema(mySchema).
	SetName(`engineeringPersonnel`).
	SetDescription(`EP-46: Engineering employee`).
	SetNumericOID(`0.9.2342.19200300.100.4.5`).
	SetMust(`uid`).
	SetMay(`description`, `seeAlso`, `l`, `o`, `ou`).
	SetNot(`host`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer() // use default stringer

fmt.Println(oc)

Output:

( 0.9.2342.19200300.100.4.5
    NAME 'engineeringPersonnel'
    DESC 'EP-46: Engineering employee'
    MUST uid
    MAY ( description
        $ seeAlso
        $ l
        $ o
        $ ou )
    NOT host
    X-ORIGIN 'NOWHERE' )

func (DITContentRule) Aux 

func (r DITContentRule) Aux() (aux ObjectClasses)

Aux returns an ObjectClasses containing zero (0) or more auxiliary ObjectClass definitions for use within entries governed by this rule.

func (DITContentRule) Compliant 

func (r DITContentRule) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.6 of RFC 4512:

  • Numeric OID must relate to a predefined ObjectClass in the associated Schema instance
  • ObjectClass referenced by OID must be STRUCTURAL
  • ObjectClass referenced by OID must be COMPLIANT itself
  • Collective AttributeType instances are permitted, but not verified as they are never present in any ObjectClass
  • MUST, MAY and NOT clause AttributeType instances are limited to those present in the ObjectClass super chain
  • No conflicting clause values (e.g.: cannot forbid (NOT) a required type (MUST)), with emphasis on related DITStructureRule FORM (NameForm) instances.
Example

This example demonstrates a compliancy check of the "account" ObjectClass. 

dc := mySchema.DITContentRules().Index(0)
fmt.Println(dc.Compliant())

Output:

true

func (DITContentRule) Data 

func (r DITContentRule) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the DITContentRule.SetData method.

func (DITContentRule) Description 

func (r DITContentRule) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

func (DITContentRule) Extensions 

func (r DITContentRule) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver.

func (DITContentRule) IsIdentifiedAs 

func (r DITContentRule) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or descriptor of the receiver instance. Case is not significant in the matching process.

Example 
oc := mySchema.DITContentRules().Get(`arcContent`)
fmt.Println(oc.IsIdentifiedAs(`1.3.6.1.4.1.56521.101.2.5.3`))

Output:

true

func (DITContentRule) IsZero 

func (r DITContentRule) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (DITContentRule) Map 

func (r DITContentRule) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example 
def := mySchema.DITContentRules().Index(0)
fmt.Println(def.Map()[`NUMERICOID`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.56521.101.2.5.3

func (DITContentRule) May 

func (r DITContentRule) May() (may AttributeTypes)

May returns an AttributeTypes containing zero (0) or more allowed AttributeType definitions for use within entries governed by this rule.

func (DITContentRule) Must 

func (r DITContentRule) Must() (must AttributeTypes)

Must returns an AttributeTypes containing zero (0) or more required AttributeType definitions for use within entries governed by this rule.

func (DITContentRule) Name 

func (r DITContentRule) Name() (id string)

Name returns the string form of the principal name of the receiver instance, if set.

func (DITContentRule) Names 

func (r DITContentRule) Names() (names QuotedDescriptorList)

Names returns the underlying instance of QuotedDescriptorList from within the receiver.

func (DITContentRule) Not 

func (r DITContentRule) Not() (not AttributeTypes)

Not returns an AttributeTypes containing zero (0) or more AttributeType definitions disallowed for use within entries governed by this rule.

func (DITContentRule) NumericOID 

func (r DITContentRule) NumericOID() (noid string)

NumericOID returns the string representation of the numeric OID held by the receiver instance.

func (DITContentRule) OID 

func (r DITContentRule) OID() (oid string)

OID returns the string representation of an OID -- which is either a numeric OID or descriptor -- that is held by the receiver instance.

func (DITContentRule) Obsolete 

func (r DITContentRule) Obsolete() (o bool)

Obsolete returns a Boolean value indicative of definition obsolescence.

func (DITContentRule) Parse 

func (r DITContentRule) Parse(raw string) (err error)

Parse returns an error following an attempt to parse raw into the receiver instance.

Note that the receiver MUST possess a Schema reference prior to the execution of this method.

Also note that successful execution of this method does NOT automatically push the receiver into any DITContentRules stack, nor does it automatically execute the DITContentRule.SetStringer method, leaving these tasks to the user. If the automatic handling of these tasks is desired, see the Schema.ParseDITContentRule method as an alternative.

func (DITContentRule) Replace 

func (r DITContentRule) Replace(x DITContentRule) DITContentRule

Replace overrides the receiver with x. Both must bear an identical numeric OID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the DITContentRule envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

func (DITContentRule) Schema 

func (r DITContentRule) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (DITContentRule) SetAux 

func (r DITContentRule) SetAux(m ...any) DITContentRule

SetAux assigns the provided input ObjectClass instance(s) -- which must be AUXILIARY via the AuxiliaryKind constant -- to the receiver's AUX clause.

This is a fluent method.

func (DITContentRule) SetData 

func (r DITContentRule) SetData(x any) DITContentRule

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the DITContentRule.Data method.

This is a fluent method.

Example

This example demonstrates the assignment of arbitrary data to an instance of ObjectClass.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// The value can be any type, but we'll
// use a string for simplicity.
documentation := `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`

// Obtain the target attribute type to bear
// the assigned value.
dvc := mySchema.DITContentRules().Index(0)

// Set it.
dvc.SetData(documentation)

// Get it and compare to the original.
equal := documentation == dvc.Data().(string)

fmt.Printf("Values are equal: %t", equal)

Output:

Values are equal: true

func (DITContentRule) SetDescription 

func (r DITContentRule) SetDescription(desc string) DITContentRule

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

This is a fluent method.

func (DITContentRule) SetExtension 

func (r DITContentRule) SetExtension(x string, xstrs ...string) DITContentRule

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (DITContentRule) SetMay 

func (r DITContentRule) SetMay(m ...any) DITContentRule

SetMay assigns the provided input AttributeType instance(s) to the receiver's MAY clause.

This is a fluent method.

func (DITContentRule) SetMust 

func (r DITContentRule) SetMust(m ...any) DITContentRule

SetMust assigns the provided input AttributeType instance(s) to the receiver's MUST clause.

This is a fluent method.

func (DITContentRule) SetName 

func (r DITContentRule) SetName(x ...string) DITContentRule

SetName assigns the provided names to the receiver instance.

Name instances must conform to RFC 4512 descriptor format but need not be quoted.

This is a fluent method.

func (DITContentRule) SetNot 

func (r DITContentRule) SetNot(m ...any) DITContentRule

SetNot assigns the provided input AttributeType instance(s) to the receiver's NOT clause.

This is a fluent method.

func (DITContentRule) SetNumericOID 

func (r DITContentRule) SetNumericOID(id string) DITContentRule

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (DITContentRule) SetObsolete 

func (r DITContentRule) SetObsolete() DITContentRule

SetObsolete sets the receiver instance to OBSOLETE if not already set. Note that obsolescence cannot be unset.

This is a fluent method.

Example 
fake := NewDITContentRule().
	SetNumericOID(`1.3.6.1.4.1.56521.999.108.4`).
	SetName(`obsoleteClass`).
	SetObsolete()

fmt.Println(fake.Obsolete())

Output:

true

func (DITContentRule) SetSchema 

func (r DITContentRule) SetSchema(schema Schema) DITContentRule

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewDITContentRule method.

This is a fluent method.

func (DITContentRule) SetStringer 

func (r DITContentRule) SetStringer(function ...Stringer) DITContentRule

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the ObjectClass.SetStringer method to impose a custom Stringer closure over the default instance.

Naturally the end-user would opt for a more useful stringer, such as one that produces singular CSV rows per instance.

To avoid impacting other unit tests, we reset the default stringer via the ObjectClass.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

opers := mySchema.DITContentRules().Index(0)
opers.SetStringer(func() string {
	return "This useless message brought to you by a dumb stringer"
})

msg := fmt.Sprintln(opers)
opers.SetStringer() // return it to its previous state if need be ...

fmt.Printf("Original: %s\nOld: %s", opers, msg)

Output:

Original: ( 1.3.6.1.4.1.56521.101.2.5.3
    NAME 'arcContent'
    DESC 'arc entry content rule'
    AUX ( x660Context
        $ x667Context
        $ x680Context
        $ x690Context )
    MUST ( aSN1Notation
         $ iRI
         $ identifier
         $ n
         $ unicodeValue )
    MAY ( additionalUnicodeValue
        $ nameAndNumberForm
        $ secondaryIdentifier
        $ standardizedNameForm )
    NOT dotNotation
    X-ORIGIN 'draft-coretta-oiddir-schema; unofficial supplement'
    X-WARNING 'UNOFFICIAL' )
Old: This useless message brought to you by a dumb stringer

func (DITContentRule) String 

func (r DITContentRule) String() (dcr string)

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

func (DITContentRule) StructuralClass added in v1.5.4 

func (r DITContentRule) StructuralClass() (soc ObjectClass)

StructuralClass returns the STRUCTURAL ObjectClass set within the receiver instance, or a zero instance if unset.

func (DITContentRule) Type 

func (r DITContentRule) Type() string

Type returns the string literal "dITContentRule".

Example 
var def DITContentRule
fmt.Println(def.Type())

Output:

dITContentRule

type DITContentRules 

type DITContentRules collection // RFC 4512 § 4.2.6

func NewDITContentRules 

func NewDITContentRules() DITContentRules

NewDITContentRules initializes a new DITContentRules instance.

func (DITContentRules) Compliant 

func (r DITContentRules) Compliant() bool

Compliant returns a Boolean value indicative of every DITContentRule returning a compliant response from the DITContentRule.Compliant method.

Example

This example demonstrates a compliancy check of all ObjectClasses members.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

rules := mySchema.DITContentRules()
fmt.Println(rules.Compliant())

Output:

true

func (DITContentRules) Contains 

func (r DITContentRules) Contains(id string) bool

Contains calls DITStructureRules.Get to return a Boolean value indicative of a successful, non-zero retrieval of an DITStructureRule instance -- matching the provided id -- from within the receiver stack instance.

Example

This example demonstrates a means of checking whether a particular instance of ObjectClass is present within an instance of ObjectClasses.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

rules := mySchema.DITContentRules()
fmt.Println(rules.Contains(`arcContent`)) // or "1.3.6.1.4.1.56521.101.2.5.3"

Output:

true

func (DITContentRules) Get 

func (r DITContentRules) Get(id string) DITContentRule

Get returns an instance of DITContentRule based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of the principal identifier of an DITContentRule and the provided id.

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (DITContentRules) Index 

func (r DITContentRules) Index(idx int) DITContentRule

Index returns the instance of DITContentRule found within the receiver stack instance at index N. If no instance is found at the index specified, a zero DITContentRule instance is returned.

func (DITContentRules) Inventory 

func (r DITContentRules) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of DITContentRule instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example 
dc := mySchema.DITContentRules().Inventory()
fmt.Println(dc[`1.3.6.1.4.1.56521.101.2.5.3`][0])

Output:

arcContent

func (DITContentRules) IsZero 

func (r DITContentRules) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (DITContentRules) Len 

func (r DITContentRules) Len() int

Len returns the current integer length of the receiver instance.

func (DITContentRules) Maps 

func (r DITContentRules) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the ObjectClasses.Maps method, which produces slices of DefinitionMap instances born of the ObjectClasses stack in which they reside. We (quite recklessly) call index three (3) and reference index zero (0) of its `SYNTAX` key to obtain the relevant LDAPSyntax OID string value. 

defs := mySchema.DITContentRules().Maps()
fmt.Println(defs[0][`NUMERICOID`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.56521.101.2.5.3

func (DITContentRules) Push 

func (r DITContentRules) Push(dc any) error

Push returns an error following an attempt to push a DITContentRule into the receiver stack instance.

func (DITContentRules) SetStringer 

func (r DITContentRules) SetStringer(function ...Stringer) DITContentRules

SetStringer allows the assignment of an individual Stringer function or method to all DITContentRule slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the ObjectClasses.SetStringer method to impose a custom Stringer closure upon all stack members.

Naturally the end-user would opt for a more useful stringer, such as one that produces a CSV file containing all ObjectClass instances.

To avoid impacting other unit tests, we reset the default stringer via the ObjectClasses.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

attrs := mySchema.DITContentRules()
attrs.SetStringer(func() string {
	return "" // make a null stringer
})

output := attrs.String()
attrs.SetStringer() // return to default

fmt.Println(output)

Output:

func (DITContentRules) String 

func (r DITContentRules) String() string

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

func (DITContentRules) Type 

func (r DITContentRules) Type() string

Type returns the string literal "dITContentRules".

Example 
oc := mySchema.DITContentRules()
fmt.Println(oc.Type())

Output:

dITContentRules

type DITStructureRule 

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

DITStructureRule implements § 4.1.7.1 of RFC 4512. 

DITStructureRuleDescription = LPAREN WSP
    ruleid                     ; rule identifier
    [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
    [ SP "DESC" SP qdstring ]  ; description
    [ SP "OBSOLETE" ]          ; not active
    SP "FORM" SP oid           ; NameForm
    [ SP "SUP" SP ruleids ]    ; superior rules <NOTE: SEE ERRATA # 7896>
    extensions WSP RPAREN      ; extensions

ruleids = ruleid / ( LPAREN WSP ruleidlist WSP RPAREN )
ruleidlist = ruleid *( SP ruleid )
ruleid = number

From clause 13.7.6 of ITU-T Rec. X.501: 

DITStructureRule ::= SEQUENCE {
	ruleIdentifier RuleIdentifier,
	-- shall be unique within the scope of the subschema
	nameForm NAME-FORM.&id,
	superiorStructureRules SET SIZE (1..MAX) OF RuleIdentifier OPTIONAL,
	... }

RuleIdentifier ::= INTEGER

STRUCTURE-RULE ::= CLASS {
	&nameForm NAME-FORM,
	&SuperiorStructureRules STRUCTURE-RULE.&id OPTIONAL,
	&id RuleIdentifier }

WITH SYNTAX {
	NAME FORM &nameForm
	[SUPERIOR RULES &SuperiorStructureRules]
	ID &id }

func NewDITStructureRule 

func NewDITStructureRule() DITStructureRule

NewDITStructureRule initializes and returns a new instance of DITStructureRule, ready for manual assembly. This method need not be used when creating new DITStructureRule instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the DITStructureRule.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewDITStructureRule method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of DITStructureRule instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an DITStructureRule instance.

Example

This example demonstrates the creation of a DITStructureRule. 

// First create a name form that requires an
// RDN of uid=<val>, or (optionally) an RDN
// of uid=<val>+gidNumber=<val>
perForm := mySchema.NewNameForm().
	SetNumericOID(`1.3.6.1.4.1.56521.999.16.7`).
	SetName(`fictionalPersonForm`).
	SetDescription(`generalized person name form`).
	SetOC(`person`).
	SetMust(`uid`).
	SetMay(`gidnumber`).
	SetStringer()

// Create the structure rule and assign the
// new nameform
ds := mySchema.NewDITStructureRule().
	SetRuleID(0).
	SetName(`fictionalPersonStructure`).
	SetDescription(`person structure rule`).
	SetForm(perForm).
	SetStringer()

fmt.Println(ds)

Output:

( 0
    NAME 'fictionalPersonStructure'
    DESC 'person structure rule'
    FORM fictionalPersonForm )

func (DITStructureRule) Compliant 

func (r DITStructureRule) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.7.1 of RFC 4512:

  • "rule ID" must be specified in the form of an unsigned integer of any magnitude
  • FORM clause MUST refer to a known NameForm instance within the associated Schema instance
  • FORM clause MUST refer to a COMPLIANT NameForm
  • FORM must not violate, or be violated by, a relevant DITContentRule within the associated Schema instance
Example

This example demonstrates a compliancy check of a DITStructureRule instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// grab our dITStructureRule bearing an ID of zero (0)
ds := mySchema.DITStructureRules().Get(0) // or "rootArcStructure"
fmt.Println(ds.Compliant())

Output:

true

func (DITStructureRule) Data 

func (r DITStructureRule) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the DITStructureRule.SetData method.

func (DITStructureRule) Description 

func (r DITStructureRule) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

func (DITStructureRule) Extensions 

func (r DITStructureRule) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver.

func (DITStructureRule) Form 

func (r DITStructureRule) Form() (nf NameForm)

Form returns the underlying instance of NameForm set within the receiver. If unset, a zero instance is returned.

func (DITStructureRule) ID 

func (r DITStructureRule) ID() (id string)

ID returns the string representation of the principal name OR rule ID held by the receiver instance.

Example

This example demonstrates the means of accessing the string form of the principal name OR rule ID of a DITStructureRule instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.DITStructureRules().Get(0)
fmt.Println(def.ID())

Output:

rootArcStructure

func (DITStructureRule) IsIdentifiedAs 

func (r DITStructureRule) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or descriptor of the receiver instance. Case is not significant in the matching process.

Example 
def := mySchema.DITStructureRules().Get(0)
fmt.Println(def.IsIdentifiedAs(`rootArcStructure`))

Output:

true

func (DITStructureRule) IsZero 

func (r DITStructureRule) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

Example

This example demonstrates the means of checking whether an instance of DITStructureRule is of a nil state. 

var def DITStructureRule
fmt.Println(def.IsZero())

Output:

true

func (DITStructureRule) Map 

func (r DITStructureRule) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example

This example demonstrates the means of transforming an instance of DITStructureRule into an instance of DefinitionMap for simplified use.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.DITStructureRules().Get(0)
fmt.Println(def.Map()[`NAME`][0])

Output:

rootArcStructure

func (DITStructureRule) Name 

func (r DITStructureRule) Name() (id string)

Name returns the string form of the principal name of the receiver instance, if set.

Example

This example demonstrates the means of accessing the principal name of an instance of DITStructureRule.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.DITStructureRules().Get(0)
fmt.Println(def.Name())

Output:

rootArcStructure

func (DITStructureRule) Names 

func (r DITStructureRule) Names() (names QuotedDescriptorList)

Names returns the underlying instance of QuotedDescriptorList from within the receiver.

Example

This example demonstrates the means of accessing the QuotedDescriptorList instance containing the name(s) by which a DITStructureRule is known.

Use of this method will encapsulate the value(s), per § 4.1 of RFC 4512, using single quotes (SQUOTE ('), ASCII %x27).

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.DITStructureRules().Get(1) // or "1"
fmt.Println(def.Names())

Output:

'arcStructure'

func (DITStructureRule) NumericOID 

func (r DITStructureRule) NumericOID() string

NumericOID returns an empty string, as DITStructureRule definitions do not bear numeric OIDs. This method exists only to satisfy Go interface requirements.

Example

This example demonstrates the futility of the DITStructureRule.NumericOID method. Numeric OIDs are not used to identify instances of DITStructureRule.

The DITStructureRule.NumericOID method only exists to satisfy Go's interface signature requirements with regards to the Definition interface type. 

// access a known valid dITStructureRule
def := mySchema.DITStructureRules().Get(2) // or 'dotNotArcStructure'
fmt.Println(def.NumericOID())

Output:

func (DITStructureRule) Obsolete 

func (r DITStructureRule) Obsolete() (o bool)

Obsolete returns a Boolean value indicative of definition obsolescence.

func (DITStructureRule) Parse 

func (r DITStructureRule) Parse(raw string) (err error)

Parse returns an error following an attempt to parse raw into the receiver instance.

Note that the receiver MUST possess a Schema reference prior to the execution of this method.

Also note that successful execution of this method does NOT automatically push the receiver into any DITStructureRules stack, nor does it automatically execute the DITStructureRule.SetStringer method, leaving these tasks to the user. If the automatic handling of these tasks is desired, see the Schema.ParseDITStructureRule method as an alternative.

Example

This example demonstrates a means of parsing a raw definition into a new instance of AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.NewDITStructureRule()

err := def.Parse(`( 31
                NAME 'fakeStructureRule'
		DESC 'fake structure rule'
		FORM dotNotationArcForm
                X-ORIGIN 'NOWHERE' )`)

fmt.Println(err)

Output:

<nil>
Example (Bogus)

This example demonstrates the parsing of a bogus definition, which results in the return of an error by the underlying ANTLR parser.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.NewDITStructureRule()

// feed the parser a subtly bogus definition ...
err := def.Parse(`( -1
                NAME 'fakeStructureRule'
		DESC 'fake structure rule'
		FORM dotNotationArcForm
                X-ORIGIN 'YOUR FACE' )`)

fmt.Println(err)

Output:

Inconsistent antlr4512.DITStructureRule parse results or bad content

func (DITStructureRule) Replace 

func (r DITStructureRule) Replace(x DITStructureRule) DITStructureRule

Replace overrides the receiver with x. Both must bear an identical numeric rule ID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the DITStructureRule envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

Example

This example demonstrates the replacement process of an DITStructureRule instance within an instance of DITStructureRules.

For reasons of oversight, we've added a custom extension X-WARNING to remind users and admin alike of the modification.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.NewDITStructureRule()

err := def.Parse(`( 31
                NAME 'fakeStructureRule'
                DESC 'fake structure rule'
                FORM dotNotationArcForm
                X-ORIGIN 'NOWHERE' )`)

if err != nil {
	fmt.Println(err)
	return
}

def2 := mySchema.NewDITStructureRule()
err = def2.Parse(`( 31
                NAME 'fakeStructureRule'
                DESC 'fake structure rule updated'
                FORM dotNotationArcForm
                X-ORIGIN 'ANYWHERE' )`)

if err != nil {
	fmt.Println(err)
	return
}

def.Replace(def2)
fmt.Println(def.Description())

Output:

fake structure rule updated

func (DITStructureRule) RuleID 

func (r DITStructureRule) RuleID() (id uint)

RuleID returns the unsigned integer identifier held by the receiver instance.

Example

This example demonstrates the means of accessing the unsigned rule ID held by an instance of DITStructureRule.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.DITStructureRules().Get(`arcStructure`) // or 1, or "1"
fmt.Println(def.RuleID())

Output:

1

func (DITStructureRule) Schema 

func (r DITStructureRule) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (DITStructureRule) SetData 

func (r DITStructureRule) SetData(x any) DITStructureRule

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the DITStructureRule.Data method.

This is a fluent method.

Example

This example demonstrates the assignment of arbitrary data to an instance of AttributeType.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

nf := mySchema.NewNameForm().
	SetNumericOID(`1.3.6.1.4.1.56521.999.16.7`).
	SetName(`personForm`).
	SetDescription(`generalized person name form`).
	SetOC(`person`).
	SetMust(`uid`).
	SetMay(`gidnumber`).
	SetStringer()

//mySchema.NameForms().Push(nf)

// Create the structure rule and assign the
// new nameform
ds := mySchema.NewDITStructureRule().
	SetRuleID(0).
	SetName(`personStructure`).
	SetDescription(`person structure rule`).
	SetForm(nf).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer()

// The value can be any type, but we'll
// use a string for simplicity.
documentation := `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`

// Set it.
ds.SetData(documentation)

// Get it and compare to the original.
equal := documentation == ds.Data().(string)

fmt.Printf("Values are equal: %t", equal)

Output:

Values are equal: true

func (DITStructureRule) SetDescription 

func (r DITStructureRule) SetDescription(desc string) DITStructureRule

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

This is a fluent method.

func (DITStructureRule) SetExtension 

func (r DITStructureRule) SetExtension(x string, xstrs ...string) DITStructureRule

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (DITStructureRule) SetForm 

func (r DITStructureRule) SetForm(x any) DITStructureRule

SetForm assigns x to the receiver instance as an instance of NameForm.

This is a fluent method.

func (DITStructureRule) SetName 

func (r DITStructureRule) SetName(x ...string) DITStructureRule

SetName assigns the provided names to the receiver instance.

Name instances must conform to RFC 4512 descriptor format but need not be quoted.

This is a fluent method.

func (DITStructureRule) SetObsolete 

func (r DITStructureRule) SetObsolete() DITStructureRule

SetObsolete sets the receiver instance to OBSOLETE if not already set. Note that obsolescence cannot be unset.

This is a fluent method.

Example

This example demonstrates use of the DITStructureRule.SetObsolete method to impose obsolescence upon the receiver instance.

Note: we craft a throw-away instance so as to avoid impacting other unit tests as a result of declaring obsolescence upon an otherwise valid instance. 

defs := NewDITStructureRule()
defs.SetName(`throwAwayStructure`)
defs.SetRuleID(10)
defs.SetObsolete()
fmt.Printf("%s is obsolete: %t", defs.Name(), defs.Obsolete())

Output:

throwAwayStructure is obsolete: true

func (DITStructureRule) SetRuleID 

func (r DITStructureRule) SetRuleID(id any) DITStructureRule

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (DITStructureRule) SetSchema 

func (r DITStructureRule) SetSchema(schema Schema) DITStructureRule

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewDITStructureRule method.

This is a fluent method.

func (DITStructureRule) SetStringer 

func (r DITStructureRule) SetStringer(function ...Stringer) DITStructureRule

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the DITStructureRule.SetStringer method to impose a custom Stringer closure over the default instance.

Naturally the end-user would opt for a more useful stringer, such as one that produces singular CSV rows per instance.

To avoid impacting other unit tests, we reset the default stringer via the DITStructureRule.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

ds := mySchema.DITStructureRules().Get(2)
ds.SetStringer(func() string {
	return "This useless message brought to you by a dumb stringer"
})

msg := fmt.Sprintln(ds)
ds.SetStringer() // return it to its previous state

fmt.Printf("Original: %s\nOld: %s", ds, msg)
// Original: ( 2
//     NAME 'dotNotArcStructure'
//     DESC 'structure rule for two dimensional arc entries; FOR DEMONSTRATION USE ONLY'
//     FORM dotNotationArcForm
//     SUP 0
//     X-ORIGIN 'draft-coretta-oiddir-schema; unofficial supplement' )
// Old: This useless message brought to you by a dumb stringer

Output:

func (DITStructureRule) SetSuperRule 

func (r DITStructureRule) SetSuperRule(m ...any) DITStructureRule

SetSuperRule assigns the provided input DITStructureRule instance(s) to the receiver's SUP clause.

This is a fluent method.

Example

This example demonstrates the means of manually assigning a superior DITStructureRule to the receiver instance, thereby rendering it subordinate it context.

Note: we craft a throw-away instance just for the sake of simplicity.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

super := mySchema.DITStructureRules().Get(2)
defs := mySchema.NewDITStructureRule()
defs.SetName(`throwAwaySubStructure`)
defs.SetRuleID(10)
defs.SetSuperRule(super)
fmt.Printf("Superior rule is %s", defs.SuperRules().Index(0).ID())

Output:

Superior rule is dotNotArcStructure

func (DITStructureRule) String 

func (r DITStructureRule) String() (dsr string)

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

func (DITStructureRule) SubRules added in v1.5.7 

func (r DITStructureRule) SubRules() (subs DITStructureRules)

SubRules returns an instance of DITStructureRules containing slices of DITStructureRule instances that are direct subordinates to the receiver instance. As such, this method is essentially the inverse of the DITStructureRule.SuperRules method.

The super chain is NOT traversed beyond immediate subordinate instances.

Note that the relevant Schema instance must have been set using the DITStructureRule.SetSchema method prior to invocation of this method. Should this requirement remain unfulfilled, the return instance will be a zero instance.

Example

This example demonstrates the means of accessing all subordinate rule instances of the receiver instance.

In essence, this method is the opposite of the DITStructureRule.SuperRules method and may return zero (0) or more DITStructureRule instances within the return DITStructureRules instance. 

def := mySchema.DITStructureRules().Get(0)
fmt.Printf("%d subordinate rules found", def.SubRules().Len())

Output:

2 subordinate rules found

func (DITStructureRule) SuperRules 

func (r DITStructureRule) SuperRules() (sup DITStructureRules)

SuperRules returns a DITStructureRules containing zero (0) or more superior DITStructureRule instances from which the receiver extends.

Example

This example demonstrates the means of accessing any and all immediate superior DITStructureRule instances for the receiver instance. The super chain of rules is NOT traversed indefinitely.

The DITStructureRule.NumericOID method only exists to satisfy Go's interface signature requirements with regards to the Definition interface type. 

def := mySchema.DITStructureRules().Get(2) // or 'dotNotArcStructure'
fmt.Println(def.SuperRules())

Output:

0

func (DITStructureRule) Type 

func (r DITStructureRule) Type() string

Type returns the string literal "dITStructureRule".

Example

This example demonstrates accessing the string type name of a DITStructureRule definition. This is mainly used as a low-cost alternative to type assertion when dealing with Definition interface type instances. 

var def DITStructureRule
fmt.Println(def.Type())

Output:

dITStructureRule

type DITStructureRules 

type DITStructureRules collection // RFC 4512 § 4.2.7

func NewDITStructureRuleIDList 

func NewDITStructureRuleIDList() DITStructureRules

NewDITStructureRuleIDList initializes a new RuleIDList instance and casts it as a DITStructureRules instance.

This is mainly used to define a series of superior DITStructureRule instances specified by a subordinate instance of DITStructureRule.

func NewDITStructureRules 

func NewDITStructureRules() DITStructureRules

NewDITStructureRules initializes a new DITStructureRules instance.

func (DITStructureRules) Compliant 

func (r DITStructureRules) Compliant() bool

Compliant returns a Boolean value indicative of every DITStructureRule returning a compliant response from the DITStructureRule.Compliant method.

Example

This example demonstrates a compliancy check of a DITStructureRules instance.

Generally use of this method is unnecessary due to stringent checks imposed upon submitted DITStructureRule instance during the "Push" process.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// grab our dITStructureRules collection
defs := mySchema.DITStructureRules()
fmt.Println(defs.Compliant())

Output:

true

func (DITStructureRules) Contains 

func (r DITStructureRules) Contains(id string) bool

Contains calls [Contains.Get] to return a Boolean value indicative of a successful, non-zero retrieval of an DITStructureRules instance -- matching the provided id -- from within the receiver stack instance.

Example

This example demonstrates a means of checking whether a particular instance of DITStructureRule is present within an instance of DITStructureRules.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

fmt.Println(mySchema.DITStructureRules().Contains(`rootArcStructure`))

Output:

true

func (DITStructureRules) Get 

func (r DITStructureRules) Get(id any) DITStructureRule

Get returns an instance of DITStructureRule based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of the principal identifier of an DITStructureRule and the provided id.

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (DITStructureRules) Index 

func (r DITStructureRules) Index(idx int) DITStructureRule

Index returns the instance of DITStructureRule found within the receiver stack instance at index N. If no instance is found at the index specified, a zero DITStructureRule instance is returned.

Example

This example demonstrates the means of calling the Nth DITStructureRule slice instance from the DITStructureRules collection instance in which it resides.

This method should not be confused with DITStructureRules.Get, which deals with unsigned rule IDs and names of definitions -- not indices. 

defs := mySchema.DITStructureRules()
fmt.Println(defs.Index(0).Name())

Output:

rootArcStructure

func (DITStructureRules) Inventory 

func (r DITStructureRules) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of DITStructureRule instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example

This example demonstrates the creation of an Inventory instance based upon the current contents of a DITStructureRules instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

defs := mySchema.DITStructureRules()
inv := defs.Inventory()
fmt.Println(inv[`2`][0])

Output:

dotNotArcStructure

func (DITStructureRules) IsZero 

func (r DITStructureRules) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

Example

This example demonstrates the means of checking whether an instance of DITStructureRules is of a nil state. 

var defs DITStructureRules
fmt.Println(defs.IsZero())

Output:

true

func (DITStructureRules) Len 

func (r DITStructureRules) Len() int

Len returns the current integer length of the receiver instance.

func (DITStructureRules) Maps 

func (r DITStructureRules) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the DITStructureRules.Maps method, which produces slices of DefinitionMap instances containing DITStructureRule derived values.

Here, we (quite recklessly) call index three (3) and reference index zero (0) of its `NAME` key to obtain the principal name of the definition.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

defs := mySchema.DITStructureRules().Maps()
fmt.Println(defs[2][`NAME`][0]) // risky, just for simplicity

Output:

dotNotArcStructure

func (DITStructureRules) Push 

func (r DITStructureRules) Push(ds any) error

Push returns an error following an attempt to push a DITStructureRule into the receiver stack instance.

func (DITStructureRules) SetStringer 

func (r DITStructureRules) SetStringer(function ...Stringer) DITStructureRules

SetStringer allows the assignment of an individual Stringer function or method to all DITStructureRule slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the DITStructureRules.SetStringer method to impose a custom Stringer closure upon all stack members.

Naturally the end-user would opt for a more useful stringer, such as one that produces a CSV file containing all AttributeType instances.

To avoid impacting other unit tests, we reset the default stringer via the DITStructureRules.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

defs := mySchema.DITStructureRules()
defs.SetStringer(func() string {
	return "" // make a null stringer
})

output := defs.String()
defs.SetStringer() // return to default

fmt.Println(output)

Output:

func (DITStructureRules) String 

func (r DITStructureRules) String() string

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

func (DITStructureRules) Type 

func (r DITStructureRules) Type() string

Type returns the string literal "dITStructureRules".

Example

This example demonstrates accessing the string type name of a DITStructureRules definition. This is mainly used as a low-cost alternative to type assertion when dealing with Definitions interface type instances. 

var defs DITStructureRules
fmt.Println(defs.Type())

Output:

dITStructureRules

type Definition 

type Definition interface {
	// NumericOID returns the string representation of the ASN.1
	// numeric OID value of the instance.  If the underlying type
	// is a DITStructureRule, no value is returned as this type
	// of definition does not bear an OID.
	NumericOID() string

	// Data returns the underlying user-assigned value present
	// within the receiver instance.
	Data() any

	// Parse returns an error following an attempt read the string
	// input value into the receiver instance.
	//
	// Please note:
	//
	//   - The receiver MUST be initialized and associated with an
	//     appropriate Schema instance
	//   - MatchingRuleUse instances are NOT eligible for this method
	Parse(string) error

	// Name returns the first string NAME value present within
	// the underlying Name stack instance.  A zero
	// string is returned if no names were set, or if the given
	// type instance is LDAPSyntax, which does not bear a name.
	Name() string

	// Names returns the underlying instance of QuotedDescriptorList.
	// If executed upon an instance of LDAPSyntax, an empty instance
	// is returned, as LDAPSyntaxes do not bear names.
	Names() QuotedDescriptorList

	// IsZero returns a Boolean value indicative of nilness
	// with respect to the embedded type instance.
	IsZero() bool

	// Compliant returns a Boolean value indicative of compliance
	// with respect to relevant RFCs, such as RFC 4512.
	Compliant() bool

	// String returns the complete string representation of the
	// underlying definition type per § 4.1.x of RFC 4512.
	String() string

	// Description returns the DESC clause of the underlying
	// definition type, else a zero string if undefined.
	Description() string

	// Schema returns the associated Schema instance with which
	// the receiver instance is associated.
	Schema() Schema

	// IsIdentifiedAs returns a Boolean value indicative of
	// whether the input string represents an identifying
	// value for the underlying definition.
	//
	// Acceptable input values vary based on the underlying
	// type.  See the individual method notes for details.
	//
	// Case-folding of input values is not significant in
	// the matching process, regardless of underlying type.
	IsIdentifiedAs(string) bool

	// Map returns a DefinitionMap instance based upon the
	// the contents and state of the receiver instance.
	Map() DefinitionMap

	// Obsolete returns a Boolean value indicative of the
	// condition of definition obsolescence. Executing this
	// method upon an LDAPSyntax receiver will always return
	// false, as the condition of obsolescence does not
	// apply to this definition type.
	Obsolete() bool

	// Type returns the string literal name for the receiver
	// instance. For example, if the receiver is an LDAPSyntax
	// instance, the return value is "ldapSyntax".
	Type() string

	// Extensions returns the underlying Extension instance value.
	// An empty Extensions instance is returned if no extensions
	// were set.
	Extensions() Extensions
	// contains filtered or unexported methods
}

Definition is an interface type used to allow basic interaction with any of the following instance types:

Not all methods extended through instances of these types are made available through this interface.

type DefinitionMap 

type DefinitionMap map[string][]string

DefinitionMap implements a convenient map-based Definition type. Use of this type is normally indicated in external processing scenarios, such as templating.

Note that, due to the underlying map instance from which this type extends, ordering of clauses (e.g.: NAME vs. DESC) cannot be guaranteed.

func (DefinitionMap) Contains 

func (r DefinitionMap) Contains(id string) bool
Example 
classes := mySchema.ObjectClasses()
fmt.Printf("%t", classes.Maps().Index(2).Contains(`NAME`))

Output:

true

func (DefinitionMap) Get 

func (r DefinitionMap) Get(id string) (val []string)
Example 
classes := mySchema.ObjectClasses()
fmt.Printf("%s", classes.Maps().Index(2).Get(`NAME`)[0])

Output:

subschema

func (DefinitionMap) IsZero 

func (r DefinitionMap) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

Example 
classes := mySchema.ObjectClasses()
fmt.Printf("ObjectClass map zero: %t", classes.Maps().Index(0).IsZero())

Output:

ObjectClass map zero: false

func (DefinitionMap) Keys 

func (r DefinitionMap) Keys() (keys []string)

Keys returns slices of names, each representing a key residing within the receiver instance. Note that the order of keys cannot be guaranteed.

Example 
classes := mySchema.ObjectClasses()
fmt.Printf("ObjectClass map keys: %d", len(classes.Maps().Index(0).Keys()))

Output:

ObjectClass map keys: 8

func (DefinitionMap) Len 

func (r DefinitionMap) Len() int
Example 
classes := mySchema.ObjectClasses()
fmt.Printf("ObjectClass map fields: %d", classes.Maps().Index(0).Len())

Output:

ObjectClass map fields: 8

func (DefinitionMap) Type 

func (r DefinitionMap) Type() (t string)

Type returns the first value assigned to the TYPE key, if defined, else `unknown` is returned.

Example 
classes := mySchema.ObjectClasses()
fmt.Printf("Map type: %s", classes.Maps().Index(0).Type())

Output:

Map type: objectClass

type DefinitionMaps 

type DefinitionMaps []DefinitionMap

DefinitionMaps implements slices of DefinitionMap instances, collectively representing an entire type-specific stack (e.g.: AttributeTypes).

func (DefinitionMaps) Index 

func (r DefinitionMaps) Index(idx int) DefinitionMap
Example 
classes := mySchema.ObjectClasses()
fmt.Printf("%s", classes.Maps().Index(2)[`NUMERICOID`][0])

Output:

2.5.20.1

func (DefinitionMaps) IsZero 

func (r DefinitionMaps) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

Example 
classes := mySchema.ObjectClasses()
fmt.Printf("ObjectClass maps zero: %t", classes.Maps().IsZero())

Output:

ObjectClass maps zero: false

func (DefinitionMaps) Len 

func (r DefinitionMaps) Len() int
Example 
classes := mySchema.ObjectClasses()
fmt.Printf("%d definitions", classes.Maps().Len())

Output:

69 definitions

type Definitions 

type Definitions interface {
	// Len returns the integer length of the receiver instance,
	// indicating the number of definitions residing within.
	Len() int

	// IsZero returns a Boolean value indicative of nilness.
	IsZero() bool

	// Compliant returns a Boolean value indicative of all slices
	// being in compliance with respect to relevant RFCs, such as
	// RFC 4512.
	Compliant() bool

	// Contains returns a Boolean value indicative of whether the
	// specified string value represents the RFC 4512 OID of a
	// Definition qualifier found within the receiver instance.
	Contains(string) bool

	// String returns the string representation of the underlying
	// stack instance.  Note that the manner in which the instance
	// was initialized will influence the resulting output.
	String() string

	// Maps returns slices of DefinitionMap instances, each of which
	// are expressions of actual Definition qualifiers found within
	// the receiver instance.
	Maps() DefinitionMaps

	// Inventory returns an instance of Inventory containing
	// the fundamental numerical and textual identifiers for
	// the contents of any given definition collection. Note
	// that the semantics for representation within instances
	// of this type vary among definition types.
	Inventory() Inventory

	// Type returns the string literal name for the receiver instance.
	// For example, if the receiver is LDAPSyntaxes, "ldapSyntaxes"
	// is the return value.  This is useful in case switching scenarios.
	Type() string

	// Push returns an error instance following an attempt to push
	// an instance of any into the receiver stack instance.  The
	// appropriate instance type depends on the nature of the
	// underlying stack instance.
	Push(any) error
	// contains filtered or unexported methods
}

Definitions is an interface type used to allow basic interaction with any of the following stack types:

Not all methods extended through instances of these types are made available through this interface.

type Extension 

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

Extension is the singular (slice) form of Extensions, and contains the following:

  • One (1) instance of string (XString), declaring the effective "X-" name, AND ...
  • One (1) QuotedStringList stack instance, containing one (1) or more "qdstringlist" values

The ABNF production for "xstring", per § 4.1 of RFC 4512, is as follows: 

xstring	     = "X" HYPHEN 1*( ALPHA / HYPHEN / USCORE )

The ABNF production for "qdstringlist", per § 4.1 of RFC 4512, is as follows: 

qdstringlist = [ qdstring *( SP qdstring ) ]
qdstring     = SQUOTE dstring SQUOTE
dstring      = 1*( QS / QQ / QUTF8 )   ; escaped UTF-8 string

func (Extension) IsZero 

func (r Extension) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (Extension) String 

func (r Extension) String() (s string)

String returns the string representation of the receiver instance.

type Extensions 

type Extensions stackage.Stack

Extensions implements extensions as defined in § 4.1 of RFC 4512: 

extensions = *( SP xstring SP qdstrings )

func NewExtensions 

func NewExtensions(o ...Option) (e Extensions)

NewExtensions initializes and returns a new instance of Extensions.

func (Extensions) Definition 

func (r Extensions) Definition() Definition

Definition returns the Definition instance to which the receiver instance is assigned.

func (Extensions) Exists 

func (r Extensions) Exists(key string) bool

Exists returns a Boolean value indicative of whether the specified key exists within the receiver instance. Case is not significant in the matching process.

func (Extensions) Get 

func (r Extensions) Get(key string) (QuotedStringList, bool)

Get returns QuotedStringList and Boolean instances based on a successful retrieval of values associated with key in the receiver instance. The Boolean value is indicative of a positive match. Case is not significant in the matching process.

func (Extensions) Index 

func (r Extensions) Index(idx int) Extension

Index returns the instance of string found within the receiver stack instance at index N. If no instance is found at the index specified, a zero string instance is returned.

func (Extensions) IsZero 

func (r Extensions) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (Extensions) Keys 

func (r Extensions) Keys() (keys []string)

Keys returns all keys found within the underlying map instance.

func (Extensions) Len 

func (r Extensions) Len() int

Len returns the current integer length of the receiver instance.

func (Extensions) Push 

func (r Extensions) Push(x any) error

func (Extensions) Set 

func (r Extensions) Set(key string, values ...string)

Set assigns the provided key and values instances to the receiver instance, thereby specifying a new extension value as described in RFC 4512.

func (Extensions) String 

func (r Extensions) String() (s string)

String is a stringer method that returns a properly formatted quoted descriptor list based on the number of string values within the receiver instance.

type Inventory 

type Inventory map[string][]string

Inventory is a type alias of map[string][]string, and is used to provide a simple manifest of all members of a collection type, such as LDAPSyntaxes. This can be useful during activities such as templating.

Unlike the DefinitionMap type, this type is only used to manifest the most basic details of a collection of definitions, namely the numerical and textual identifiers present.

Keys represent the numerical identifier for a definition, whether a numeric OID or integer rule ID. In the case of DITStructureRule definitions, the rule ID -- an unsigned integer -- is used. In all other cases, a numeric OID is used.

Values represent the NAME or DESC by which the definition is known.

Note that DESC is only used in the case of LDAPSyntax instances, and NAME is used for all definition types *except* LDAPSyntax.

type LDAPSyntax 

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

LDAPSyntax implements § 4.1.5 of RFC 4512. 

SyntaxDescription = LPAREN WSP
    numericoid                 ; object identifier
    [ SP "DESC" SP qdstring ]  ; description
    extensions WSP RPAREN      ; extensions

From clause 13.12 of ITU-T Rec. X.501: 

SYNTAX-NAME ::= CLASS {
	&desc UTF8String,
	&Type,
	&id OBJECT IDENTIFIER UNIQUE }

WITH SYNTAX {
	DESC &desc
	DIRECTORY SYNTAX &Type
	ID &id }

func NewLDAPSyntax 

func NewLDAPSyntax() LDAPSyntax

NewLDAPSyntax initializes and returns a new instance of LDAPSyntax, ready for manual assembly. This method need not be used when creating new LDAPSyntax instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the LDAPSyntax.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewLDAPSyntax method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of LDAPSyntax instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an LDAPSyntax instance.

Example (Fluent)

This example demonstrates the creation of a new LDAPSyntax instance for manual assembly in a fluent manner.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// prepare new var instance and
// set values in fluent form
def := NewLDAPSyntax().
	SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetDescription(`pulsarFrequencySyntax`).
	SetExtension(`X-NOT-HUMAN-READABLE`, `TRUE`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer() // default closure

fmt.Printf("%s", def)

Output:

( 1.3.6.1.4.1.56521.999.5
    DESC 'pulsarFrequencySyntax'
    X-NOT-HUMAN-READABLE 'TRUE'
    X-ORIGIN 'NOWHERE' )
Example (Piecemeal)

This example demonstrates the creation of a new LDAPSyntax instance for manual assembly piecemeal.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// prepare new var instance and
// set values in fluent form
var def LDAPSyntax = NewLDAPSyntax() // initialization always required
def.SetSchema(mySchema)

def.SetNumericOID(`1.3.6.1.4.1.56521.999.5`)

// ... do other things ...

def.SetExtension(`X-ORIGIN`, `NOWHERE`)
def.SetDescription(`pulsarFrequencySyntax`)
def.SetExtension(`X-NOT-HUMAN-READABLE`, `TRUE`)

// Set default closure if, and only if, the definition
// is deemed to be RFC compliant. In this case, print
// the string representation as our final act.
if def.Compliant() {
	def.SetStringer()
	fmt.Printf("%s", def)
}

Output:

( 1.3.6.1.4.1.56521.999.5
    DESC 'pulsarFrequencySyntax'
    X-ORIGIN 'NOWHERE'
    X-NOT-HUMAN-READABLE 'TRUE' )

func (LDAPSyntax) Compliant 

func (r LDAPSyntax) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.5 of RFC 4512:

  • Numeric OID must be present and valid

func (LDAPSyntax) Data 

func (r LDAPSyntax) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the LDAPSyntax.SetData method.

Example 
syn := mySchema.LDAPSyntaxes().Get(`integer`)

// Let's pretend img ([]uint8) represents
// some JPEG data (e.g.: a diagram)
var img []uint8 = []uint8{0x1, 0x2, 0x3, 0x4}
syn.SetData(img)

got := syn.Data().([]uint8)

fmt.Printf("%T, Len:%d", got, len(got))

Output:

[]uint8, Len:4

func (LDAPSyntax) Description 

func (r LDAPSyntax) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

Example 
integer := mySchema.LDAPSyntaxes().Get(`integer`)
fmt.Println(integer.Description())

Output:

INTEGER

func (LDAPSyntax) Extensions 

func (r LDAPSyntax) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver.

Example

This example demonstrates the means for accessing the underlying instance of Extensions within an LDAPSyntax instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

integer := mySchema.LDAPSyntaxes().Get(`integer`)
fmt.Println(integer.Extensions())

Output:

X-ORIGIN 'RFC4517'

func (LDAPSyntax) IsIdentifiedAs 

func (r LDAPSyntax) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or description of the receiver instance. Case is not significant in the matching process.

Example 
ls := mySchema.LDAPSyntaxes().Get(`integer`)
fmt.Println(ls.IsIdentifiedAs(`1.3.6.1.4.1.1466.115.121.1.27`))

Output:

true

func (LDAPSyntax) IsZero 

func (r LDAPSyntax) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (LDAPSyntax) Map 

func (r LDAPSyntax) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example

This example demonstrates the means of converting an instance of LDAPSyntax into an instance of map[string][]string.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

integer := mySchema.LDAPSyntaxes().Get(`integer`)
fmt.Println(integer.Map()[`NUMERICOID`][0])

Output:

1.3.6.1.4.1.1466.115.121.1.27

func (LDAPSyntax) Name 

func (r LDAPSyntax) Name() string

Name returns an empty string, as LDAPSyntax definitions do not bear names. This method exists only to satisfy Go's interface signature requirements.

func (LDAPSyntax) Names 

func (r LDAPSyntax) Names() QuotedDescriptorList

Names returns an empty instance of QuotedDescriptorList, as names do not apply to LDAPSyntax definitions. This method exists only to satisfy Go's interface signature requirements.

func (LDAPSyntax) NumericOID 

func (r LDAPSyntax) NumericOID() (noid string)

NumericOID returns the string representation of the numeric OID held by the receiver instance.

Example

This example demonstrates accessing the numeric OID of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

integer := mySchema.LDAPSyntaxes().Get(`integer`)
fmt.Println(integer.NumericOID())

Output:

1.3.6.1.4.1.1466.115.121.1.27

func (LDAPSyntax) OID 

func (r LDAPSyntax) OID() string

OID is an alias for the LDAPSyntax.NumericOID method, as LDAPSyntax instances do not allow for the assignment of names. This method exists solely to satisfy Go's interface signature requirements.

Example

This example demonstrates the means for accessing the description OR numeric OID of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

integer := mySchema.LDAPSyntaxes().Get(`integer`)
fmt.Println(integer.OID())

Output:

1.3.6.1.4.1.1466.115.121.1.27

func (LDAPSyntax) Obsolete 

func (r LDAPSyntax) Obsolete() bool

Obsolete only returns a false Boolean value, as definition obsolescence does not apply to LDAPSyntax definitions. This method exists only to satisfy Go's interface signature requirements.

func (LDAPSyntax) Parse 

func (r LDAPSyntax) Parse(raw string) (err error)

Parse returns an error following an attempt to parse raw into the receiver instance.

Note that the receiver MUST possess a Schema reference prior to the execution of this method.

Also note that successful execution of this method does NOT automatically push the receiver into any LDAPSyntaxes stack, nor does it automatically execute the LDAPSyntax.SetStringer method, leaving these tasks to the user. If the automatic handling of these tasks is desired, see the Schema.ParseLDAPSyntax method as an alternative.

Example

This example demonstrates the process of parsing a raw string-based ldapSyntax definition into a proper instance of LDAPSyntax.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

var raw string = `( 1.3.6.1.4.1.56521.999.5 DESC 'pulsarFrequencySyntax' X-NOT-HUMAN-READABLE 'TRUE' X-ORIGIN 'NOWHERE' )`
var def LDAPSyntax = mySchema.NewLDAPSyntax()
if err := def.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

fmt.Println(def.SetStringer())

Output:

( 1.3.6.1.4.1.56521.999.5
    DESC 'pulsarFrequencySyntax'
    X-NOT-HUMAN-READABLE 'TRUE'
    X-ORIGIN 'NOWHERE' )

func (LDAPSyntax) QualifySyntax 

func (r LDAPSyntax) QualifySyntax(value any) (err error)

QualifySyntax returns an error instance following an analysis of the input value using the SyntaxQualifier instance previously assigned to the receiver instance.

If a SyntaxQualifier is not assigned to the receiver instance, the ErrNilSyntaxQualifier error is returned if and when this method is executed. Otherwise, an error is returned based on the custom SyntaxQualifier error handler devised within the user provided closure.

A nil error return always indicates valid input value syntax.

See the LDAPSyntax.SetSyntaxQualifier method for information regarding the assignment of an instance of SyntaxQualifier to the receiver.

func (LDAPSyntax) Replace 

func (r LDAPSyntax) Replace(x LDAPSyntax) LDAPSyntax

Replace overrides the receiver with x. Both must bear an identical numeric OID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the LDAPSyntax envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

Example

This example demonstrates the creation of a new LDAPSyntax instance which will be replaced in memory by another. This change will be recognized in any and all stacks in which the replaced LDAPSyntax resides.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Here is our bad version
orig := mySchema.NewLDAPSyntax().
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetDescription(`freakwency`).
	SetExtension(`X-OERIGIN`, `NOWHERE`).
	SetStringer()

// Here is our good version
good := mySchema.NewLDAPSyntax().
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetDescription(`Frequency`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer()

// Make sure we allow overrides within the
// schema instance.
mySchema.Options().Shift(AllowOverride)

// Swap orig for good, but while preserving
// the same pointer address to keep our
// references valid.
orig.Replace(good)

fmt.Printf("%s", orig)

Output:

( 1.3.6.1.4.1.56521.999.5
    DESC 'Frequency'
    X-ORIGIN 'NOWHERE' )

func (LDAPSyntax) Schema 

func (r LDAPSyntax) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (LDAPSyntax) SetData 

func (r LDAPSyntax) SetData(x any) LDAPSyntax

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the LDAPSyntax.Data method.

This is a fluent method.

Example 
syn := mySchema.LDAPSyntaxes().Get(`integer`)

// Let's pretend img ([]uint8) represents
// some JPEG data (e.g.: a diagram)
var img []uint8 = []uint8{0x1, 0x2, 0x3, 0x4}
syn.SetData(img)

got := syn.Data().([]uint8)

fmt.Printf("%T, Len:%d", got, len(got))

Output:

[]uint8, Len:4

func (LDAPSyntax) SetDescription 

func (r LDAPSyntax) SetDescription(desc string) LDAPSyntax

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

This is a fluent method.

func (LDAPSyntax) SetExtension 

func (r LDAPSyntax) SetExtension(x string, xstrs ...string) LDAPSyntax

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (LDAPSyntax) SetNumericOID 

func (r LDAPSyntax) SetNumericOID(id string) LDAPSyntax

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (LDAPSyntax) SetSchema 

func (r LDAPSyntax) SetSchema(schema Schema) LDAPSyntax

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewLDAPSyntax method.

This is a fluent method.

func (LDAPSyntax) SetStringer 

func (r LDAPSyntax) SetStringer(function ...Stringer) LDAPSyntax

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

func (LDAPSyntax) SetSyntaxQualifier 

func (r LDAPSyntax) SetSyntaxQualifier(function SyntaxQualifier) LDAPSyntax

SetSyntaxQualifier assigns an instance of SyntaxQualifier to the receiver instance. A nil value may be passed to disable syntax checking capabilities.

See the LDAPSyntax.QualifySyntax method for details on making active use of the SyntaxQualifier capabilities.

This is a fluent method.

func (LDAPSyntax) String 

func (r LDAPSyntax) String() (def string)

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

func (LDAPSyntax) Type 

func (r LDAPSyntax) Type() string

Type returns the string literal "ldapSyntax".

type LDAPSyntaxes 

type LDAPSyntaxes collection // RFC 4512 § 4.2.5

func NewLDAPSyntaxes 

func NewLDAPSyntaxes() LDAPSyntaxes

NewLDAPSyntaxes initializes a new LDAPSyntaxes instance.

func (LDAPSyntaxes) Compliant 

func (r LDAPSyntaxes) Compliant() bool

Compliant returns a Boolean value indicative of every LDAPSyntax returning a compliant response from the LDAPSyntax.Compliant method.

Example

This example demonstrates instant compliance checks for all LDAPSyntax instances present within an instance of LDAPSyntaxes. 

syns := mySchema.LDAPSyntaxes()
fmt.Printf("All %d %s are compliant: %t", syns.Len(), syns.Type(), syns.Compliant())

Output:

All 67 ldapSyntaxes are compliant: true

func (LDAPSyntaxes) Contains 

func (r LDAPSyntaxes) Contains(id string) bool

Contains calls MatchingRules.Get to return a Boolean value indicative of a successful, non-zero retrieval of an MatchingRule instance -- matching the provided id -- from within the receiver stack instance.

func (LDAPSyntaxes) Get 

func (r LDAPSyntaxes) Get(id string) LDAPSyntax

Get returns an instance of LDAPSyntax based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of either of the following:

  • the numeric OID of an LDAPSyntax and the provided id
  • the description text -- minus whitespace -- and the provided id

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (LDAPSyntaxes) Index 

func (r LDAPSyntaxes) Index(idx int) LDAPSyntax

Index returns the instance of LDAPSyntax found within the receiver stack instance at index N. If no instance is found at the index specified, a zero LDAPSyntax instance is returned.

Example

This example demonstrates the means of accessing a specific slice value within an instance of LDAPSyntaxes by way of its associated integer index. 

slice := mySchema.LDAPSyntaxes().Index(3)
fmt.Println(slice)

Output:

( 1.3.6.1.4.1.1466.115.121.1.4
    DESC 'Audio'
    X-NOT-HUMAN-READABLE 'TRUE'
    X-ORIGIN 'RFC4517' )

func (LDAPSyntaxes) Inventory 

func (r LDAPSyntaxes) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of LDAPSyntaxes instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example

This example demonstrates the LDAPSyntaxes.Inventory method, which produces an instance of Inventory. The Inventory type is used for accessing an OID to DESC "mapping table".

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

maps := mySchema.LDAPSyntaxes().Inventory()
fmt.Println(maps[`1.3.6.1.4.1.1466.115.121.1.40`][0])

Output:

Octet String

func (LDAPSyntaxes) IsZero 

func (r LDAPSyntaxes) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (LDAPSyntaxes) Len 

func (r LDAPSyntaxes) Len() int

Len returns the current integer length of the receiver instance.

Example

This example demonstrates the means of accessing the integer length of an LDAPSyntaxes stack instance. 

syns := mySchema.LDAPSyntaxes()
fmt.Printf("We have %d %s", syns.Len(), syns.Type())

Output:

We have 67 ldapSyntaxes

func (LDAPSyntaxes) Maps 

func (r LDAPSyntaxes) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the LDAPSyntaxes.Maps method, which produces slices of DefinitionMap instances born of the LDAPSyntaxes stack in which they reside.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

maps := mySchema.LDAPSyntaxes().Maps()
fmt.Println(maps[3][`NUMERICOID`][0])

Output:

1.3.6.1.4.1.1466.115.121.1.4

func (LDAPSyntaxes) Push 

func (r LDAPSyntaxes) Push(ls any) error

Push returns an error following an attempt to push an LDAPSyntax into the receiver stack instance.

func (LDAPSyntaxes) SetStringer 

func (r LDAPSyntaxes) SetStringer(function ...Stringer) LDAPSyntaxes

SetStringer allows the assignment of an individual Stringer function or method to all LDAPSyntax slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

func (LDAPSyntaxes) String 

func (r LDAPSyntaxes) String() string

String returns the string representation of the receiver instance.

func (LDAPSyntaxes) Type 

func (r LDAPSyntaxes) Type() string

Type returns the string literal "ldapSyntaxes".

Example

This example demonstrates use of the LDAPSyntaxes.Type method to determine the type of stack defined within the receiver. This is mainly useful in cases where multiple stacks are being iterated in Definitions interface contexts and is more efficient when compared to manual type assertion. 

syns := mySchema.LDAPSyntaxes()
fmt.Printf("We have %d %s", syns.Len(), syns.Type())

Output:

We have 67 ldapSyntaxes

type Macros 

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

Macros contains user-defined macros for parsing OID-referencing macros used within definitions, such as those found within RFC 2307.

Instances of this type are accessed and managed via the Schema.Macros method.

Users should NOT attempt to instantiate instances of this type manually for any reason.

func (Macros) Keys 

func (r Macros) Keys() []string

Keys returns all numeric OID keys present within the receiver instance.

func (Macros) Resolve 

func (r Macros) Resolve(x string) (y string, found bool)

Resolve returns string y (a name) following an attempt to forward-resolve string x (numeric OID). The Boolean value (found) is returned indicative of a successful resolution attempt.

Case is not significant in the matching process.

func (Macros) ReverseResolve 

func (r Macros) ReverseResolve(y string) (x string, found bool)

ReverseResolve returns string x (a numeric OID) following an attempt to reverse-resolve string y (name). The Boolean value (found) is returned indicative of a successful resolution attempt.

Case is not significant in the matching process.

func (Macros) Set 

func (r Macros) Set(x, y string) Macros

Set assigns value y (macro name) to key x (numeric OID).

This is a fluent method.

type MatchingRule 

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

MatchingRule implements § 4.1.3 of RFC 4512. 

MatchingRuleDescription = LPAREN WSP
    numericoid                 ; object identifier
    [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
    [ SP "DESC" SP qdstring ]  ; description
    [ SP "OBSOLETE" ]          ; not active
    SP "SYNTAX" SP numericoid  ; assertion syntax
    extensions WSP RPAREN      ; extensions

From clause 13.5.2 of ITU-T Rec. X.501: 

MATCHING-RULE ::= CLASS {
	&ParentMatchingRules MATCHING-RULE OPTIONAL,
	&AssertionType OPTIONAL,
	&uniqueMatchIndicator ATTRIBUTE OPTIONAL,
	&ldapSyntax SYNTAX-NAME.&id OPTIONAL,
	&ldapName SEQUENCE SIZE(1..MAX) OF UTF8String OPTIONAL,
	&ldapDesc UTF8String OPTIONAL,
	&id OBJECT IDENTIFIER UNIQUE }

WITH SYNTAX {
	[PARENT &ParentMatchingRules]
	[SYNTAX &AssertionType]
	[UNIQUE-MATCH-INDICATOR &uniqueMatchIndicator]
	[LDAP-SYNTAX &ldapSyntax]
	[LDAP-NAME &ldapName]
	[LDAP-DESC &ldapDesc]
	ID &id }

func NewMatchingRule 

func NewMatchingRule() MatchingRule

NewMatchingRule initializes and returns a new instance of MatchingRule, ready for manual assembly. This method need not be used when creating new MatchingRule instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the MatchingRule.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewMatchingRule method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of MatchingRule instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an MatchingRule instance.

Example

This example demonstrates the creation of a new MatchingRule instance for manual assembly in a fluent manner.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Craft and push an assembled (and fictional)
// LDAPSyntax instance into our schema.
mySchema.LDAPSyntaxes().Push(mySchema.NewLDAPSyntax().
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetDescription(`Frequency`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer())

// set values in fluent form
def := NewMatchingRule().
	SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.88.5`).
	SetName(`frequencyMatch`).
	SetSyntax(`Frequency`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer()

fmt.Printf("%s", def)

Output:

( 1.3.6.1.4.1.56521.999.88.5
    NAME 'frequencyMatch'
    SYNTAX 1.3.6.1.4.1.56521.999.5
    X-ORIGIN 'NOWHERE' )

func (MatchingRule) Assertion 

func (r MatchingRule) Assertion(value1, value2 any) (err error)

Assertion returns an error instance following an analysis of the two input values provided in the context of an assertion match based on the receiver instance.

If an AssertionMatcher is not assigned to the receiver instance, the ErrNilAssertionMatcher error is returned if and when this method is executed. Otherwise, an error is returned based on the custom AssertionMatcher error handler devised within the user provided closure.

A nil error return always indicates valid input value syntax.

See the MatchingRule.SetAssertionMatcher for information regarding the assignment of an instance of AssertionMatcher to the receiver.

func (MatchingRule) Compliant 

func (r MatchingRule) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.3 of RFC 4512:

  • Numeric OID must be present and valid

func (MatchingRule) Data 

func (r MatchingRule) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the MatchingRule.SetData method.

Example

This example demonstrates the means of accessing an arbitrary instance of any type that has been stored within an instance of MatchingRule; this could include documentation or image data, to offer some examples.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mr := mySchema.MatchingRules().Get(`caseIgnoreMatch`)

// Let's pretend img ([]uint8) represents
// some JPEG data (e.g.: a diagram)
var img []uint8 = []uint8{0x1, 0x2, 0x3, 0x4}
mr.SetData(img)

got := mr.Data().([]uint8)

fmt.Printf("%T, Len:%d", got, len(got))

Output:

[]uint8, Len:4

func (MatchingRule) Description 

func (r MatchingRule) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

Example 
cem := mySchema.MatchingRules().Get(`caseExactMatch`)
fmt.Println(cem.Description())

Output:

func (MatchingRule) Extensions 

func (r MatchingRule) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver.

Example 
cim := mySchema.MatchingRules().Get(`caseIgnoreMatch`)
fmt.Println(cim.Extensions())

Output:

X-ORIGIN 'RFC4517'

func (MatchingRule) IsIdentifiedAs 

func (r MatchingRule) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or descriptor of the receiver instance. Case is not significant in the matching process.

Example 
mr := mySchema.MatchingRules().Get(`2.5.13.5`)
fmt.Println(mr.IsIdentifiedAs(`caseexactmatch`))

Output:

true

func (MatchingRule) IsZero 

func (r MatchingRule) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (MatchingRule) Map 

func (r MatchingRule) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example

This example demonstrates the means of converting an instance of MatchingRule into an instance of map[string][]string.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.MatchingRules().Get(`caseIgnoreMatch`)
fmt.Println(def.Map()[`SYNTAX`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.1466.115.121.1.15

func (MatchingRule) Name 

func (r MatchingRule) Name() (id string)

Name returns the string form of the principal name of the receiver instance, if set.

Example

This example demonstrates accessing the principal name of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

im := mySchema.MatchingRules().Get(`2.5.13.14`)
fmt.Println(im.Name())

Output:

integerMatch

func (MatchingRule) Names 

func (r MatchingRule) Names() (names QuotedDescriptorList)

Names returns the underlying instance of QuotedDescriptorList from within the receiver.

func (MatchingRule) NumericOID 

func (r MatchingRule) NumericOID() (noid string)

NumericOID returns the string representation of the numeric OID held by the receiver instance.

Example

This example demonstrates accessing the numeric OID of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

im := mySchema.MatchingRules().Get(`integerMatch`)
fmt.Println(im.NumericOID())

Output:

2.5.13.14

func (MatchingRule) OID 

func (r MatchingRule) OID() (oid string)

OID returns the string representation of an OID -- which is either a numeric OID or descriptor -- that is held by the receiver instance.

Example

This example demonstrates accessing the OID -- whether it is the principal name or numeric OID -- of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

im := mySchema.MatchingRules().Get(`2.5.13.14`)
fmt.Println(im.OID())

Output:

integerMatch

func (MatchingRule) Obsolete 

func (r MatchingRule) Obsolete() (o bool)

Obsolete returns a Boolean value indicative of definition obsolescence.

Example

This example demonstrates the means of declaring a state of obsolescence for an instance of MatchingRule. Once set, it cannot be unset.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.MatchingRules().Get(`caseExactMatch`)
fmt.Println(def.Obsolete())

Output:

false

func (MatchingRule) Parse 

func (r MatchingRule) Parse(raw string) (err error)

Parse returns an error following an attempt to parse raw into the receiver instance.

Note that the receiver MUST possess a Schema reference prior to the execution of this method.

Also note that successful execution of this method does NOT automatically push the receiver into any MatchingRules stack, nor does it automatically execute the MatchingRule.SetStringer method, leaving these tasks to the user. If the automatic handling of these tasks is desired, see the Schema.ParseMatchingRule method as an alternative.

Example

This example demonstrates the process of parsing a raw string-based matchingRule definition into a proper instance of MatchingRule.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Craft and push an assembled (and fictional)
// LDAPSyntax instance into our schema.
mySchema.LDAPSyntaxes().Push(mySchema.NewLDAPSyntax().
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetDescription(`Frequency`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetExtension(`X-NOT-HUMAN-READABLE`, `TRUE`).
	SetStringer())

var raw string = `( 1.3.6.1.4.1.56521.999.88.5 NAME 'frequencyMatch' SYNTAX 1.3.6.1.4.1.56521.999.5 X-ORIGIN 'NOWHERE' )`
var def MatchingRule = mySchema.NewMatchingRule()
if err := def.Parse(raw); err != nil {
	fmt.Println(err)
	return
}

fmt.Println(def.SetStringer())

Output:

( 1.3.6.1.4.1.56521.999.88.5
    NAME 'frequencyMatch'
    SYNTAX 1.3.6.1.4.1.56521.999.5
    X-ORIGIN 'NOWHERE' )

func (MatchingRule) Replace 

func (r MatchingRule) Replace(x MatchingRule) MatchingRule

Replace overrides the receiver with x. Both must bear an identical numeric OID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the MatchingRule envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

Example

This example demonstrates the creation of a new MatchingRule instance which will be replaced in memory by another. This change will be recognized in any and all stacks in which the replaced MatchingRule resides.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Craft and push an assembled (and fictional)
// LDAPSyntax instance into our schema.
mySchema.LDAPSyntaxes().Push(mySchema.NewLDAPSyntax().
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetDescription(`Frequency`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer())

// Here is our bad version
orig := NewMatchingRule().
	SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.88.5`).
	SetName(`freakwencyMatch`).
	SetSyntax(`Frequency`).
	SetExtension(`X-OERIGIN`, `NOWHERE`).
	SetStringer()

// Here is our good version
good := NewMatchingRule().
	SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.88.5`).
	SetName(`frequencyMatch`).
	SetSyntax(`Frequency`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer()

// Swap orig for good, but while preserving
// the same pointer address to keep our
// references valid.
orig.Replace(good)

fmt.Printf("%s", orig)

Output:

( 1.3.6.1.4.1.56521.999.88.5
    NAME 'frequencyMatch'
    SYNTAX 1.3.6.1.4.1.56521.999.5
    X-ORIGIN 'NOWHERE' )

func (MatchingRule) Schema 

func (r MatchingRule) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (MatchingRule) SetAssertionMatcher 

func (r MatchingRule) SetAssertionMatcher(function AssertionMatcher) MatchingRule

SetAssertionMatcher assigns an instance of AssertionMatcher to the receiver instance. A nil value may be passed to assertion matching capabilities.

See the MatchingRule.Assertion method for details on making active use of the AssertionMatcher capabilities.

This is a fluent method.

func (MatchingRule) SetData 

func (r MatchingRule) SetData(x any) MatchingRule

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the MatchingRule.Data method.

This is a fluent method.

Example

This example demonstrates the means of assigning an instance of any type to an instance of MatchingRule. This might include textual documentation, image or diagram content or some other content.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mr := mySchema.MatchingRules().Get(`caseIgnoreMatch`)

// Let's pretend img ([]uint8) represents
// some JPEG data (e.g.: a diagram)
var img []uint8 = []uint8{0x1, 0x2, 0x3, 0x4}
mr.SetData(img)

got := mr.Data().([]uint8)

fmt.Printf("%T, Len:%d", got, len(got))

Output:

[]uint8, Len:4

func (MatchingRule) SetDescription 

func (r MatchingRule) SetDescription(desc string) MatchingRule

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

This is a fluent method.

Example

This example demonstrates assigning and verifying a descriptive text value within a new (and incomplete) MatchingRule instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

var def MatchingRule = NewMatchingRule()
def.SetDescription(`Important Notes`)
fmt.Println(def.Description())

Output:

Important Notes

func (MatchingRule) SetExtension 

func (r MatchingRule) SetExtension(x string, xstrs ...string) MatchingRule

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (MatchingRule) SetName 

func (r MatchingRule) SetName(x ...string) MatchingRule

SetName assigns the provided names to the receiver instance.

Name instances must conform to RFC 4512 descriptor format but need not be quoted.

This is a fluent method.

func (MatchingRule) SetNumericOID 

func (r MatchingRule) SetNumericOID(id string) MatchingRule

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (MatchingRule) SetObsolete 

func (r MatchingRule) SetObsolete() MatchingRule

SetObsolete sets the receiver instance to OBSOLETE if not already set. Note that obsolescence cannot be unset.

This is a fluent method.

Example

This example demonstrates the creation of a new MatchingRule instance for manual assembly as an OBSOLETE instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Craft and push an assembled (and fictional)
// LDAPSyntax instance into our schema.
mySchema.LDAPSyntaxes().Push(mySchema.NewLDAPSyntax().
	SetNumericOID(`1.3.6.1.4.1.56521.999.5`).
	SetDescription(`Frequency`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer())

// set values in fluent form
def := NewMatchingRule().
	SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.88.5`).
	SetName(`frequencyMatch`).
	SetSyntax(`Frequency`).
	SetObsolete().
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer()

fmt.Printf("%s", def)

Output:

( 1.3.6.1.4.1.56521.999.88.5
    NAME 'frequencyMatch'
    OBSOLETE
    SYNTAX 1.3.6.1.4.1.56521.999.5
    X-ORIGIN 'NOWHERE' )

func (MatchingRule) SetSchema 

func (r MatchingRule) SetSchema(schema Schema) MatchingRule

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewMatchingRule method.

This is a fluent method.

func (MatchingRule) SetStringer 

func (r MatchingRule) SetStringer(function ...Stringer) MatchingRule

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

func (MatchingRule) SetSyntax 

func (r MatchingRule) SetSyntax(x any) MatchingRule

SetSyntax assigns x to the receiver instance as an instance of LDAPSyntax.

This is a fluent method.

Example

This example demonstrates the assignment of an LDAPSyntax instance to a MatchingRule.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// Integer syntax
syn := mySchema.LDAPSyntaxes().Get(`integer`)

// set values in fluent form
def := NewMatchingRule().
	SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.81.3`).
	SetName(`salaryMatch`).
	SetSyntax(syn).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer()

fmt.Println(def.Syntax().NumericOID())

Output:

1.3.6.1.4.1.1466.115.121.1.27

func (MatchingRule) String 

func (r MatchingRule) String() (def string)

String is a stringer method that returns the string representation of the receiver instance. A zero-value indicates an invalid receiver, or that the ObjectClass.SetStringer method was not used during MANUAL composition of the receiver.

func (MatchingRule) Syntax 

func (r MatchingRule) Syntax() (syntax LDAPSyntax)

Syntax returns the LDAPSyntax reference held by the receiver instance.

func (MatchingRule) Type 

func (r MatchingRule) Type() string

Type returns the string literal "matchingRule".

type MatchingRuleUse 

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

MatchingRuleUse implements § 4.1.4 of RFC 4512. 

MatchingRuleUseDescription = LPAREN WSP
    numericoid                 ; object identifier
    [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
    [ SP "DESC" SP qdstring ]  ; description
    [ SP "OBSOLETE" ]          ; not active
    SP "APPLIES" SP oids       ; attribute types
    extensions WSP RPAREN      ; extensions

From clause 13.6.2 of ITU-T Rec. X.501: 

MAPPING-BASED-MATCHING
{SelectedBy, BOOLEAN:combinable, MappingResult, OBJECT IDENTIFIER:matchingRule} ::= CLASS {
	&selectBy SelectedBy OPTIONAL,
	&ApplicableTo ATTRIBUTE,
	&subtypesIncluded BOOLEAN DEFAULT TRUE,
	&combinable BOOLEAN(combinable),
	&mappingResults MappingResult OPTIONAL,
	&userControl BOOLEAN DEFAULT FALSE,
	&exclusive BOOLEAN DEFAULT TRUE,
	&matching-rule MATCHING-RULE.&id(matchingRule),
	&id OBJECT IDENTIFIER UNIQUE }

WITH SYNTAX {
	[SELECT BY &selectBy]
	APPLICABLE TO &ApplicableTo
	[SUBTYPES INCLUDED &subtypesIncluded]
	COMBINABLE &combinable
	[MAPPING RESULTS &mappingResults]
	[USER CONTROL &userControl]
	[EXCLUSIVE &exclusive]
	MATCHING RULE &matching-rule
	ID &id }

func NewMatchingRuleUse 

func NewMatchingRuleUse() MatchingRuleUse

NewMatchingRuleUse initializes and returns a new instance of MatchingRuleUse, ready for manual assembly. This method need not be used when creating new MatchingRuleUse instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the MatchingRuleUse.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewMatchingRuleUse method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of MatchingRuleUse instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an MatchingRuleUse instance.

Example

This example demonstrates manual assembly of a new MatchingRuleUse instance. Note this is provided for demonstration purposes only and in context does not perform anything useful.

In general it is not necessary for end-users to manually define this kind of instance. Instances of this type are normally created by automated processes when new AttributeType definitions are created or introduced which make use of a given MatchingRule instance. 

var def MatchingRuleUse = NewMatchingRuleUse().SetSchema(mySchema)

def.SetNumericOID(`2.5.13.16`).
	SetName(`fakeBitStringMatch`).
	SetExtension(`X-ORIGIN`, `NOWHERE`)

for _, apl := range []AttributeType{
	mySchema.AttributeTypes().Get(`cn`),
	mySchema.AttributeTypes().Get(`sn`),
	mySchema.AttributeTypes().Get(`l`),
} {
	def.SetApplies(apl)
}

// We're done and ready, set the stringer
def.SetStringer()

fmt.Printf("%s", def)

Output:

( 2.5.13.16
    NAME 'fakeBitStringMatch'
    APPLIES ( cn
            $ sn
            $ l )
    X-ORIGIN 'NOWHERE' )

func (MatchingRuleUse) Applies 

func (r MatchingRuleUse) Applies() (aa AttributeTypes)

Applies returns an AttributeTypes instance containing pointer references to all AttributeType instances to which the receiver applies.

func (MatchingRuleUse) Compliant 

func (r MatchingRuleUse) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.4 of RFC 4512:

  • Numeric OID must be present and valid
  • Numeric OID must correlate to a previously registered MatchingRule
Example

This example demonstrates calling the 3rd index of the MatchingRuleUses stack of our Schema and performing a compliancy checking on the slice.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mu := mySchema.MatchingRuleUses().Index(3)
fmt.Println(mu.Compliant())

Output:

true

func (MatchingRuleUse) Data 

func (r MatchingRuleUse) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the MatchingRuleUse.SetData method.

Example 
mr := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)

// Let's pretend img ([]uint8) represents
// some JPEG data (e.g.: a diagram)
var img []uint8 = []uint8{0x1, 0x2, 0x3, 0x4}
mr.SetData(img)

got := mr.Data().([]uint8)

fmt.Printf("%T, Len:%d", got, len(got))

Output:

[]uint8, Len:4

func (MatchingRuleUse) Description 

func (r MatchingRuleUse) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

Example

This example demonstrates accessing the description clause within the receiver instance. Most MatchingRuleUse instances do not have any descriptive text set, thus like others this example produces no value.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

cim := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)
fmt.Println(cim.Description())

Output:

func (MatchingRuleUse) Extensions 

func (r MatchingRuleUse) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver.

Example

This example demonstrates a means of accessing the underlying Extensions stack instance within the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

cim := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)
fmt.Println(cim.Extensions())

Output:

X-ORIGIN 'RFC4517'

func (MatchingRuleUse) IsIdentifiedAs 

func (r MatchingRuleUse) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or descriptor of the receiver instance. Case is not significant in the matching process.

func (MatchingRuleUse) IsZero 

func (r MatchingRuleUse) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (MatchingRuleUse) Map 

func (r MatchingRuleUse) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example

This example demonstrates the means of transferring an MatchingRuleUse into an instance of DefinitionMap.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

def := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)
fmt.Println(def.Map()[`NUMERICOID`][0]) // risky, just for simplicity

Output:

2.5.13.2

func (MatchingRuleUse) Name 

func (r MatchingRuleUse) Name() (id string)

Name returns the string form of the principal name of the receiver instance, if set.

Example

This example demonstrates accessing the principal name of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

im := mySchema.MatchingRuleUses().Get(`2.5.13.14`)
fmt.Println(im.Name())

Output:

integerMatch

func (MatchingRuleUse) Names 

func (r MatchingRuleUse) Names() (names QuotedDescriptorList)

Names returns the underlying instance of QuotedDescriptorList from within the receiver.

Example 
cim := mySchema.MatchingRuleUses().Get(`2.5.13.2`)
fmt.Println(cim.Names())

Output:

'caseIgnoreMatch'

func (MatchingRuleUse) NumericOID 

func (r MatchingRuleUse) NumericOID() (noid string)

NumericOID returns the string representation of the numeric OID held by the receiver instance.

Example

This example demonstrates accessing the numeric OID of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

im := mySchema.MatchingRuleUses().Get(`integerMatch`)
fmt.Println(im.NumericOID())

Output:

2.5.13.14

func (MatchingRuleUse) OID 

func (r MatchingRuleUse) OID() (oid string)

OID returns the string representation of an OID -- which is either a numeric OID or descriptor -- that refers to the MatchingRule upon which the receiver instance is based.

Example

This example demonstrates accessing the OID -- whether it is the principal name or numeric OID -- of the receiver instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

im := mySchema.MatchingRuleUses().Get(`2.5.13.14`)
fmt.Println(im.OID())

Output:

integerMatch

func (MatchingRuleUse) Obsolete 

func (r MatchingRuleUse) Obsolete() (o bool)

Obsolete returns a Boolean value indicative of definition obsolescence.

Example 
def := mySchema.MatchingRuleUses().Get(`caseExactMatch`)
fmt.Println(def.Obsolete())

Output:

false

func (MatchingRuleUse) Parse 

func (r MatchingRuleUse) Parse(raw string) error

Parse always returns an error, as parsing does not apply to MatchingRuleUse instances, as they are meant to be dynamically generated -- not parsed.

See the Schema.UpdateMatchingRuleUses method for a means of refreshing the current Schema.MatchingRuleUses stack based upon the AttributeType instances present within the Schema instance at runtime.

Example

This example demonstrates the futility of attempting to parse a raw string-based matchingRuleUse definition into a proper instance of MatchingRuleUse, as these definitions are auto-generated by the DSA governed by the relevant schema; not parsed from input. 

var raw string = `( 2.5.13.21
		NAME 'tellyMatch'
		APPLIES sponsorTelephoneNumber
		X-ORIGIN 'NOWHERE' )`

var def MatchingRuleUse
fmt.Println(def.Parse(raw))

Output:

Parsing is not applicable to a MatchingRuleUse

func (MatchingRuleUse) Replace 

func (r MatchingRuleUse) Replace(x MatchingRuleUse) MatchingRuleUse

Replace overrides the receiver with x. Both must bear an identical numeric OID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the MatchingRuleUse envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

func (MatchingRuleUse) Schema 

func (r MatchingRuleUse) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (MatchingRuleUse) SetApplies 

func (r MatchingRuleUse) SetApplies(m ...any) MatchingRuleUse

SetApplies assigns the provided input values as applied AttributeType instances advertised through the receiver instance.

This is a fluent method.

func (MatchingRuleUse) SetData 

func (r MatchingRuleUse) SetData(x any) MatchingRuleUse

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the MatchingRuleUse.Data method.

This is a fluent method.

Example 
mr := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)

// Let's pretend img ([]uint8) represents
// some JPEG data (e.g.: a diagram)
var img []uint8 = []uint8{0x1, 0x2, 0x3, 0x4}
mr.SetData(img)

got := mr.Data().([]uint8)

fmt.Printf("%T, Len:%d", got, len(got))

Output:

[]uint8, Len:4

func (MatchingRuleUse) SetDescription 

func (r MatchingRuleUse) SetDescription(desc string) MatchingRuleUse

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

Example 
cim := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)
cim.SetDescription("Caseless string match")
fmt.Println(cim.Description())

Output:

Caseless string match

func (MatchingRuleUse) SetExtension 

func (r MatchingRuleUse) SetExtension(x string, xstrs ...string) MatchingRuleUse

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (MatchingRuleUse) SetName 

func (r MatchingRuleUse) SetName(x ...string) MatchingRuleUse

SetName assigns the provided names to the receiver instance.

Name instances must conform to RFC 4512 descriptor format but need not be quoted.

This is a fluent method.

func (MatchingRuleUse) SetNumericOID 

func (r MatchingRuleUse) SetNumericOID(id string) MatchingRuleUse

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The input id relates to a known MatchingRule instance within the associated Schema
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (MatchingRuleUse) SetObsolete 

func (r MatchingRuleUse) SetObsolete() MatchingRuleUse

SetObsolete sets the receiver instance to OBSOLETE if not already set.

Obsolescence cannot be unset.

This is a fluent method.

Example

This example demonstrates the creation of a new MatchingRuleUse instance for manual assembly as an OBSOLETE instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

var def MatchingRuleUse = NewMatchingRuleUse()
def.SetObsolete()
fmt.Printf("Is obsolete: %t", def.Obsolete())

Output:

Is obsolete: true

func (MatchingRuleUse) SetSchema 

func (r MatchingRuleUse) SetSchema(schema Schema) MatchingRuleUse

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewMatchingRuleUse method.

This is a fluent method.

func (MatchingRuleUse) SetStringer 

func (r MatchingRuleUse) SetStringer(function ...Stringer) MatchingRuleUse

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the MatchingRuleUse.SetStringer method to impose a custom Stringer closure over the default instance.

Naturally the end-user would opt for a more useful stringer, such as one that produces singular CSV rows per instance.

To avoid impacting other unit tests, we reset the default stringer via the MatchingRuleUse.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

cim := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)
cim.SetStringer(func() string {
	return "This useless message brought to you by a dumb stringer"
})

msg := fmt.Sprintln(cim)
cim.SetStringer() // return it to its previous state if need be ...

fmt.Printf("Original: %s\nOld: %s", cim, msg)

Output:

Original: ( 2.5.13.2
    NAME 'caseIgnoreMatch'
    APPLIES ( carLicense
            $ departmentNumber
            $ displayName
            $ employeeNumber
            $ employeeType
            $ preferredLanguage
            $ name
            $ businessCategory
            $ description
            $ destinationIndicator
            $ dnQualifier
            $ houseIdentifier
            $ physicalDeliveryOfficeName
            $ postalCode
            $ postOfficeBox
            $ serialNumber
            $ street
            $ uid
            $ buildingName
            $ co
            $ documentIdentifier
            $ documentLocation
            $ documentPublisher
            $ documentTitle
            $ documentVersion
            $ drink
            $ host
            $ info
            $ organizationalStatus
            $ personalTitle
            $ roomNumber
            $ uniqueIdentifier
            $ userClass
            $ aSN1Notation )
    X-ORIGIN 'RFC4517' )
Old: This useless message brought to you by a dumb stringer

func (MatchingRuleUse) String 

func (r MatchingRuleUse) String() (def string)

String is a stringer method that returns the string representation of the receiver instance. A zero-value indicates an invalid receiver, or that the ObjectClass.SetStringer method was not used during MANUAL composition of the receiver.

Example

This example demonstrates the string representation process for an instance of MatchingRuleUse.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mu := mySchema.MatchingRuleUses().Get(`2.5.13.2`)
fmt.Println(mu)

Output:

( 2.5.13.2
    NAME 'caseIgnoreMatch'
    APPLIES ( carLicense
            $ departmentNumber
            $ displayName
            $ employeeNumber
            $ employeeType
            $ preferredLanguage
            $ name
            $ businessCategory
            $ description
            $ destinationIndicator
            $ dnQualifier
            $ houseIdentifier
            $ physicalDeliveryOfficeName
            $ postalCode
            $ postOfficeBox
            $ serialNumber
            $ street
            $ uid
            $ buildingName
            $ co
            $ documentIdentifier
            $ documentLocation
            $ documentPublisher
            $ documentTitle
            $ documentVersion
            $ drink
            $ host
            $ info
            $ organizationalStatus
            $ personalTitle
            $ roomNumber
            $ uniqueIdentifier
            $ userClass
            $ aSN1Notation )
    X-ORIGIN 'RFC4517' )

func (MatchingRuleUse) Type 

func (r MatchingRuleUse) Type() string

Type returns the string literal "matchingRuleUse".

type MatchingRuleUses 

type MatchingRuleUses collection // RFC 4512 § 4.2.4

func NewMatchingRuleUses 

func NewMatchingRuleUses() MatchingRuleUses

NewMatchingRuleUses initializes a new MatchingRuleUses instance.

func (MatchingRuleUses) Compliant 

func (r MatchingRuleUses) Compliant() bool

Compliant returns a Boolean value indicative of every MatchingRuleUse returning a compliant response from the MatchingRuleUse.Compliant method.

Example

This example demonstrates instant compliance checks for all MatchingRuleUse instances present within an instance of MatchingRuleUses.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mus := mySchema.MatchingRuleUses()
fmt.Printf("All %d %s are compliant: %t", mus.Len(), mus.Type(), mus.Compliant())

Output:

All 32 matchingRuleUses are compliant: true

func (MatchingRuleUses) Contains 

func (r MatchingRuleUses) Contains(id string) bool

Contains calls MatchingRuleUses.Get to return a Boolean value indicative of a successful, non-zero retrieval of an MatchingRuleUse instance -- matching the provided id -- from within the receiver stack instance.

Example

This example demonstrates a means of checking whether a particular instance of MatchingRuleUse is present within an instance of MatchingRuleUses.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mus := mySchema.MatchingRuleUses()
fmt.Println(mus.Contains(`caseIgnoreMatch`)) // or "2.5.13.2"

Output:

true

func (MatchingRuleUses) Get 

func (r MatchingRuleUses) Get(id string) MatchingRuleUse

Get returns an instance of MatchingRuleUse based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of the principal identifier of an MatchingRuleUse and the provided id.

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (MatchingRuleUses) Index 

func (r MatchingRuleUses) Index(idx int) MatchingRuleUse

Index returns the instance of MatchingRuleUse found within the receiver stack instance at index N. If no instance is found at the index specified, a zero MatchingRuleUse instance is returned.

Example

This example demonstrates the means of accessing a specific slice value within an instance of MatchingRuleUses by way of its associated integer index.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

slice := mySchema.MatchingRuleUses().Index(3)
fmt.Println(slice)

Output:

( 2.5.13.28
    NAME 'generalizedTimeOrderingMatch'
    APPLIES ( createTimestamp
            $ modifyTimestamp
            $ subschemaTimestamp
            $ registrationCreated
            $ registrationModified
            $ currentAuthorityStartTimestamp
            $ firstAuthorityStartTimestamp
            $ firstAuthorityEndTimestamp
            $ sponsorStartTimestamp
            $ sponsorEndTimestamp )
    X-ORIGIN 'RFC4517' )

func (MatchingRuleUses) Inventory 

func (r MatchingRuleUses) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of MatchingRuleUse instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example

This example demonstrates the creation of an Inventory instance based upon the current contents of an MatchingRuleUses stack instance. Use of an Inventory instance is convenient in cases where a receiver of schema information may not be able to directly receive working stack instances and requires a more portable and generalized type.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

at := mySchema.MatchingRuleUses().Inventory()
fmt.Println(at[`2.5.13.2`][0])

Output:

caseIgnoreMatch

func (MatchingRuleUses) IsZero 

func (r MatchingRuleUses) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

Example 
var mus MatchingRuleUses
fmt.Println(mus.IsZero())

Output:

true

func (MatchingRuleUses) Len 

func (r MatchingRuleUses) Len() int

Len returns the current integer length of the receiver instance.

Example

This example demonstrates the means of accessing the integer length of an MatchingRuleUses stack instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mrs := mySchema.MatchingRuleUses()
fmt.Printf("We have %d %s", mrs.Len(), mrs.Type())

Output:

We have 32 matchingRuleUses

func (MatchingRuleUses) Maps 

func (r MatchingRuleUses) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the MatchingRuleUses.Maps method, which produces slices of DefinitionMap instances containing MatchingRuleUse derived values

Here, we (quite recklessly) call index three (3) and reference index zero (0) of its `SYNTAX` key to obtain the relevant LDAPSyntax OID string value.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

defs := mySchema.MatchingRuleUses().Maps()
fmt.Println(defs[3][`APPLIES`][0]) // risky, just for simplicity

Output:

createTimestamp

func (MatchingRuleUses) Push 

func (r MatchingRuleUses) Push(mu any) error

Push returns an error following an attempt to push a MatchingRuleUse instance into the receiver instance.

Example

This example demonstrates the act of pushing, or appending, a new instance of MatchingRuleUse into a new MatchingRuleUses stack instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mu := mySchema.MatchingRuleUses().Get(`caseIgnoreMatch`)
myMus := NewMatchingRuleUses()
myMus.Push(mu)
fmt.Println(myMus.Len())

Output:

1

func (MatchingRuleUses) SetStringer 

func (r MatchingRuleUses) SetStringer(function ...Stringer) MatchingRuleUses

SetStringer allows the assignment of an individual Stringer function or method to all MatchingRuleUse slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the MatchingRuleUses.SetStringer method to impose a custom Stringer closure upon all stack members.

Naturally the end-user would opt for a more useful stringer, such as one that produces a CSV file containing all MatchingRuleUse instances.

To avoid impacting other unit tests, we reset the default stringer via the MatchingRuleUses.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mrs := mySchema.MatchingRuleUses()
mrs.SetStringer(func() string {
	return "" // make a null stringer
})

output := mrs.String()
mrs.SetStringer() // return to default

fmt.Println(output)

Output:

func (MatchingRuleUses) String 

func (r MatchingRuleUses) String() string

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

func (MatchingRuleUses) Type 

func (r MatchingRuleUses) Type() string

Type returns the string literal "matchingRuleUses".

Example

This example demonstrates use of the MatchingRuleUses.Type method to determine the type of stack defined within the receiver. This is mainly useful in cases where multiple stacks are being iterated in Definitions interface contexts and is more efficient when compared to manual type assertion.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mrs := mySchema.MatchingRuleUses()
fmt.Printf("We have %d %s", mrs.Len(), mrs.Type())

Output:

We have 32 matchingRuleUses

type MatchingRules 

type MatchingRules collection // RFC 4512 § 4.2.3

func NewMatchingRules 

func NewMatchingRules() MatchingRules

NewMatchingRules initializes a new MatchingRules instance.

func (MatchingRules) Compliant 

func (r MatchingRules) Compliant() bool

Compliant returns a Boolean value indicative of every MatchingRule returning a compliant response from the MatchingRule.Compliant method.

Example

This example demonstrates instant compliance checks for all MatchingRule instances present within an instance of MatchingRules.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mrs := mySchema.MatchingRules()
fmt.Printf("All %d %s are compliant: %t", mrs.Len(), mrs.Type(), mrs.Compliant())

Output:

All 44 matchingRules are compliant: true

func (MatchingRules) Contains 

func (r MatchingRules) Contains(id string) bool

Contains calls MatchingRules.Get to return a Boolean value indicative of a successful, non-zero retrieval of an MatchingRule instance -- matching the provided id -- from within the receiver stack instance.

func (MatchingRules) Get 

func (r MatchingRules) Get(id string) MatchingRule

Get returns an instance of MatchingRule based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of the principal identifier of an MatchingRule and the provided id.

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (MatchingRules) Index 

func (r MatchingRules) Index(idx int) MatchingRule

Index returns the instance of MatchingRule found within the receiver stack instance at index N. If no instance is found at the index specified, a zero MatchingRule instance is returned.

Example

This example demonstrates the means of accessing a specific slice value within an instance of MatchingRules by way of its associated integer index.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

slice := mySchema.MatchingRules().Index(3)
fmt.Println(slice)

Output:

( 2.5.13.2
    NAME 'caseIgnoreMatch'
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
    X-ORIGIN 'RFC4517' )

func (MatchingRules) Inventory 

func (r MatchingRules) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of MatchingRule instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example

This example demonstrates the MatchingRules.Inventory method, which produces an instance of Inventory. The Inventory type is used for accessing an OID to NAME "mapping table".

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

inv := mySchema.MatchingRules().Inventory()
fmt.Println(inv[`2.5.13.13`][0]) // risky, just for simplicity

Output:

booleanMatch

func (MatchingRules) IsZero 

func (r MatchingRules) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (MatchingRules) Len 

func (r MatchingRules) Len() int

Len returns the current integer length of the receiver instance.

Example

This example demonstrates the means of accessing the integer length of an MatchingRules stack instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mrs := mySchema.MatchingRules()
fmt.Printf("We have %d %s", mrs.Len(), mrs.Type())

Output:

We have 44 matchingRules

func (MatchingRules) Maps 

func (r MatchingRules) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the MatchingRules.Maps method, which produces slices of DefinitionMap instances born of the MatchingRules stack in which they reside. We (quite recklessly) call index three (3) and reference index zero (0) of its `SYNTAX` key to obtain the relevant LDAPSyntax OID string value.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

defs := mySchema.MatchingRules().Maps()
fmt.Println(defs[3][`SYNTAX`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.1466.115.121.1.15

func (MatchingRules) Push 

func (r MatchingRules) Push(mr any) error

Push returns an error following an attempt to push a MatchingRule into the receiver stack instance.

func (MatchingRules) SetStringer 

func (r MatchingRules) SetStringer(function ...Stringer) MatchingRules

SetStringer allows the assignment of an individual Stringer function or method to all MatchingRule slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

func (MatchingRules) String 

func (r MatchingRules) String() string

String returns the string representation of the receiver instance.

func (MatchingRules) Type 

func (r MatchingRules) Type() string

Type returns the string literal "matchingRules".

Example

This example demonstrates use of the MatchingRules.Type method to determine the type of stack defined within the receiver. This is mainly useful in cases where multiple stacks are being iterated in Definitions interface contexts and is more efficient when compared to manual type assertion.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

mrs := mySchema.MatchingRules()
fmt.Printf("We have %d %s", mrs.Len(), mrs.Type())

Output:

We have 44 matchingRules

type NameForm 

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

NameForm implements § 4.1.7.2 of RFC 4512. 

NameFormDescription = LPAREN WSP
    numericoid                 ; object identifier
    [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
    [ SP "DESC" SP qdstring ]  ; description
    [ SP "OBSOLETE" ]          ; not active
    SP "OC" SP oid             ; structural object class
    SP "MUST" SP oids          ; attribute types
    [ SP "MAY" SP oids ]       ; attribute types
    extensions WSP RPAREN      ; extensions

From clause 13.7.3 of ITU-T Rec. X.501: 

NAME-FORM ::= CLASS {
	&namedObjectClass OBJECT-CLASS,
	&MandatoryAttributes ATTRIBUTE,
	&OptionalAttributes ATTRIBUTE OPTIONAL,
	&ldapName SEQUENCE SIZE(1..MAX) OF UTF8String OPTIONAL,
	&ldapDesc UTF8String OPTIONAL,
	&id OBJECT IDENTIFIER UNIQUE }

WITH SYNTAX {
	NAMES &namedObjectClass
	WITH ATTRIBUTES &MandatoryAttributes
	[AND OPTIONALLY &OptionalAttributes]
	[LDAP-NAME &ldapName]
	[LDAP-DESC &ldapDesc]
	ID &id }

func NewNameForm 

func NewNameForm() NameForm

NewNameForm initializes and returns a new instance of NameForm, ready for manual assembly. This method need not be used when creating new NameForm instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the NameForm.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewNameForm method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of NameForm instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an NameForm instance.

func (NameForm) Compliant 

func (r NameForm) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.7.2 of RFC 4512:

  • Numeric OID must be present and valid
Example

This example demonstrates a compliancy check of the "account" ObjectClass.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

dnaf := mySchema.NameForms().Get(`dotNotationArcForm`)
fmt.Println(dnaf.Compliant())

Output:

true

func (NameForm) Data 

func (r NameForm) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the NameForm.SetData method.

func (NameForm) Description 

func (r NameForm) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

func (NameForm) Extensions 

func (r NameForm) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver instance.

Additions to the Extensions instance returned may be effected using the Extensions.Set method. Existing Extensions cannot be altered.

func (NameForm) IsIdentifiedAs 

func (r NameForm) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or descriptor of the receiver instance. Case is not significant in the matching process.

Example 
nf := mySchema.NameForms().Get(`nRootArcForm`)
fmt.Println(nf.IsIdentifiedAs(`1.3.6.1.4.1.56521.101.2.7.1`))

Output:

true

func (NameForm) IsZero 

func (r NameForm) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (NameForm) Map 

func (r NameForm) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example 
def := mySchema.NameForms().Get(`nRootArcForm`)
fmt.Println(def.Map()[`NUMERICOID`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.56521.101.2.7.1

func (NameForm) May 

func (r NameForm) May() (may AttributeTypes)

May returns an AttributeTypes containing zero (0) or more allowed AttributeType definitions for use with this class.

Additions to the AttributeTypes instance returned may be effected using the AttributeTypes.Push method. Existing AttributeType instances cannot be removed.

func (NameForm) Must 

func (r NameForm) Must() (must AttributeTypes)

Must returns an AttributeTypes containing zero (0) or more required AttributeType definitions for use with this class.

Additions to the AttributeTypes instance returned may be effected using the AttributeTypes.Push method. Existing AttributeType instances cannot be removed.

func (NameForm) Name 

func (r NameForm) Name() (id string)

Name returns the string form of the principal name of the receiver instance, if set.

func (NameForm) Names 

func (r NameForm) Names() (names QuotedDescriptorList)

Names returns the underlying instance of QuotedDescriptorList from within the receiver instance.

func (NameForm) NumericOID 

func (r NameForm) NumericOID() (noid string)

NumericOID returns the string representation of the numeric OID held by the receiver instance.

func (NameForm) OC 

func (r NameForm) OC() ObjectClass

OC returns the STRUCTURAL ObjectClass specified within the receiver instance.

func (NameForm) OID 

func (r NameForm) OID() (oid string)

OID returns the string representation of the OID -- whether numeric or descriptor -- held by the receiver instance. Note that a principal name is requested first and, if not found, the numeric OID is returned as a fallback. The return value should NEVER be zero for a valid receiver.

func (NameForm) Obsolete 

func (r NameForm) Obsolete() (o bool)

Obsolete returns a Boolean value indicative of definition obsolescence.

func (NameForm) Parse 

func (r NameForm) Parse(raw string) (err error)

Parse returns an error following an attempt to parse raw into the receiver instance.

Note that the receiver MUST possess a Schema reference prior to the execution of this method.

Also note that successful execution of this method does NOT automatically push the receiver into any NameForms stack, nor does it automatically execute the NameForm.SetStringer method, leaving these tasks to the user. If the automatic handling of these tasks is desired, see the Schema.ParseNameForm method as an alternative.

Example

This example demonstrates a means of parsing a raw definition into a new instance of NameForm.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

nf := mySchema.NewNameForm()

// feed the parser a subtly bogus definition ...
err := nf.Parse(`( 1.3.6.1.4.1.56521.999.14.56.1
                NAME 'fakeForm'
                DESC 'It\'s not real'
		OC device
		MUST cn
                X-ORIGIN 'YOUR FACE'
        )`)

if err != nil {
	fmt.Println(err)
	return
}

fmt.Println(nf.Must())

Output:

cn

func (NameForm) Replace 

func (r NameForm) Replace(x NameForm) NameForm

Replace overrides the receiver with x. Both must bear an identical numeric OID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the NameForm envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

Example

This example demonstrates a common (and most unfortunate) modification to an OFFICIAL ObjectClass definition -- "groupOfNames", found within Section 3.5 of RFC 4519.

The design of this particular class is widely considered to be inconvenient due to its mandate that at least one (1) instance of the "member" AttributeType (from Section 2.17 of RFC 4519).

As such, this has forced many LDAP architects to literally modify this ObjectClass definition within the given directory schema, moving the "member" AttributeType from the MUST clause to the MAY clause.

For reasons of oversight, we've added the RFC of origin as an X-ORIGIN extension, and a custom extension X-WARNING to remind users and admin alike that we've resorted to this risky trick. 

// Obtain the groupOfNames (gon) ObjectClass so
// we can copy some of its values.
gon := mySchema.NameForms().Get(`nRootArcForm`)

// Craft a near identical groupOfNames instance,
// save for the one change we intend to make.
ngon := mySchema.NewNameForm().
	SetName(gon.Name()).
	SetDescription("new root arc name form for a number form RDN").
	SetNumericOID(gon.NumericOID()).
	SetOC(`rootArc`).
	SetMust(`n`).
	SetExtension(`X-ORIGIN`, `draft-coretta-oiddir-schema`).
	SetExtension(`X-WARNING`, `MODIFIED`).
	SetStringer()

// Replace gon with ngon, while preserving its pointer
// address so that references within stacks do not fail.
gon.Replace(ngon)

// call the new one (just to be sure)
fmt.Println(mySchema.NameForms().Get(`nRootArcForm`))

Output:

( 1.3.6.1.4.1.56521.101.2.7.1
    NAME 'nRootArcForm'
    DESC 'new root arc name form for a number form RDN'
    OC rootArc
    MUST n
    X-ORIGIN 'draft-coretta-oiddir-schema'
    X-WARNING 'MODIFIED' )

func (NameForm) Schema 

func (r NameForm) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (NameForm) SetData 

func (r NameForm) SetData(x any) NameForm

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the NameForm.Data method.

This is a fluent method.

Example

This example demonstrates the assignment of arbitrary data to an instance of NameForm.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// The value can be any type, but we'll
// use a string for simplicity.
documentation := `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`

// Obtain the target attribute type to bear
// the assigned value.
nform := mySchema.NameForms().Get(`nArcForm`)

// Set it.
nform.SetData(documentation)

// Get it and compare to the original.
equal := documentation == nform.Data().(string)

fmt.Printf("Values are equal: %t", equal)

Output:

Values are equal: true

func (NameForm) SetDescription 

func (r NameForm) SetDescription(desc string) NameForm

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

func (NameForm) SetExtension 

func (r NameForm) SetExtension(x string, xstrs ...string) NameForm

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (NameForm) SetMay 

func (r NameForm) SetMay(m ...any) NameForm

SetMay assigns the provided input AttributeType instance(s) to the receiver's MAY clause.

This is a fluent method.

func (NameForm) SetMust 

func (r NameForm) SetMust(m ...any) NameForm

SetMust assigns the provided input AttributeType instance(s) to the receiver's MUST clause.

This is a fluent method.

func (NameForm) SetName 

func (r NameForm) SetName(name ...string) NameForm

SetName allows the manual assignment of one (1) or more RFC 4512-compliant descriptor values by which the receiver instance is to be known. This will append to -- not replace -- any preexisting names.

This is a fluent method.

func (NameForm) SetNumericOID 

func (r NameForm) SetNumericOID(id string) NameForm

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (NameForm) SetOC 

func (r NameForm) SetOC(x any) NameForm

SetOC sets the structural class of the receiver to the value provided. Valid input types are string, to represent an RFC 4512 OID residing in the underlying Schema instance, or an actual structural ObjectClass instance already obtained or crafted.

This is a fluent method.

func (NameForm) SetObsolete 

func (r NameForm) SetObsolete() NameForm

SetObsolete will declare the receiver instance as OBSOLETE. Calls to this method will not operate in a toggling manner in that there is no way to "unset" a state of obsolescence.

This is a fluent method.

Example 
fake := NewNameForm().
	SetNumericOID(`1.3.6.1.4.1.56521.999.108.4`).
	SetName(`obsoleteForm`).
	SetObsolete()

fmt.Println(fake.Obsolete())

Output:

true

func (NameForm) SetSchema 

func (r NameForm) SetSchema(schema Schema) NameForm

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewNameForm method.

This is a fluent method.

func (NameForm) SetStringer 

func (r NameForm) SetStringer(function ...Stringer) NameForm

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the NameForm.SetStringer method to impose a custom Stringer closure over the default instance.

Naturally the end-user would opt for a more useful stringer, such as one that produces singular CSV rows per instance.

To avoid impacting other unit tests, we reset the default stringer via the NameForm.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

dnaf := mySchema.NameForms().Get(`dotNotationArcForm`)
dnaf.SetStringer(func() string {
	return "This useless message brought to you by a dumb stringer"
})

msg := fmt.Sprintln(dnaf)
dnaf.SetStringer() // return it to its previous state if need be ...

fmt.Printf("Original: %s\nOld: %s", dnaf, msg)

Output:

Original: ( 1.3.6.1.4.1.56521.101.2.7.3
    NAME 'dotNotationArcForm'
    DESC 'arc name form for a numeric OID RDN'
    OC arc
    MUST dotNotation
    X-ORIGIN 'draft-coretta-oiddir-schema' )
Old: This useless message brought to you by a dumb stringer

func (NameForm) String 

func (r NameForm) String() (nf string)

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

func (NameForm) Type 

func (r NameForm) Type() string

Type returns the string literal "nameForm".

Example 
var def NameForm
fmt.Println(def.Type())

Output:

nameForm

type NameForms 

type NameForms collection // RFC 4512 § 4.2.8

func NewNameForms 

func NewNameForms() NameForms

NewNameForms initializes a new NameForms instance.

func (NameForms) Compliant 

func (r NameForms) Compliant() bool

Compliant returns a Boolean value indicative of every NameForm returning a compliant response from the NameForm.Compliant method.

Example

This example demonstrates a compliancy check of all ObjectClasses members.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

forms := mySchema.NameForms()
fmt.Println(forms.Compliant())

Output:

true

func (NameForms) Contains 

func (r NameForms) Contains(id string) bool

Contains calls NameForms.Get to return a Boolean value indicative of a successful, non-zero retrieval of a NameForm instance -- matching the provided id -- from within the receiver stack instance.

Example

This example demonstrates a means of checking whether a particular instance of ObjectClass is present within an instance of ObjectClasses.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

classes := mySchema.NameForms()
fmt.Println(classes.Contains(`nArcForm`)) // or "1.3.6.1.4.1.56521.101.2.7.2"

Output:

true

func (NameForms) Get 

func (r NameForms) Get(id string) NameForm

Get returns an instance of NameForm based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of the principal identifier of a NameForm and the provided id.

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (NameForms) Index 

func (r NameForms) Index(idx int) NameForm

Index returns the instance of NameForm found within the receiver stack instance at index N. If no instance is found at the index specified, a zero NameForm instance is returned.

func (NameForms) Inventory 

func (r NameForms) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of NameForm instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example 
oc := mySchema.NameForms().Inventory()
fmt.Println(oc[`1.3.6.1.4.1.56521.101.2.7.2`][0])

Output:

nArcForm

func (NameForms) IsZero 

func (r NameForms) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (NameForms) Len 

func (r NameForms) Len() int

Len returns the current integer length of the receiver instance.

func (NameForms) Maps 

func (r NameForms) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the ObjectClasses.Maps method, which produces slices of DefinitionMap instances born of the ObjectClasses stack in which they reside. We (quite recklessly) call index three (3) and reference index zero (0) of its `SYNTAX` key to obtain the relevant LDAPSyntax OID string value. 

defs := mySchema.NameForms().Maps()
fmt.Println(defs[0][`NUMERICOID`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.56521.101.2.7.1

func (NameForms) Push 

func (r NameForms) Push(nf any) error

Push returns an error following an attempt to push a NameForm instance into the receiver stack instance.

Example

This example demonstrates the act of pushing, or appending, a new instance of NameForm into a new NameForms stack instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

nf := mySchema.NameForms().Get(`nArcForm`)
myNFs := NewNameForms()
myNFs.Push(nf)
fmt.Println(myNFs.Len())

Output:

1

func (NameForms) SetStringer 

func (r NameForms) SetStringer(function ...Stringer) NameForms

SetStringer allows the assignment of an individual Stringer function or method to all NameForm slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the NameForms.SetStringer method to impose a custom Stringer closure upon all stack members.

Naturally the end-user would opt for a more useful stringer, such as one that produces a CSV file containing all NameForm instances.

To avoid impacting other unit tests, we reset the default stringer via the NameForms.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

nfs := mySchema.NameForms()
nfs.SetStringer(func() string {
	return "" // make a null stringer
})

output := nfs.String()
nfs.SetStringer() // return to default

fmt.Println(output)

Output:

func (NameForms) String 

func (r NameForms) String() string

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

func (NameForms) Type 

func (r NameForms) Type() string

Type returns the string literal "nameForms".

Example 
oc := mySchema.NameForms()
fmt.Println(oc.Type())

Output:

nameForms

type ObjectClass 

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

ObjectClass implements § 4.1.1 of RFC 4512. 

ObjectClassDescription = LPAREN WSP
    numericoid                 ; object identifier
    [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
    [ SP "DESC" SP qdstring ]  ; description
    [ SP "OBSOLETE" ]          ; not active
    [ SP "SUP" SP oids ]       ; superior object classes
    [ SP kind ]                ; kind of class
    [ SP "MUST" SP oids ]      ; attribute types
    [ SP "MAY" SP oids ]       ; attribute types
    extensions WSP RPAREN

kind = "ABSTRACT" / "STRUCTURAL" / "AUXILIARY"

From clause 13.4.8 of ITU-T Rec. X.501: 

OBJECT-CLASS ::= CLASS {
	&Superclasses OBJECT-CLASS OPTIONAL,
	&kind ObjectClassKind DEFAULT structural,
	&MandatoryAttributes ATTRIBUTE OPTIONAL,
	&OptionalAttributes ATTRIBUTE OPTIONAL,
	&ldapName SEQUENCE SIZE(1..MAX) OF UTF8String OPTIONAL,
	&ldapDesc UTF8String OPTIONAL,
	&id OBJECT IDENTIFIER UNIQUE }

WITH SYNTAX {
	[SUBCLASS OF &Superclasses]
	[KIND &kind]
	[MUST CONTAIN &MandatoryAttributes]
	[MAY CONTAIN &OptionalAttributes]
	[LDAP-NAME &ldapName]
	[LDAP-DESC &ldapDesc]
	ID &id }

func NewObjectClass 

func NewObjectClass() ObjectClass

NewObjectClass initializes and returns a new instance of ObjectClass, ready for manual assembly. This method need not be used when creating new ObjectClass instances by way of parsing, as that is handled on an internal basis.

Use of this function does not automatically reference the "parent" Schema instance, leaving it up to the user to invoke the ObjectClass.SetSchema method manually.

When interacting with a single Schema instance, which represents most use cases, use of the Schema.NewObjectClass method is PREFERRED over use of this package-level function.

However certain migration efforts, schema audits and other such activities may require distinct associations of ObjectClass instances with specific Schema instances. Use of this function allows the user to specify the appropriate Schema instance at a later point for a specific instance of an ObjectClass instance.

Example

This example demonstrates the manual (non-parsed) assembly of a new ObjectClass instance.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

oc := NewObjectClass() // Important! Initializes internal stacks

// Conveniently input values in fluent form ...
oc.SetSchema(mySchema).
	SetName(`engineeringPersonnel`).
	SetDescription(`EP-46: Engineering employee`).
	SetKind(`AUXILIARY`).
	SetNumericOID(`1.3.6.1.4.1.56521.999.12.5`).
	SetSuperClass(`account`, `organizationalPerson`).
	SetMust(`uid`).
	SetMay(`sn`, `cn`, `l`, `st`, `c`, `co`).
	SetExtension(`X-ORIGIN`, `NOWHERE`).
	SetStringer() // use default stringer

fmt.Println(oc)

Output:

( 1.3.6.1.4.1.56521.999.12.5
    NAME 'engineeringPersonnel'
    DESC 'EP-46: Engineering employee'
    SUP ( account
        $ organizationalPerson )
    AUXILIARY
    MUST uid
    MAY ( sn
        $ cn
        $ l
        $ st
        $ c
        $ co )
    X-ORIGIN 'NOWHERE' )

func (ObjectClass) AllAttributes 

func (r ObjectClass) AllAttributes() (all AttributeTypes)

AllAttributes returns an AttributeTypes instance containing zero (0) or more permitted or required AttributeType definitions for use with this class as well as those specified by any and all applicable super classes.

This is useful if a complete list of all AttributeType instances which are available for use is needed.

Duplicate references are silently discarded.

Example

This example demonstrates the means of gathering a list of all possible AttributeType instances -- by OID -- that are either required or allowed by an ObjectClass instance. 

ats := mySchema.ObjectClasses().Get(`posixAccount`).AllAttributes()
for i := 0; i < ats.Len(); i++ {
	at := ats.Index(i)
	fmt.Println(at.OID())
}

Output:

description
gecos
loginShell
userPassword
objectClass
cn
gidNumber
homeDirectory
uid
uidNumber

func (ObjectClass) AllMay 

func (r ObjectClass) AllMay() (may AttributeTypes)

AllMay returns an AttributeTypes containing zero (0) or more allowed AttributeType definitions for use with this class as well as those specified by any and all applicable super classes. Duplicate references are silently discarded.

Example

This example demonstrates the means of gathering a list of all possible AttributeType instances -- by OID -- that are considered OPTIONAL per an ObjectClass instance. 

ats := mySchema.ObjectClasses().Get(`posixAccount`).AllMay()
for i := 0; i < ats.Len(); i++ {
	at := ats.Index(i)
	fmt.Println(at.OID())
}

Output:

description
gecos
loginShell
userPassword

func (ObjectClass) AllMust 

func (r ObjectClass) AllMust() (must AttributeTypes)

AllMust returns an AttributeTypes containing zero (0) or more required AttributeType definitions for use with this class as well as those specified by any and all applicable super classes. Duplicate references are silently discarded.

Example

This example demonstrates the means of gathering a list of all possible AttributeType instances -- by OID -- that are considered OPTIONAL per an ObjectClass instance. 

ats := mySchema.ObjectClasses().Get(`posixAccount`).AllMust()
for i := 0; i < ats.Len(); i++ {
	at := ats.Index(i)
	fmt.Println(at.OID())
}

Output:

objectClass
cn
gidNumber
homeDirectory
uid
uidNumber

func (ObjectClass) Attributes 

func (r ObjectClass) Attributes() (a AttributeTypes)

Attributes returns an instance of AttributeTypes containing references to AttributeType instances which reside within the receiver's MUST and MAY clauses.

This is useful if a complete list of all immediate AttributeType instances which are available for use and does not include those made available through super classes.

Duplicate references are silently discarded.

Example 
ats := mySchema.ObjectClasses().Get(`posixAccount`).Attributes()
for i := 0; i < ats.Len(); i++ {
	at := ats.Index(i)
	fmt.Println(at.OID())
}

Output:

cn
gidNumber
homeDirectory
uid
uidNumber
description
gecos
loginShell
userPassword

func (ObjectClass) Compliant 

func (r ObjectClass) Compliant() bool

Compliant returns a Boolean value indicative of the receiver being fully compliant per the required clauses of § 4.1.1 of RFC 4512:

  • Numeric OID must be present and valid
Example

This example demonstrates a compliancy check of the "account" ObjectClass. 

acc := mySchema.ObjectClasses().Get(`account`)
fmt.Println(acc.Compliant())

Output:

true

func (ObjectClass) Data 

func (r ObjectClass) Data() (x any)

Data returns the underlying value (x) assigned to the receiver's data storage field. Data can be set within the receiver instance by way of the ObjectClass.SetData method.

func (ObjectClass) Description 

func (r ObjectClass) Description() (desc string)

Description returns the underlying (optional) descriptive text assigned to the receiver instance.

func (ObjectClass) Extensions 

func (r ObjectClass) Extensions() (e Extensions)

Extensions returns the Extensions instance -- if set -- within the receiver.

func (ObjectClass) IsIdentifiedAs 

func (r ObjectClass) IsIdentifiedAs(id string) (ident bool)

IsIdentifiedAs returns a Boolean value indicative of whether id matches either the numericOID or descriptor of the receiver instance. Case is not significant in the matching process.

Example 
oc := mySchema.ObjectClasses().Get(`account`)
fmt.Println(oc.IsIdentifiedAs(`0.9.2342.19200300.100.4.5`))

Output:

true

func (ObjectClass) IsZero 

func (r ObjectClass) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (ObjectClass) Kind 

func (r ObjectClass) Kind() (kind uint)

Kind returns the uint-based kind value associated with the receiver instance.

func (ObjectClass) Map 

func (r ObjectClass) Map() (def DefinitionMap)

Map marshals the receiver instance into an instance of DefinitionMap.

Example 
def := mySchema.ObjectClasses().Get(`account`)
fmt.Println(def.Map()[`NUMERICOID`][0]) // risky, just for simplicity

Output:

0.9.2342.19200300.100.4.5

func (ObjectClass) May 

func (r ObjectClass) May() (may AttributeTypes)

May returns an AttributeTypes containing zero (0) or more allowed AttributeType definitions for use with this class.

func (ObjectClass) Must 

func (r ObjectClass) Must() (must AttributeTypes)

Must returns an AttributeTypes containing zero (0) or more required AttributeType definitions for use with this class.

func (ObjectClass) Name 

func (r ObjectClass) Name() (id string)

Name returns the string form of the principal name of the receiver instance, if set.

func (ObjectClass) Names 

func (r ObjectClass) Names() (names QuotedDescriptorList)

Names returns the underlying instance of QuotedDescriptorList from within the receiver.

func (ObjectClass) NumericOID 

func (r ObjectClass) NumericOID() (noid string)

NumericOID returns the string representation of the numeric OID held by the receiver instance.

func (ObjectClass) OID 

func (r ObjectClass) OID() (oid string)

OID returns the string representation of an OID -- which is either a numeric OID or descriptor -- that is held by the receiver instance.

func (ObjectClass) Obsolete 

func (r ObjectClass) Obsolete() (o bool)

Obsolete returns a Boolean value indicative of definition obsolescence.

func (ObjectClass) Parse 

func (r ObjectClass) Parse(raw string) (err error)

Parse returns an error following an attempt to parse raw into the receiver instance.

Note that the receiver MUST possess a Schema reference prior to the execution of this method.

Also note that successful execution of this method does NOT automatically push the receiver into any [ObjectClasss] stack, nor does it automatically execute the ObjectClass.SetStringer method, leaving these tasks to the user. If the automatic handling of these tasks is desired, see the Schema.ParseObjectClass method as an alternative.

func (ObjectClass) Replace 

func (r ObjectClass) Replace(x ObjectClass) ObjectClass

Replace overrides the receiver with x. Both must bear an identical numeric OID and x MUST be compliant.

Note that the relevant Schema instance must be configured to allow definition override by way of the AllowOverride bit setting. See the Schema.Options method for a means of accessing the settings value.

Note that this method does not reallocate a new pointer instance within the ObjectClass envelope type, thus all references to the receiver instance within various stacks will be preserved.

This is a fluent method.

Example

This example demonstrates a common (and most unfortunate) modification to an OFFICIAL ObjectClass definition -- "groupOfNames", found within Section 3.5 of RFC 4519.

The design of this particular class is widely considered to be inconvenient due to its mandate that at least one (1) instance of the "member" AttributeType (from Section 2.17 of RFC 4519).

As such, this has forced many LDAP architects to literally modify this ObjectClass definition within the given directory schema, moving the "member" AttributeType from the MUST clause to the MAY clause.

For reasons of oversight, we've added the RFC of origin as an X-ORIGIN extension, and a custom extension X-WARNING to remind users and admin alike that we've resorted to this risky trick. 

// make sure we enable the AllowOverride bit in
// our Schema instance early in its initialization
//mySchema.Options().Shift(AllowOverride)

// Same for HangingIndents - must be done prior
// to the parsing/loading of ANY definitions
// in a given Schema instance.
//mySchema.Options().Shift(HangingIndents)

// Obtain the groupOfNames (gon) ObjectClass so
// we can copy some of its values.
gon := mySchema.ObjectClasses().Get(`groupOfNames`)

// Craft a near identical groupOfNames instance,
// save for the one change we intend to make.
ngon := mySchema.NewObjectClass().
	SetName(gon.Name()).
	SetNumericOID(gon.NumericOID()).
	SetKind(gon.Kind()).
	SetSuperClass(`top`).
	SetMust(`cn`).
	SetMay(`member`, `businessCategory`, `seeAlso`, `owner`, `ou`, `o`, `description`).
	SetExtension(`X-ORIGIN`, `RFC4519`).
	SetExtension(`X-WARNING`, `MODIFIED`). // optional
	SetStringer()

// Replace gon with ngon, while preserving its pointer
// address so that references within stacks do not fail.
gon.Replace(ngon)

// call the new one (just to be sure)
fmt.Println(mySchema.ObjectClasses().Get(`groupOfNames`))

Output:

( 2.5.6.9
    NAME 'groupOfNames'
    SUP top
    STRUCTURAL
    MUST cn
    MAY ( member
        $ businessCategory
        $ seeAlso
        $ owner
        $ ou
        $ o
        $ description )
    X-ORIGIN 'RFC4519'
    X-WARNING 'MODIFIED' )

func (ObjectClass) Schema 

func (r ObjectClass) Schema() (s Schema)

Schema returns the Schema instance associated with the receiver instance.

func (ObjectClass) SetData 

func (r ObjectClass) SetData(x any) ObjectClass

SetData assigns x to the receiver instance. This is a general-use method and has no specific intent beyond convenience. The contents may be subsequently accessed via the ObjectClass.Data method.

This is a fluent method.

Example

This example demonstrates the assignment of arbitrary data to an instance of ObjectClass.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

// The value can be any type, but we'll
// use a string for simplicity.
documentation := `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`

// Obtain the target attribute type to bear
// the assigned value.
dvc := mySchema.ObjectClasses().Get(`device`)

// Set it.
dvc.SetData(documentation)

// Get it and compare to the original.
equal := documentation == dvc.Data().(string)

fmt.Printf("Values are equal: %t", equal)

Output:

Values are equal: true

func (ObjectClass) SetDescription 

func (r ObjectClass) SetDescription(desc string) ObjectClass

SetDescription parses desc into the underlying DESC clause within the receiver instance. Although a RFC 4512-compliant QuotedString is required, the outer single-quotes need not be specified literally.

func (ObjectClass) SetExtension 

func (r ObjectClass) SetExtension(x string, xstrs ...string) ObjectClass

SetExtension assigns key x to value xstrs within the receiver's underlying Extensions instance.

This is a fluent method.

func (ObjectClass) SetKind 

func (r ObjectClass) SetKind(k any) ObjectClass

SetKind assigns the abstraction of an objectClass "kind" to the receiver instance. Valid input types are as follows:

In the case of string names, case is not significant.

This is a fluent method.

func (ObjectClass) SetMay 

func (r ObjectClass) SetMay(m ...any) ObjectClass

SetMay assigns the provided input AttributeType instance(s) to the receiver's MAY clause.

This is a fluent method.

func (ObjectClass) SetMust 

func (r ObjectClass) SetMust(m ...any) ObjectClass

SetMust assigns the provided input AttributeType instance(s) to the receiver's MUST clause.

This is a fluent method.

func (ObjectClass) SetName 

func (r ObjectClass) SetName(x ...string) ObjectClass

SetName assigns the provided names to the receiver instance.

Name instances must conform to RFC 4512 descriptor format but need not be quoted.

This is a fluent method.

func (ObjectClass) SetNumericOID 

func (r ObjectClass) SetNumericOID(id string) ObjectClass

SetNumericOID allows the manual assignment of a numeric OID to the receiver instance if the following are all true:

  • The input id value is a syntactically valid numeric OID
  • The receiver does not already possess a numeric OID

This is a fluent method.

func (ObjectClass) SetObsolete 

func (r ObjectClass) SetObsolete() ObjectClass

SetObsolete sets the receiver instance to OBSOLETE if not already set.

Obsolescence cannot be unset.

This is a fluent method.

Example 
fake := NewObjectClass().
	SetNumericOID(`1.3.6.1.4.1.56521.999.108.4`).
	SetName(`obsoleteClass`).
	SetObsolete()

fmt.Println(fake.Obsolete())

Output:

true

func (ObjectClass) SetSchema 

func (r ObjectClass) SetSchema(schema Schema) ObjectClass

SetSchema assigns an instance of Schema to the receiver instance. This allows internal verification of certain actions without the need for user input of an instance of Schema manually at each juncture.

Note that the underlying Schema instance is automatically set when creating instances of this type by way of parsing, as well as if the receiver instance was initialized using the Schema.NewObjectClass method.

This is a fluent method.

func (ObjectClass) SetStringer 

func (r ObjectClass) SetStringer(function ...Stringer) ObjectClass

SetStringer allows the assignment of an individual Stringer function or method to the receiver instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite any preexisting stringer function with the internal closure default, which is based upon a one-time use of the text/template package by the receiver instance.

Input of a non-nil closure function value will overwrite any preexisting stringer.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the ObjectClass.SetStringer method to impose a custom Stringer closure over the default instance.

Naturally the end-user would opt for a more useful stringer, such as one that produces singular CSV rows per instance.

To avoid impacting other unit tests, we reset the default stringer via the ObjectClass.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

opers := mySchema.ObjectClasses().Get(`organizationalPerson`)
opers.SetStringer(func() string {
	return "This useless message brought to you by a dumb stringer"
})

msg := fmt.Sprintln(opers)
opers.SetStringer() // return it to its previous state if need be ...

fmt.Printf("Original: %s\nOld: %s", opers, msg)

Output:

Original: ( 2.5.6.7
    NAME 'organizationalPerson'
    SUP person
    STRUCTURAL
    MAY ( destinationIndicator
        $ facsimileTelephoneNumber
        $ internationalISDNNumber
        $ l
        $ ou
        $ physicalDeliveryOfficeName
        $ postOfficeBox
        $ postalAddress
        $ postalCode
        $ preferredDeliveryMethod
        $ registeredAddress
        $ st
        $ street
        $ telephoneNumber
        $ teletexTerminalIdentifier
        $ telexNumber
        $ title
        $ x121Address )
    X-ORIGIN 'RFC4519' )
Old: This useless message brought to you by a dumb stringer

func (ObjectClass) SetSuperClass 

func (r ObjectClass) SetSuperClass(x ...any) ObjectClass

SetSuperClass appends the input value(s) to the the super classes stack within the the receiver. Valid input types are string, to represent an RFC 4512 OID residing in the underlying Schema instance, or an bonafide ObjectClass instance already obtained or crafted.

This is a fluent method.

func (ObjectClass) String 

func (r ObjectClass) String() (def string)

String is a stringer method that returns the string representation of the receiver instance. A zero-value indicates an invalid receiver, or that the ObjectClass.SetStringer method was not used during MANUAL composition of the receiver.

func (ObjectClass) SubClasses added in v1.5.7 

func (r ObjectClass) SubClasses() (subs ObjectClasses)

SubClasses returns an instance of ObjectClasses containing slices of ObjectClass instances that are direct subordinates to the receiver instance. As such, this method is essentially the inverse of the ObjectClass.SuperClasses method.

The super chain is NOT traversed beyond immediate subordinate instances.

Note that the relevant Schema instance must have been set using the ObjectClass.SetSchema method prior to invocation of this method. Should this requirement remain unfulfilled, the return instance will be a zero instance.

Example

This example demonstrates the means of accessing all subordinate class instances of the receiver instance.

In essence, this method is the opposite of the ObjectClass.SuperClasses method and may return zero (0) or more ObjectClasses instances within the return ObjectClasses instance. 

def := mySchema.ObjectClasses().Get(`top`)
fmt.Printf("%d subordinate classes found", def.SubClasses().Len())

Output:

49 subordinate classes found

func (ObjectClass) SuperChain 

func (r ObjectClass) SuperChain() (sups ObjectClasses)

SuperChain returns an ObjectClasses stack of ObjectClass instances which make up the super type chain of the receiver instance.

Example

This example demonstrates the means of gathering references to every superior ObjectClass in the relevant super class chain. 

inet := mySchema.ObjectClasses().Get(`inetOrgPerson`)

oc := inet.SuperChain()
for i := 0; i < oc.Len(); i++ {
	fmt.Println(oc.Index(i).OID())
}

Output:

organizationalPerson
person
top

func (ObjectClass) SuperClassOf 

func (r ObjectClass) SuperClassOf(sub ObjectClass) (sup bool)

SuperClassOf returns a Boolean value indicative of r being a superior ("SUP") ObjectClass of sub.

Note: this will trace all super class chains indefinitely and, thus, will recognize any superior association without regard for "depth".

Example

This example demonstrates the means of checking superiority of a class over another class by way of the ObjectClass.SuperClassOf method.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

top := mySchema.ObjectClasses().Get(`top`)
acc := mySchema.ObjectClasses().Get(`account`)

fmt.Println(top.SuperClassOf(acc))

Output:

true

func (ObjectClass) SuperClasses 

func (r ObjectClass) SuperClasses() (sups ObjectClasses)

SuperClasses returns an ObjectClasses stack instance containing zero (0) or more superior ObjectClass instances from which the receiver directly extends. This method does not walk any super class chains.

func (ObjectClass) Type 

func (r ObjectClass) Type() string

Type returns the string literal "objectClass".

Example 
var def ObjectClass
fmt.Println(def.Type())

Output:

objectClass

type ObjectClasses 

type ObjectClasses collection // RFC 4512 § 4.2.1

func NewObjectClassOIDList 

func NewObjectClassOIDList(label ...string) ObjectClasses

NewObjectClassOIDList initializes and returns a new ObjectClasses that has been cast from an instance of [OIDList] and configured to allow the storage of arbitrary ObjectClass instances.

func NewObjectClasses 

func NewObjectClasses() ObjectClasses

NewObjectClasses initializes and returns a new ObjectClasses instance, configured to allow the storage of all ObjectClass instances.

func (ObjectClasses) Compliant 

func (r ObjectClasses) Compliant() bool

Compliant returns a Boolean value indicative of every ObjectClass returning a compliant response from the ObjectClass.Compliant method.

Example

This example demonstrates a compliancy check of all ObjectClasses members.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

classes := mySchema.ObjectClasses()
fmt.Println(classes.Compliant())

Output:

true

func (ObjectClasses) Contains 

func (r ObjectClasses) Contains(id string) bool

Contains calls ObjectClasses.Get to return a Boolean value indicative of a successful, non-zero retrieval of an ObjectClass instance -- matching the provided id -- from within the receiver stack instance.

Example

This example demonstrates a means of checking whether a particular instance of ObjectClass is present within an instance of ObjectClasses.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

classes := mySchema.ObjectClasses()
fmt.Println(classes.Contains(`top`)) // or "2.5.6.0"

Output:

true

func (ObjectClasses) Get 

func (r ObjectClasses) Get(id string) ObjectClass

Get returns an instance of ObjectClass based upon a search for id within the receiver stack instance.

The return instance, if not nil, was retrieved based upon a textual match of the principal identifier of an ObjectClass and the provided id.

The return instance is nil if no match was made.

Case is not significant in the matching process.

func (ObjectClasses) Index 

func (r ObjectClasses) Index(idx int) ObjectClass

Index returns the instance of ObjectClass found within the receiver stack instance at index N. If no instance is found at the index specified, a zero ObjectClass instance is returned.

func (ObjectClasses) Inventory 

func (r ObjectClasses) Inventory() (inv Inventory)

Inventory returns an instance of Inventory which represents the current inventory of ObjectClass instances within the receiver.

The keys are numeric OIDs, while the values are zero (0) or more string slices, each representing a name by which the definition is known.

Example 
oc := mySchema.ObjectClasses().Inventory()
fmt.Println(oc[`2.5.6.7`][0])

Output:

organizationalPerson

func (ObjectClasses) IsZero 

func (r ObjectClasses) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (ObjectClasses) Len 

func (r ObjectClasses) Len() int

Len returns the current integer length of the receiver instance.

func (ObjectClasses) Maps 

func (r ObjectClasses) Maps() (defs DefinitionMaps)

Maps returns slices of DefinitionMap instances.

Example

This example demonstrates use of the ObjectClasses.Maps method, which produces slices of DefinitionMap instances born of the ObjectClasses stack in which they reside. We (quite recklessly) call index three (3) and reference index zero (0) of its `SYNTAX` key to obtain the relevant LDAPSyntax OID string value. 

defs := mySchema.ObjectClasses().Maps()
fmt.Println(defs[3][`NUMERICOID`][0]) // risky, just for simplicity

Output:

1.3.6.1.4.1.1466.101.120.111

func (ObjectClasses) Push 

func (r ObjectClasses) Push(oc any) error

Push returns an error following an attempt to push an ObjectClass into the receiver instance.

func (ObjectClasses) SetStringer 

func (r ObjectClasses) SetStringer(function ...Stringer) ObjectClasses

SetStringer allows the assignment of an individual Stringer function or method to all ObjectClass slices within the receiver stack instance.

Input of zero (0) variadic values, or an explicit nil, will overwrite all preexisting stringer functions with the internal closure default, which is based upon a one-time use of the text/template package by all receiver slice instances.

Input of a non-nil closure function value will overwrite all preexisting stringers.

This is a fluent method and may be used multiple times.

Example

This example demonstrates use of the ObjectClasses.SetStringer method to impose a custom Stringer closure upon all stack members.

Naturally the end-user would opt for a more useful stringer, such as one that produces a CSV file containing all ObjectClass instances.

To avoid impacting other unit tests, we reset the default stringer via the ObjectClasses.SetStringer method again, with no arguments.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

attrs := mySchema.ObjectClasses()
attrs.SetStringer(func() string {
	return "" // make a null stringer
})

output := attrs.String()
attrs.SetStringer() // return to default

fmt.Println(output)

Output:

func (ObjectClasses) String 

func (r ObjectClasses) String() string

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

func (ObjectClasses) Type 

func (r ObjectClasses) Type() string

Type returns the string literal "objectClasses".

Example 
oc := mySchema.ObjectClasses()
fmt.Println(oc.Type())

Output:

objectClasses

type Option 

type Option uint16

Option represents a single configuration parameter within an instance of Options. 

const (
	// HangingIndents will cause all eligible string
	// processing to include hanging intends for a
	// given definition, as opposed to all definitions
	// occupying a single line each.
	HangingIndents Option = 1 << iota

	// SortExtensions will cause all ANTLR-based parsing
	// operations to sort all extensions alphabetically
	// according to the respective XString field value.
	//
	// Note this does not influence definition Extensions
	// that were manually crafted by the user.
	SortExtensions

	// SortLists will cause all ANTLR-based parsing operations
	// to sort all extensions alphabetically according to the
	// principal identifying string value of a slice member.
	// This will influence stacks that represent multi-valued
	// clauses like MAY, MUST, APPLIES and others.
	//
	// Note this does not influence slice members that were
	// entered manually by the user.
	SortLists

	// AllowOverride declares that any instance of Definition
	// may be replaced by way of its Replace method. This is
	// reflected in all stacks in which the Definition resides.
	AllowOverride
)

type Options 

type Options shifty.BitValue

Options wraps an instance of shifty.BitValue allowing clean and simple bit shifting/unshifting to effect changes to a Schema's behavior.

Instances of this type are accessed and managed via the Schema.Options method.

Users should NOT attempt to instantiate instances of this type manually for any reason.

func (Options) Positive 

func (r Options) Positive(x any) bool

Positive returns a Boolean value indicative of whether option x has been set within the receiver instance.

Input value x may be a non-negative int or explicit Option constants.

Example

This example demonstrates use of the Options.Positive method to determine whether a specific bit value registers as positive, or enabled. 

opts := mySchema.Options()
opts.Shift(AllowOverride) // FYR: AllowOverride is 8
fmt.Println(opts.Positive(16))

Output:

false

func (Options) Shift 

func (r Options) Shift(x ...any) Options

Unshift assigns the variadic bit values of x to the receiver instance.

Variadic input can include non-negative int or explicit Option constant slices.

This is a fluent method.

Example

This example demonstrates use of the Options.Shift method to set a particular bit value to a positive (enabled) state. 

opts := mySchema.Options()
opts.Shift(AllowOverride)
fmt.Println(opts.Positive(AllowOverride))

Output:

true

func (Options) Unshift 

func (r Options) Unshift(x ...any) Options

Unshift unassigns the variadic bit values of x to the receiver instance.

Variadic input can include non-negative int or explicit Option constant slices.

This is a fluent method.

Example

This example demonstrates use of the Options.Unshift method to set a particular bit value to a negative (disabled) state. 

opts := mySchema.Options()
opts.Shift(AllowOverride)
opts.Unshift(AllowOverride)
fmt.Println(opts.Positive(AllowOverride))

Output:

false

type QuotedDescriptorList 

type QuotedDescriptorList stackage.Stack

QuotedDescriptorList implements qdescrlist per § 4.1 of RFC 4512. Instances of this type need not be handled by users directly. 

qdescrlist = [ qdescr *( SP qdescr ) ]

func NewName 

func NewName() (name QuotedDescriptorList)

NewName initializes and returns a new instance of QuotedDescriptorList.

Example 
n := NewName()
n.Push(`thisIsAName`)
fmt.Println(n)

Output:

'thisIsAName'

func (QuotedDescriptorList) Contains 

func (r QuotedDescriptorList) Contains(name string) bool

Contains returns a Boolean value indicative of whether the input name value was found within the receiver instance. Case-folding is not significant in this operation.

Example 
n := NewName()
n.Push(`thisIsAName`)
fmt.Println(n.Contains(`otherName`))

Output:

false

func (QuotedDescriptorList) Index 

func (r QuotedDescriptorList) Index(idx int) string

Index returns the instance of string found within the receiver stack instance at index N. If no instance is found at the index specified, a zero string instance is returned.

Example 
var n QuotedDescriptorList
fmt.Println(n.Index(0))

Output:

func (QuotedDescriptorList) IsZero 

func (r QuotedDescriptorList) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

Example 
var n QuotedDescriptorList
fmt.Println(n.IsZero())

Output:

true

func (QuotedDescriptorList) Len 

func (r QuotedDescriptorList) Len() int

Len returns the current integer length of the receiver instance.

Example 
n := NewName()
n.Push(`thisIsAName`)
fmt.Println(n.Len())

Output:

1

func (QuotedDescriptorList) List 

func (r QuotedDescriptorList) List() (list []string)

List returns slices of string names from within the receiver.

func (QuotedDescriptorList) Push 

func (r QuotedDescriptorList) Push(name string) error

Push returns an error following an attempt to push name into the receiver instance. The name value must be non-zero in length and must be a valid RFC 4512 "descr" qualifier.

func (QuotedDescriptorList) String 

func (r QuotedDescriptorList) String() string

String is a stringer method that returns a properly formatted quoted descriptor list based on the number of string values within the receiver instance.

type QuotedStringList 

type QuotedStringList stackage.Stack

QuotedStringList implements qdstringlist per § 4.1 of RFC 4512. Instances of this type need not be handled by users directly. 

qdstringlist = [ qdstring *( SP qdstring ) ]

func (QuotedStringList) Contains 

func (r QuotedStringList) Contains(val string) bool

Contains returns a Boolean value indicative of the presence of the indicated key within the receiver instance.

func (QuotedStringList) Index 

func (r QuotedStringList) Index(idx int) string

Index returns the instance of string found within the receiver stack instance at index N. If no instance is found at the index specified, a zero string instance is returned.

func (QuotedStringList) IsZero 

func (r QuotedStringList) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver state.

func (QuotedStringList) Len 

func (r QuotedStringList) Len() int

Len returns the current integer length of the receiver instance.

func (QuotedStringList) List 

func (r QuotedStringList) List() (list []string)

List returns an instance of []string containing values derived from the receiver instance.

func (QuotedStringList) String 

func (r QuotedStringList) String() string

type RuleIDList 

type RuleIDList stackage.Stack

RuleIDList implements ruleidlist per § 4.1.7.1 of RFC 4512. Instances of this type need not be handled by users directly. 

ruleidlist = ruleid *( SP ruleid )

type Schema 

type Schema collection

Schema is a practical implementation of a 'subschemaSubentry' in that individual definitions are accessible and collectively define the elements available for use in populating a directory.

See the following methods to access any desired Definition qualifier types:

func NewBasicSchema 

func NewBasicSchema(o ...Option) (r Schema)

NewBasicSchema initializes and returns an instance of Schema.

The Schema instance shall only contain the LDAPSyntax and MatchingRule definitions from the following RFCs:

This function produces a Schema that best resembles the schema subsystem found in most DSA products today, in that LDAPSyntax and MatchingRule definitions generally are not loaded by the end user, however they are pre-loaded to allow immediate creation of other (dependent) definition types, namely AttributeType instances.

Option instances may be input in variadic form.

Example 
mySchema := NewBasicSchema()
fmt.Printf("%d syntaxes parsed", mySchema.Counters().LS)

Output:

67 syntaxes parsed

func NewEmptySchema 

func NewEmptySchema(o ...Option) (r Schema)

NewEmptySchema initializes and returns an instance of Schema completely initialized but devoid of any definitions whatsoever.

Option instances may be input in variadic form.

This function is intended for advanced users building a very specialized Schema instance.

Example 
mySchema := NewEmptySchema()
fmt.Printf("%d syntaxes parsed", mySchema.Counters().LS)

Output:

0 syntaxes parsed

func NewSchema 

func NewSchema(o ...Option) (r Schema)

NewSchema returns a new instance of Schema containing ALL package-included definitions. See the internal directory contents for a complete manifest.

Option instances may be input in variadic form.

Example

This example demonstrates the so-called "Quick Start Schema" initialization. The NewSchema function imports all built-in definitions instantly, allowing the user to start their activities with no fuss. 

mySchema := NewSchema()
fmt.Printf("%d types parsed", mySchema.Counters().AT)

Output:

168 types parsed

func (Schema) AttributeTypes 

func (r Schema) AttributeTypes() (ats AttributeTypes)

AttributeTypes returns the AttributeTypes instance from within the receiver instance.

func (Schema) Counters 

func (r Schema) Counters() Counters

Counters returns an instance of Counters bearing the current number of definitions by category.

The return instance is merely a snapshot in time and is NOT thread-safe.

Example

This example demonstrates obtaining a non thread-safe Counters instance, which outlines the number of Definition instances in categorical fashion. 

fmt.Printf("%d types present", mySchema.Counters().AT)

Output:

273 types present

func (Schema) DITContentRules 

func (r Schema) DITContentRules() (dcs DITContentRules)

DITContentRules returns the DITContentRules instance from within the receiver instance.

func (Schema) DITStructureRules 

func (r Schema) DITStructureRules() (dss DITStructureRules)

DITStructureRules returns the DITStructureRules instance from within the receiver instance.

func (Schema) DN 

func (r Schema) DN() string

DN returns the distinguished name by which the relevant subschemaSubentry may be accessed via the relevant DSA(s).

Example

This example demonstrates accessing the Schema instance's distinguished name, if set. 

fmt.Println(mySchema.DN())

Output:

cn=schema

func (Schema) IsZero 

func (r Schema) IsZero() bool

IsZero returns a Boolean value indicative of a nil receiver instance.

func (Schema) LDAPSyntaxes 

func (r Schema) LDAPSyntaxes() (lss LDAPSyntaxes)

LDAPSyntaxes returns the LDAPSyntaxes instance from within the receiver instance.

func (Schema) LoadAttributeTypes 

func (r Schema) LoadAttributeTypes() error

LoadAttributeTypes returns an error following an attempt to load all built-in AttributeType slices into the receiver instance.

func (Schema) LoadLDAPSyntaxes 

func (r Schema) LoadLDAPSyntaxes() error

LoadLDAPSyntaxes returns an error following an attempt to load all built-in LDAPSyntax definitions into the receiver instance.

func (Schema) LoadMatchingRules 

func (r Schema) LoadMatchingRules() error

LoadMatchingRules returns an error following to attempt to load all built-in MatchingRule definitions into the receiver instance.

func (Schema) LoadObjectClasses 

func (r Schema) LoadObjectClasses() error

LoadObjectClasses returns an error following an attempt to load all built-in ObjectClass slices into the receiver instance.

func (Schema) LoadRFC2079AttributeTypes 

func (r Schema) LoadRFC2079AttributeTypes() error

LoadRFC2079AttributeTypes returns an error following an attempt to load all RFC 2079 AttributeType slices into the receiver instance.

func (Schema) LoadRFC2079ObjectClasses 

func (r Schema) LoadRFC2079ObjectClasses() error

LoadRFC2079ObjectClasses returns an error following an attempt to load all RFC 2079 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC2307AttributeTypes 

func (r Schema) LoadRFC2307AttributeTypes() error

LoadRFC2307AttributeTypes returns an error following an attempt to load all RFC 2307 AttributeType slices into the receiver instance.

func (Schema) LoadRFC2307MatchingRules 

func (r Schema) LoadRFC2307MatchingRules() error

LoadRFC2307MatchingRules returns an error following an attempt to load all RFC 2307 MatchingRule slices into the receiver instance.

func (Schema) LoadRFC2307ObjectClasses 

func (r Schema) LoadRFC2307ObjectClasses() error

LoadRFC2307ObjectClasses returns an error following an attempt to load all RFC 2307 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC2307Syntaxes 

func (r Schema) LoadRFC2307Syntaxes() error

LoadRFC2307Syntaxes returns an error following an attempt to load all RFC 2307 LDAPSyntax slices into the receiver instance.

func (Schema) LoadRFC2589AttributeTypes added in v1.5.6 

func (r Schema) LoadRFC2589AttributeTypes() error

LoadRFC2589AttributeTypes returns an error following an attempt to load all RFC 2589 AttributeType slices into the receiver instance.

func (Schema) LoadRFC2798AttributeTypes 

func (r Schema) LoadRFC2798AttributeTypes() error

LoadRFC2798AttributeTypes returns an error following an attempt to load all RFC 2798 AttributeType slices into the receiver instance.

func (Schema) LoadRFC2798ObjectClasses 

func (r Schema) LoadRFC2798ObjectClasses() error

LoadRFC2798ObjectClasses returns an error following an attempt to load all RFC 2798 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC3045AttributeTypes 

func (r Schema) LoadRFC3045AttributeTypes() error

LoadRFC3045AttributeTypes returns an error following an attempt to load all RFC 3045 AttributeType slices into the receiver instance.

func (Schema) LoadRFC3671AttributeTypes 

func (r Schema) LoadRFC3671AttributeTypes() error

LoadRFC3671AttributeTypes returns an error following an attempt to load all RFC 3671 AttributeType slices into the receiver instance.

func (Schema) LoadRFC3671ObjectClasses 

func (r Schema) LoadRFC3671ObjectClasses() error

LoadRFC3671ObjectClasses returns an error following an attempt to load all RFC 3671 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC3672AttributeTypes 

func (r Schema) LoadRFC3672AttributeTypes() error

LoadRFC3672AttributeTypes returns an error following an attempt to load all RFC 3672 AttributeType slices into the receiver instance.

func (Schema) LoadRFC3672ObjectClasses 

func (r Schema) LoadRFC3672ObjectClasses() error

LoadRFC3672ObjectClasses returns an error following an attempt to load all RFC 3672 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC4512AttributeTypes 

func (r Schema) LoadRFC4512AttributeTypes() error

LoadRFC4512AttributeTypes returns an error following an attempt to load all RFC 4512 AttributeType slices into the receiver instance.

func (Schema) LoadRFC4512ObjectClasses 

func (r Schema) LoadRFC4512ObjectClasses() error

LoadRFC4512ObjectClasses returns an error following an attempt to load all RFC 4512 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC4517MatchingRules 

func (r Schema) LoadRFC4517MatchingRules() error

LoadRFC4517MatchingRules returns an error following an attempt to load all RFC 4517 MatchingRule slices into the receiver instance.

func (Schema) LoadRFC4517Syntaxes 

func (r Schema) LoadRFC4517Syntaxes() error

LoadRFC4517Syntaxes returns an error following an attempt to load all RFC 4517 LDAPSyntax slices into the receiver instance.

func (Schema) LoadRFC4519AttributeTypes 

func (r Schema) LoadRFC4519AttributeTypes() error

LoadRFC4519AttributeTypes returns an error following an attempt to load all RFC 4519 AttributeType slices into the receiver instance.

func (Schema) LoadRFC4519ObjectClasses 

func (r Schema) LoadRFC4519ObjectClasses() error

LoadRFC4519ObjectClasses returns an error following an attempt to load all RFC 4519 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC4523AttributeTypes 

func (r Schema) LoadRFC4523AttributeTypes() error

LoadRFC4523AttributeTypes returns an error following an attempt to load all RFC 4523 AttributeType slices into the receiver instance.

func (Schema) LoadRFC4523MatchingRules 

func (r Schema) LoadRFC4523MatchingRules() error

LoadRFC4523MatchingRules returns an error following an attempt to load all RFC 4523 MatchingRule slices into the receiver instance.

func (Schema) LoadRFC4523ObjectClasses 

func (r Schema) LoadRFC4523ObjectClasses() error

LoadRFC4523ObjectClasses returns an error following an attempt to load all RFC 4523 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC4523Syntaxes 

func (r Schema) LoadRFC4523Syntaxes() error

LoadRFC4523Syntaxes returns an error following an attempt to load all RFC 4523 LDAPSyntax slices into the receiver instance.

func (Schema) LoadRFC4524AttributeTypes 

func (r Schema) LoadRFC4524AttributeTypes() error

LoadRFC4524AttributeTypes returns an error following an attempt to load all RFC 4524 AttributeType slices into the receiver instance.

func (Schema) LoadRFC4524ObjectClasses 

func (r Schema) LoadRFC4524ObjectClasses() error

LoadRFC4524ObjectClasses returns an error following an attempt to load all RFC 4524 ObjectClass slices into the receiver instance.

func (Schema) LoadRFC4530AttributeTypes 

func (r Schema) LoadRFC4530AttributeTypes() error

LoadRFC4530AttributeTypes returns an error following an attempt to load all RFC 4530 AttributeType slices into the receiver instance.

func (Schema) LoadRFC4530MatchingRules 

func (r Schema) LoadRFC4530MatchingRules() error

LoadRFC4530MatchingRules returns an error following an attempt to load all RFC 4530 MatchingRule slices into the receiver instance.

func (Schema) LoadRFC4530Syntaxes 

func (r Schema) LoadRFC4530Syntaxes() error

LoadRFC4530Syntaxes returns an error following an attempt to load all RFC 4530 LDAPSyntax slices into the receiver instance.

func (Schema) LoadRFC5020AttributeTypes added in v1.5.6 

func (r Schema) LoadRFC5020AttributeTypes() error

LoadRFC5020AttributeTypes returns an error following an attempt to load all RFC 5020 AttributeType slices into the receiver instance.

func (Schema) LoadX501AttributeTypes 

func (r Schema) LoadX501AttributeTypes() error

LoadX501AttributeTypes returns an error following an attempt to load all X.501 AttributeType slices into the receiver instance.

func (Schema) Macros 

func (r Schema) Macros() Macros

Macros returns the current instance of Macros found within the receiver instance.

func (Schema) MatchingRuleUses 

func (r Schema) MatchingRuleUses() (mus MatchingRuleUses)

MatchingRuleUses returns the MatchingRuleUses instance from within the receiver instance.

func (Schema) MatchingRules 

func (r Schema) MatchingRules() (mrs MatchingRules)

MatchingRules returns the MatchingRules instance from within the receiver instance.

func (Schema) NameForms 

func (r Schema) NameForms() (nfs NameForms)

NameForms returns the NameForms instance from within the receiver instance.

func (Schema) NewAttributeType 

func (r Schema) NewAttributeType() AttributeType

NewAttributeType initializes and returns a new instance of AttributeType, ready for manual assembly. This method need not be used when creating new AttributeType instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.AttributeTypes stack; this is left to the user.

Unlike the package-level NewAttributeType function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the AttributeType.SetSchema method.

This is the recommended means of creating a new AttributeType instance wherever a single Schema is being used, which represents most use cases.

Example

This example demonstrates the preferred means of initializing a new instance of AttributeType. This strategy will automatically associate the receiver instance of Schema with the return value.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

nattr := mySchema.NewAttributeType()
nattr.SetNumericOID(`1.3.6.1.4.1.56521.999.14.56.1`)
fmt.Println(nattr.NumericOID())

Output:

1.3.6.1.4.1.56521.999.14.56.1

func (Schema) NewDITContentRule 

func (r Schema) NewDITContentRule() DITContentRule

NewDITContentRule initializes and returns a new instance of DITContentRule, ready for manual assembly. This method need not be used when creating new DITContentRule instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.DITContentRules stack; this is left to the user.

Unlike the package-level NewDITContentRule function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the DITContentRule.SetSchema method.

This is the recommended means of creating a new DITContentRule instance wherever a single Schema is being used, which represents most use cases.

func (Schema) NewDITStructureRule 

func (r Schema) NewDITStructureRule() DITStructureRule

NewDITStructureRule initializes and returns a new instance of DITStructureRule, ready for manual assembly. This method need not be used when creating new DITStructureRule instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.DITStructureRules stack; this is left to the user.

Unlike the package-level NewDITStructureRule function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the DITStructureRule.SetSchema method.

This is the recommended means of creating a new DITStructureRule instance wherever a single Schema is being used, which represents most use cases.

func (Schema) NewLDAPSyntax 

func (r Schema) NewLDAPSyntax() LDAPSyntax

NewLDAPSyntax initializes and returns a new instance of LDAPSyntax, ready for manual assembly. This method need not be used when creating new LDAPSyntax instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.LDAPSyntaxes stack; this is left to the user.

Unlike the package-level NewLDAPSyntax function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the LDAPSyntax.SetSchema method.

This is the recommended means of creating a new LDAPSyntax instance wherever a single Schema is being used, which represents most use cases.

func (Schema) NewMatchingRule 

func (r Schema) NewMatchingRule() MatchingRule

NewMatchingRule initializes and returns a new instance of MatchingRule, ready for manual assembly. This method need not be used when creating new MatchingRule instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.MatchingRules stack; this is left to the user.

Unlike the package-level NewMatchingRule function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the MatchingRule.SetSchema method.

This is the recommended means of creating a new MatchingRule instance wherever a single Schema is being used, which represents most use cases.

func (Schema) NewMatchingRuleUse 

func (r Schema) NewMatchingRuleUse() MatchingRuleUse

NewMatchingRuleUse initializes and returns a new instance of MatchingRuleUse, ready for manual assembly. This method need not be used when creating new MatchingRuleUse instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.MatchingRuleUses stack; this is left to the user.

Unlike the package-level NewMatchingRuleUse function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the MatchingRuleUse.SetSchema method.

This is the recommended means of creating a new MatchingRuleUse instance wherever a single Schema is being used, which represents most use cases.

Example

This example demonstrates a means of initializing a new instance of MatchingRuleUse, with the receiver instance of Schema automatically registered as its origin.

Generally this is not needed, and is shown here merely for coverage purposes. MatchingRuleUse instances are expected to be generated automatically by the DSA(s) governed by the relevant Schema, and never parsed through user input.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

var def MatchingRuleUse = mySchema.NewMatchingRuleUse()
fmt.Println(def.Type())

Output:

matchingRuleUse

func (Schema) NewNameForm 

func (r Schema) NewNameForm() NameForm

NewNameForm initializes and returns a new instance of NameForm, ready for manual assembly. This method need not be used when creating new NameForm instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.NameForms stack; this is left to the user.

Unlike the package-level NewNameForm function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the NameForm.SetSchema method.

This is the recommended means of creating a new NameForm instance wherever a single Schema is being used, which represents most use cases.

Example

This example demonstrates the creation of a new instance of NameForm.

Note: this example assumes a legitimate schema variable is defined in place of the fictional "mySchema" var shown here for simplicity. 

var def NameForm = mySchema.NewNameForm()

// set values in fluent form
def.SetSchema(mySchema).
	SetNumericOID(`1.3.6.1.4.1.56521.999.97.7`).
	SetName(`deviceNameForm`).
	SetOC(mySchema.ObjectClasses().Get(`device`)).
	SetMust(`cn`).
	SetStringer()

fmt.Printf("%s", def)

Output:

( 1.3.6.1.4.1.56521.999.97.7
    NAME 'deviceNameForm'
    OC device
    MUST cn )

func (Schema) NewObjectClass 

func (r Schema) NewObjectClass() ObjectClass

NewObjectClass initializes and returns a new instance of ObjectClass, ready for manual assembly. This method need not be used when creating new ObjectClass instances by way of parsing, as that is handled on an internal basis.

Use of this method does NOT automatically push the return instance into the Schema.ObjectClasses stack; this is left to the user.

Unlike the package-level NewObjectClass function, this method will automatically reference its originating Schema instance (the receiver). This negates the need for manual use of the ObjectClass.SetSchema method.

This is the recommended means of creating a new ObjectClass instance wherever a single Schema is being used, which represents most use cases.

func (Schema) ObjectClasses 

func (r Schema) ObjectClasses() (ocs ObjectClasses)

ObjectClasses returns the ObjectClasses instance from within the receiver instance.

func (Schema) Options 

func (r Schema) Options() Options

Options returns the underlying Options instance found within the receiver instance.

Example 
opts := mySchema.Options()
opts.Shift(AllowOverride)
fmt.Println(opts.Positive(AllowOverride))

Output:

true

func (Schema) ParseAttributeType 

func (r Schema) ParseAttributeType(raw string) error

ParseAttributeType returns an error following an attempt to parse raw into an instance of AttributeType and append it to the Schema.AttributeTypes stack.

func (Schema) ParseDITContentRule 

func (r Schema) ParseDITContentRule(raw string) error

ParseDITContentRule returns an error following an attempt to parse raw into an instance of DITContentRule and append it to the Schema.DITContentRules stack.

func (Schema) ParseDITStructureRule 

func (r Schema) ParseDITStructureRule(raw string) error

ParseDITStructureRule returns an error following an attempt to parse raw into an instance of DITStructureRule and append it to the Schema.DITStructureRules stack.

func (Schema) ParseDirectory 

func (r Schema) ParseDirectory(dir string) (err error)

ParseDirectory returns an error following an attempt to parse the directory found at dir. Sub-directories encountered are traversed indefinitely. Files encountered will only be read if their name ends in ".schema", at which point their contents are read into bytes, processed using ANTLR and written to the receiver instance.

This method wraps the antlr4512.Schema.ParseDirectory method.

func (Schema) ParseFile 

func (r Schema) ParseFile(file string) (err error)

ParseFile returns an error following an attempt to parse file. Only files ending in ".schema" will be considered, however submission of non-qualifying files shall not produce an error.

This method wraps the antlr4512.Schema.ParseFile method.

func (Schema) ParseLDAPSyntax 

func (r Schema) ParseLDAPSyntax(raw string) error

ParseLDAPSyntax returns an error following an attempt to parse raw into an instance of LDAPSyntax and append it to the Schema.LDAPSyntaxes stack.

func (Schema) ParseMatchingRule 

func (r Schema) ParseMatchingRule(raw string) error

ParseMatchingRule returns an error following an attempt to parse raw into an instance of MatchingRule and append it to the Schema.MatchingRules stack.

func (Schema) ParseMatchingRuleUse 

func (r Schema) ParseMatchingRuleUse(raw string) error

ParseMatchingRuleUse returns an error following an attempt to parse raw into an instance of MatchingRuleUse and append it to the Schema.MatchingRuleUses stack.

func (Schema) ParseNameForm 

func (r Schema) ParseNameForm(raw string) error

ParseNameForm returns an error following an attempt to parse raw into an instance of NameForm and append it to the Schema.NameForms stack.

func (Schema) ParseObjectClass 

func (r Schema) ParseObjectClass(raw string) error

ParseObjectClass returns an error following an attempt to parse raw into an instance of ObjectClass and append it to the Schema.ObjectClasses stack.

func (Schema) ParseRaw 

func (r Schema) ParseRaw(raw []byte) (err error)

ParseRaw returns an error following an attempt to parse raw into usable schema definitions. This method operates similarly to the Schema.ParseFile method, except this method expects "pre-read" raw definition bytes rather than a filesystem path leading to such content.

This method wraps the antlr4512.Schema.ParseRaw method.

func (Schema) Replace 

func (r Schema) Replace(x Definition) Schema

Replace will attempt to override a separate incarnation of itself using the Definition instance provided.

This is specifically to allow support for overriding certain Definition instances, such as an ObjectClass to overcome inherent flaws in its design.

The most common use case for this method is to allow users to override the "groupOfNames" ObjectClass to remove the "member" AttributeType from the MUST clause and, instead, place it in the MAY clause thereby allowing use of memberless groups within a DIT.

This method SHOULD NOT be used in a cavalier manner; modifying official Definition instances can wreck havoc on a directory and should only be performed by skilled directory professionals and only when absolutely necessary.

When overriding a DITStructureRule instance, a match is performed against the respective DITStructureRule.RuleID values. All other Definition types are matched using their respective numeric OIDs.

All replacement Definition instances are subject to compliancy checks.

This is a fluent method.

Example (ObjectClass) 
gon := mySchema.ObjectClasses().Get(`groupOfNames`)
ngon := mySchema.NewObjectClass().
	SetNumericOID(gon.NumericOID()).
	SetName(gon.Name()).
	SetDescription(gon.Description()).
	SetKind(gon.Kind()).
	SetSuperClass(`top`).
	SetMust(`cn`).
	SetMay(`member`,
		`businessCategory`,
		`seeAlso`,
		`owner`,
		`ou`,
		`o`,
		`description`).
	SetExtension(`X-ORIGIN`, `RFC4519`).
	SetExtension(`X-WARNING`, `MODIFIED`). // optional
	SetStringer()

mySchema.Options().Unshift(AllowOverride)
mySchema.Replace(ngon)
mySchema.Options().Shift(AllowOverride)
mySchema.Replace(ngon)

fmt.Println(mySchema.ObjectClasses().Get(`groupOfNames`))

Output:

( 2.5.6.9
    NAME 'groupOfNames'
    SUP top
    STRUCTURAL
    MUST cn
    MAY ( member
        $ businessCategory
        $ seeAlso
        $ owner
        $ ou
        $ o
        $ description )
    X-ORIGIN 'RFC4519'
    X-WARNING 'MODIFIED' )

func (Schema) SetDN 

func (r Schema) SetDN(dn string) Schema

SetDN assigns dn (e.g.: "cn=subSchema") to the receiver instance. By default, the value is set to "cn=schema" for new instances of Schema.

This is a fluent method.

Example

This example demonstrates specifying a non-standard distinguished name for use by the Schema instance. 

mySchema := NewEmptySchema()
mySchema.SetDN(`cn=subschema`)

fmt.Println(mySchema.DN())

Output:

cn=subschema

func (Schema) UpdateMatchingRuleUses 

func (r Schema) UpdateMatchingRuleUses() error

UpdateMatchingRuleUses returns an error following an attempt to refresh the current manifest of MatchingRuleUse instances using all of the AttributeType instances present within the receiver instance at the time of execution.

Example

This example demonstrates refreshing the MatchingRuleUses collection within the receiver instance of Schema. The result of this operation is influence by any new AttributeType instances that have been added since the last refresh. 

mySchema.UpdateMatchingRuleUses()
fmt.Printf("%d matchingRuleUses present", mySchema.Counters().MU)

Output:

32 matchingRuleUses present

type Stringer 

type Stringer func() string

Stringer is an optional function or method signature which allows user controlled string representation per definition.

type SyntaxQualifier 

type SyntaxQualifier func(any) error

SyntaxQualifier is an optional closure function or method signature which may be honored by the end user for value verification controls within LDAPSyntax instances.

type ValueQualifier 

type ValueQualifier func(any) error

ValueQualifier is an optional closure function of method signature which may be honored by the end user for enhanced value interrogation of any given value with respect to the AttributeType instance to which it is assigned.

This allows the implementation (or simulation) of common directory server features -- such as regular expression processing -- that allow for value constraints beyond, or instead of, those made possible through use of an LDAPSyntax alone. This is particularly useful within organizations or other bodies in which only specific, specialized values are to be allowed.

Source Files

View all Source files

Directories

Path Synopsis
internal
rfc2079
rfc2307
rfc2589
rfc2798
rfc3045
rfc3671
rfc3672
rfc4512
rfc4517
rfc4519
rfc4523
rfc4524
rfc4530
rfc5020
x501

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.