module ROM::LDAP::Relation::Reading

Public Instance Methods

all?(&block) click to toggle source

@return [Boolean]

@api public

# File lib/rom/ldap/relation/reading.rb, line 168
def all?(&block)
  dataset.__send__(__method__, &block)
end
any?(&block) click to toggle source

@return [Boolean]

@api public

# File lib/rom/ldap/relation/reading.rb, line 153
def any?(&block)
  dataset.__send__(__method__, &block)
end
Also aliased as: exist?
authenticate(password) click to toggle source

Returns True if the filtered entity can bind.

@return [Boolean]

@api public

# File lib/rom/ldap/relation/reading.rb, line 80
def authenticate(password)
  dataset.bind(password)
end
branch(key) click to toggle source

An alternative search base selected from a class level hash.

@param key [Symbol]

@example

Relation.branches { custom: '(attribute=value)' }

relation.branch(:custom)

@api public

# File lib/rom/ldap/relation/reading.rb, line 42
def branch(key)
  with_base(self.class.branches[key])
end
by_pk(*pks) click to toggle source

Find tuples by primary_key which defaults to :entry_dn Method is required by commands.

@param pks [Integer, String]

@example

relation.by_pk(1001, 1002, 1003, 1004)
relation.by_pk('uid=test1,ou=users,dc=example,dc=com')

@return [Relation]

# File lib/rom/ldap/relation/reading.rb, line 182
def by_pk(*pks)
  where(primary_key => pks)
end
count() click to toggle source

Count the number of entries selected from the paginated dataset.

@return [Integer]

@api public

# File lib/rom/ldap/relation/reading.rb, line 128
def count
  dataset.__send__(__method__)
end
distinct?()
Alias for: one?
exist?(&block)
Alias for: any?
fetch(*pk) click to toggle source

Fetch a tuple identified by the pk

@param pk [String, Integer]

@example

users.fetch(1001) # => {:id => 1, name: "Peter"}

@return [Hash]

@raise [ROM::TupleCountMismatchError] When 0 or more than 1 tuples were found

@api public

# File lib/rom/ldap/relation/reading.rb, line 198
def fetch(*pk)
  by_pk(*pk).one!
end
find(value)
Alias for: grep
first() click to toggle source

First tuple from the relation

@example

relation.where(sn: 'smith').first

@return [Hash]

@api public

# File lib/rom/ldap/relation/reading.rb, line 210
def first
  dataset.first.to_h
end
grep(value) click to toggle source

Searches attributes of the projected schema for a match.

@param value [String]

@return [Relation]

@example

relation.find('eo')

@api public

# File lib/rom/ldap/relation/reading.rb, line 320
def grep(value)
  meta_fields = schema.attributes.select { |a| a.meta[:grep] }
  fields = meta_fields.any? ? meta_fields : schema

  new(dataset.grep(fields.map(&:name).sort, value))
end
Also aliased as: find
last() click to toggle source

Last tuple from the relation

@example

relation.where(sn: 'smith').last

@return [Hash]

@api public

# File lib/rom/ldap/relation/reading.rb, line 222
def last
  dataset.reverse_each.first.to_h
end
limit(number) click to toggle source

Limits the dataset to a number of tuples

@example

relation.limit(6)

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 294
def limit(number)
  new(dataset.with(limit: number))
end
list(field) click to toggle source

Array of values for an :attribute from all tuples.

@param field [Symbol] formatted or canonical attribute key

@example

relation.by_sn('Hamilton').list(:given_name)

@return [Array<Mixed>]

@raise [ROM::Struct::MissingAttribute] If auto_struct? and field not present.

@api public

# File lib/rom/ldap/relation/reading.rb, line 115
def list(field)
  if auto_struct?
    to_a.flat_map(&field)
  else
    map(field).to_a.compact.flatten
  end
end
map(key = nil, &block) click to toggle source

Map tuples from the relation

@example

users.map { |user| user[:id] }
# =>  [1, 2, 3]

users.map(:id).to_a
# =>  [1, 2, 3]

@param key [Symbol] An optional name of the key for extracting values

from tuples

@return [Array<Array>]

@api public

# File lib/rom/ldap/relation/reading.rb, line 99
def map(key = nil, &block)
  dataset.map(key, &block)
end
none?(&block) click to toggle source

@return [Boolean]

@api public

# File lib/rom/ldap/relation/reading.rb, line 161
def none?(&block)
  dataset.__send__(__method__, &block)
end
one?() click to toggle source

@return [Boolean]

@api public

# File lib/rom/ldap/relation/reading.rb, line 144
def one?
  dataset.__send__(__method__)
end
Also aliased as: distinct?, unique?
operational() click to toggle source

Include internal operational attributes in the tuples.

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 60
def operational
  new(dataset.with(attrs: ALL_ATTRS))
end
order(*attribute) click to toggle source

Use server-side sorting if available.

Orders the dataset by a given attribute using the coerced value.

SortResult ::= SEQUENCE {
    sortResult  ENUMERATED {
       success                   (0), -- results are sorted
       operationsError           (1), -- server internal failure
       timeLimitExceeded         (3), -- timelimit reached before
                                      -- sorting was completed
       strongAuthRequired        (8), -- refused to return sorted
                                      -- results via insecure
                                      -- protocol
       adminLimitExceeded       (11), -- too many matching entries
                                      -- for the server to sort
       noSuchAttribute          (16), -- unrecognized attribute
                                      -- type in sort key
       inappropriateMatching    (18), -- unrecognized or inappro-
                                      -- priate matching rule in
                                      -- sort key
       insufficientAccessRights (50), -- refused to return sorted
                                      -- results to this client
       busy                     (51), -- too busy to process
       unwillingToPerform       (53), -- unable to sort
       other                    (80)
       },
    attributeType [0] AttributeType OPTIONAL }

