Module: ROM::LDAP::Relation::Reading

Included in:
ROM::LDAP::Relation
Defined in:
lib/rom/ldap/relation/reading.rb

Instance Method Summary collapse

Instance Method Details

#all?(&block) ⇒ Boolean

Returns:

  • (Boolean) 


168
169
170
 
# File 'lib/rom/ldap/relation/reading.rb', line 168

def all?(&block)
  dataset.__send__(__method__, &block)
end

#any?(&block) ⇒ Boolean Also known as: exist?

Returns:

  • (Boolean) 


153
154
155
 
# File 'lib/rom/ldap/relation/reading.rb', line 153

def any?(&block)
  dataset.__send__(__method__, &block)
end

#authenticate(password) ⇒ Boolean

Returns True if the filtered entity can bind.

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/rom/ldap/relation/reading.rb', line 80

def authenticate(password)
  dataset.bind(password)
end

#branch(key) ⇒ Object

An alternative search base selected from a class level hash.

Examples:

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

relation.branch(:custom)

Parameters:

  • key (Symbol) 


42
43
44
 
# File 'lib/rom/ldap/relation/reading.rb', line 42

def branch(key)
  with_base(self.class.branches[key])
end

#by_pk(*pks) ⇒ Relation

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

Examples:

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

Parameters:

  • pks (Integer, String)

Returns:



182
183
184
 
# File 'lib/rom/ldap/relation/reading.rb', line 182

def by_pk(*pks)
  where(primary_key => pks)
end

#count ⇒ Integer

Count the number of entries selected from the paginated dataset.

Returns:

  • (Integer) 


128
129
130
 
# File 'lib/rom/ldap/relation/reading.rb', line 128

def count
  dataset.__send__(__method__)
end

#fetch(*pk) ⇒ Hash

Fetch a tuple identified by the pk

Examples:

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

Parameters:

  • pk (String, Integer)

Returns:

  • (Hash)

Raises:

  • (ROM::TupleCountMismatchError) —

    When 0 or more than 1 tuples were found



198
199
200
 
# File 'lib/rom/ldap/relation/reading.rb', line 198

def fetch(*pk)
  by_pk(*pk).one!
end

#first ⇒ Hash

First tuple from the relation

Examples:

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

Returns:

  • (Hash) 


210
211
212
 
# File 'lib/rom/ldap/relation/reading.rb', line 210

def first
  dataset.first.to_h
end

#grep(value) ⇒ Relation Also known as: find

Searches attributes of the projected schema for a match.

Examples:

relation.find('eo')

Parameters:

  • value (String)

Returns:



320
321
322
323
324
325
 
# 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

#last ⇒ Hash

Last tuple from the relation

Examples:

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

Returns:

  • (Hash) 


222
223
224
 
# File 'lib/rom/ldap/relation/reading.rb', line 222

def last
  dataset.reverse_each.first.to_h
end

#limit(number) ⇒ Relation

Limits the dataset to a number of tuples

Examples:

relation.limit(6)

Returns:



294
295
296
 
# File 'lib/rom/ldap/relation/reading.rb', line 294

def limit(number)
  new(dataset.with(limit: number))
end

#list(field) ⇒ Array<Mixed>

Array of values for an :attribute from all tuples.

Examples:

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

Parameters:

  • field (Symbol) —

    formatted or canonical attribute key

Returns:

  • (Array<Mixed>)

Raises:

  • (ROM::Struct::MissingAttribute) —

    If auto_struct? and field not present.



115
116
117
118
119
120
121
 
# 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) ⇒ Array<Array>

Map tuples from the relation

Examples:

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

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

Parameters:

  • key (Symbol) (defaults to: nil) —

    An optional name of the key for extracting values from tuples

Returns:

  • (Array<Array>) 


99
100
101
 
# File 'lib/rom/ldap/relation/reading.rb', line 99

def map(key = nil, &block)
  dataset.map(key, &block)
end

#none?(&block) ⇒ Boolean

Returns:

  • (Boolean) 


161
162
163
 
# File 'lib/rom/ldap/relation/reading.rb', line 161

def none?(&block)
  dataset.__send__(__method__, &block)
end

#one? ⇒ Boolean Also known as: distinct?, unique?

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/rom/ldap/relation/reading.rb', line 144

def one?
  dataset.__send__(__method__)
end

#operational ⇒ Relation

Include internal operational attributes in the tuples.

Returns:



60
61
62
 
# File 'lib/rom/ldap/relation/reading.rb', line 60

def operational
  new(dataset.with(attrs: ALL_ATTRS))
end

#order(*attribute) ⇒ Relation

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 }

Examples:

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

Parameters:

  • attribute (Symbol)

Returns:

See Also:



269
270
271
 
# File 'lib/rom/ldap/relation/reading.rb', line 269

def order(*attribute)
  new(dataset.with(sort_attrs: attribute))
end

#pluck(*names) ⇒ Array<String, Array>

Pluck value(s) from specific attribute(s)

unwrapped only if all are lone results.

Examples:

Single value

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

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

Multiple values

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

Parameters:

  • names (Symbol, String, Array<String, Symbol>)

Returns:

  • (Array<String, Array>)

Raises:

  • (ArgumentError) 


377
378
379
380
381
382
383
384
385
 
# 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

#random ⇒ Relation

Shuffles the dataset.

Examples:

relation.random

Returns:



306
307
308
 
# File 'lib/rom/ldap/relation/reading.rb', line 306

def random
  new(dataset.with(random: true))
end

#rename(mapping) ⇒ Relation

Rename attributes in a relation

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

Examples:

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

Parameters:

  • mapping (Hash<Symbol=>Symbol>) —

    A name => new_name map

Returns:



443
444
445
 
# File 'lib/rom/ldap/relation/reading.rb', line 443

def rename(mapping)
  schema.rename(mapping).call(self)
end

#reverse ⇒ Relation

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

Examples:

relation.reverse

Returns:



282
283
284
 
# File 'lib/rom/ldap/relation/reading.rb', line 282

def reverse
  new(dataset.with(direction: :desc))
end

#search(new_filter) ⇒ Relation

Replace the relation filter with a new query.

Parameters:

  • new_filter (String) —

    Valid LDAP filter string

Returns:



71
72
73
 
# File 'lib/rom/ldap/relation/reading.rb', line 71

def search(new_filter)
  new(dataset.with(name: new_filter))
end

#select(*attributes) ⇒ Relation #select(&block) ⇒ Relation Also known as: project

Select specific attributes

Overloads:

  • #select(*attributes) ⇒ Relation

    Project relation using schema attributes

    Examples:

    using attributes

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

    using schema

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

    Parameters:

  • #select(&block) ⇒ Relation

    Project relation using projection DSL

    Examples:

    using attributes

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

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

    Parameters:

Returns:



425
426
427
 
# File 'lib/rom/ldap/relation/reading.rb', line 425

def select(*args, &block)
  schema.project(*args, &block).call(self)
end

#select_append(*args, &block) ⇒ Relation

Append specific columns to select clause

Returns:

See Also:



454
455
456
 
# 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 ⇒ Integer

Count the number of entries in the dataset.

Returns:

  • (Integer) 


137
138
139
 
# File 'lib/rom/ldap/relation/reading.rb', line 137

def total
  dataset.__send__(__method__)
end

#unfiltered ⇒ Relation

Remove additional search criteria and return to initial filter.

Returns:



51
52
53
 
# File 'lib/rom/ldap/relation/reading.rb', line 51

def unfiltered
  new(dataset.unfiltered)
end

#unwrap ⇒ LDAP::Relation

Returns tuples with popped values.

Returns:



391
392
393
 
# 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) ⇒ Object

Overwrites forwarding to Dataset#where

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

Examples:

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))

Parameters:

  • args (Array<Array, Hash>) —

    AST queries or an attr/val hash.



346
347
348
349
350
351
352
353
354
355
356
 
# 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 ⇒ Relation

Change the search base to search the whole directory tree.

Examples:

relation.whole_tree

Returns:



28
29
30
 
# File 'lib/rom/ldap/relation/reading.rb', line 28

def whole_tree
  with_base(EMPTY_STRING)
end

#with_base(alt_base) ⇒ Relation

Specify an alternative search base.

Examples:

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

Returns:

  • (Relation) —

    Defaults to class attribute



16
17
18
 
# File 'lib/rom/ldap/relation/reading.rb', line 16

def with_base(alt_base)
  new(dataset.with(base: alt_base))
end