@param attribute [Symbol]

@example

relation.order(:uid_number).to_a =>
  [
    {uid_number: 101},
    {uid_number: 202},
    {uid_number: 303}
  ]

@return [Relation]

@see tools.ietf.org/html/rfc2891

@api public

# File lib/rom/ldap/relation/reading.rb, line 269
def order(*attribute)
  new(dataset.with(sort_attrs: attribute))
end
pluck(*names) click to toggle source

Pluck value(s) from specific attribute(s)

unwrapped only if all are lone results.

@example Single value

users.pluck(:uidnumber)
# ["1", "2"]

users.pluck(:cn)
# [["Cat", "House Cat"], ["Mouse"]]

@example Multiple values

users.pluck(:gidnumber, :uid)
# [["1", "Jane"] ["2", "Joe"]]

@param names [Symbol, String, Array<String, Symbol>]

@return [Array<String, Array>]

@api public

# File lib/rom/ldap/relation/reading.rb, line 377
def pluck(*names)
  raise ArgumentError, 'no attributes provided' if names.empty?

  map do |entry|
    results = values = names.map { |n| entry[n] }
    results = values.map(&:pop) if values.map(&:one?).all?
    results.one? ? results.pop : results
  end
end
project(*args, &block)
Alias for: select
random() click to toggle source

Shuffles the dataset.

@example

relation.random

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 306
def random
  new(dataset.with(random: true))
end
rename(mapping) click to toggle source

Rename attributes in a relation

This method is intended to be used internally within a relation object

@example

users.rename(name: :user_name).first
# {:id => 1, :user_name => "Jane", ... }

@param mapping [Hash<Symbol=>Symbol>] A name => new_name map

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 443
def rename(mapping)
  schema.rename(mapping).call(self)
end
reverse() click to toggle source

Reverses the dataset. Use server-side sorting if available.

@example

relation.reverse

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 282
def reverse
  new(dataset.with(direction: :desc))
end
select(*args, &block) click to toggle source

Select specific attributes

@overload select(*attributes)

Project relation using schema attributes

@example using attributes
  users.select(:id, :name).first
  # {:id => 1, :name => "Jane"}

@example using schema
  users.select(*schema.project(:id)).first
  # {:id => 1}

@param [Array<LDAP::Attribute>] columns A list of schema attributes

@overload select(&block)

Project relation using projection DSL

@example using attributes
  users.select { cn.as(:user_name) }
  # {:user_name => "Peter Hamilton"}

  users.select { [uidnumber, sn] }
  # {:uidnumber => 501, :name => "Hamilton"}

@param [Array<LDAP::Attribute>] columns A list of schema attributes

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 425
def select(*args, &block)
  schema.project(*args, &block).call(self)
end
Also aliased as: project
select_append(*args, &block) click to toggle source

Append specific columns to select clause

@see Relation#select

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 454
def select_append(*args, &block)
  schema.merge(schema.canonical.project(*args, &block)).call(self)
end
total() click to toggle source

Count the number of entries in the dataset.

@return [Integer]

@api public

# File lib/rom/ldap/relation/reading.rb, line 137
def total
  dataset.__send__(__method__)
end
unfiltered() click to toggle source

Remove additional search criteria and return to initial filter.

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 51
def unfiltered
  new(dataset.unfiltered)
end
unique?()
Alias for: one?
unwrap() click to toggle source

Returns tuples with popped values.

@return [LDAP::Relation]

# File lib/rom/ldap/relation/reading.rb, line 391
def unwrap
  new Functions[:map_array, Functions[:map_values, :pop]].call(self)
end
where(*args, &block) click to toggle source

Overwrites forwarding to Dataset#where

A Hash argument is passed straight to Dataset#equal. Otherwise the RestrictionDSL builds abstract queries

@param args [Array<Array, Hash>] AST queries or an attr/val hash.

@example

users.where { id.is(1)  }
users.where { id == 1   }
users.where { id > 1    }
users.where { id.gte(1) }

users.where(users[:id].is(1))
users.where(users[:id].lt(1))

@api public

# File lib/rom/ldap/relation/reading.rb, line 346
def where(*args, &block)
  if block
    where(args).where(schema.restriction(&block))
  elsif args.size == 1 && args[0].is_a?(Hash)
    new(dataset.equal(args[0]))
  elsif !args.empty?
    new(dataset.join(args))
  else
    self
  end
end
whole_tree() click to toggle source

Change the search base to search the whole directory tree.

@example

relation.whole_tree

@return [Relation]

@api public

# File lib/rom/ldap/relation/reading.rb, line 28
def whole_tree
  with_base(EMPTY_STRING)
end
with_base(alt_base) click to toggle source

Specify an alternative search base.

@example

relation.with_base("cn=department,ou=users,dc=org")

@return [Relation] Defaults to class attribute

@api public

# File lib/rom/ldap/relation/reading.rb, line 16
def with_base(alt_base)
  new(dataset.with(base: alt_base))
end