Class: Dry::Monads::List

Inherits:
Object
  • Object
show all
Includes:
Transformer
Defined in:
lib/dry/monads/list.rb

Overview

The List monad.

Defined Under Namespace

Modules: Mixin Classes: ListBuilder

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Transformer

#fmap2, #fmap3

Constructor Details

#initialize(value, type = nil) ⇒ List

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of List.



83
84
85
86
 
# File 'lib/dry/monads/list.rb', line 83

def initialize(value, type = nil)
  @value = value
  @type = type
end

Instance Attribute Details

#type ⇒ Object (readonly)

Internal array value



80
81
82
 
# File 'lib/dry/monads/list.rb', line 80

def type
  @type
end

#value ⇒ Object (readonly) Also known as: to_ary

Internal array value



80
81
82
 
# File 'lib/dry/monads/list.rb', line 80

def value
  @value
end

Class Method Details

.[](*values) ⇒ List

Builds a list.

Parameters:

  • values (Array<Object>) —

    List elements

Returns:



12
 
# File 'lib/dry/monads/list.rb', line 12

def [](*values) = new(values)

.coerce(value, type = nil) ⇒ List

Coerces a value to a list. ‘nil` will be coerced to an empty list.

Parameters:

  • value (Object) —

    Value

  • type (Monad) (defaults to: nil) —

    Embedded monad type (used in case of list of monadic values)

Returns:



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/dry/monads/list.rb', line 19

def coerce(value, type = nil)
  if value.nil?
    List.new([], type)
  elsif value.respond_to?(:to_ary)
    values = value.to_ary

    if !values.empty? && type.nil? && values[0].respond_to?(:monad)
      List.new(values, values[0].monad)
    else
      List.new(values, type)
    end
  else
    raise TypeError, "Can't coerce #{value.inspect} to List"
  end
end

.pure(value = Undefined, type = nil, &block) ⇒ List

Wraps a value with a list.

Parameters:

  • value (Object) (defaults to: Undefined) —

    any object

Returns:



39
40
41
42
43
44
45
46
47
 
# File 'lib/dry/monads/list.rb', line 39

def pure(value = Undefined, type = nil, &block)
  if value.equal?(Undefined)
    new([block])
  elsif block
    new([block], value)
  else
    new([value], type)
  end
end

.unfold(state, type = nil) ⇒ List

Iteratively builds a new list from a block returning Maybe values

Parameters:

  • state (Object.new) —

    Initial state

  • type (#pure) (defaults to: nil) —

    Type of list element

Returns:

See Also:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/dry/monads/list.rb', line 56

def unfold(state, type = nil)
  xs = []

  loop do
    m = yield(state)

    if m.some?
      state, x = m.value!
      xs << x
    else
      break
    end
  end

  new(xs, type)
end

Instance Method Details

#+(other) ⇒ List

Concatenates two lists.

Examples:

Dry::Monads::List[1, 2] + Dry::Monads::List[3, 4] # => List[1, 2, 3, 4]

Parameters:

  • other (List) —

    Other list

Returns:



145
 
# File 'lib/dry/monads/list.rb', line 145

def +(other) = List.new(to_ary + other.to_ary)

#apply(list = Undefined) ⇒ List

Applies the stored functions to the elements of the given list.

Parameters:

  • list (List) (defaults to: Undefined)

Returns:



282
283
284
285
 
# File 'lib/dry/monads/list.rb', line 282

def apply(list = Undefined, &)
  v = Undefined.default(list, &)
  fmap(Curry).bind { |f| v.fmap { f.(_1) } }
end

#bind(*args) ⇒ List

Lifts a block/proc and runs it against each member of the list. The block must return a value coercible to a list. As in other monads if no block given the first argument will be treated as callable and used instead.

Examples:

Dry::Monads::List[1, 2].bind { |x| [x + 1] } # => List[2, 3]
Dry::Monads::List[1, 2].bind(-> x { [x, x + 1] }) # => List[1, 2, 2, 3]

Parameters:

  • args (Array<Object>) —

    arguments will be passed to the block or proc

Returns:



99
100
101
102
103
104
105
106
 
# File 'lib/dry/monads/list.rb', line 99

def bind(*args)
  if block_given?
    List.coerce(value.map { yield(_1, *args) }.reduce([], &:+))
  else
    obj, *rest = args
    List.coerce(value.map { obj.(_1, *rest) }.reduce([], &:+))
  end
end

#collect ⇒ List

Iterates over the list and collects Some values.

Examples:

with block syntax

n = 20
List[10, 5, 0].collect do |divisor|
  if divisor.zero?
    None()
  else
    Some(n / divisor)
  end
end
# => List[2, 4]

without block

List[Some(5), None(), Some(3)].collect.map { |x| x * 2 }
# => [10, 6]

Returns:



315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/dry/monads/list.rb', line 315

def collect
  if block_given?
    collected = value.each_with_object([]) do |x, ys|
      y = yield(x)
      ys << y.value! if y.some?
    end

    List.new(collected)
  else
    Enumerator.new do |g|
      value.each { g << _1.value! if _1.some? }
    end
  end
end

#deconstruct ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Pattern matching

Examples:

case List[1, 2, 3]
in List[1, 2, x] then ...
in List[Integer, _, _] then ...
in List[0..2, _, _] then ...
end


340
 
# File 'lib/dry/monads/list.rb', line 340

def deconstruct = value

#empty? ⇒ TrueClass, FalseClass

Whether the list is empty.

Returns:

  • (TrueClass, FalseClass) 


193
 
# File 'lib/dry/monads/list.rb', line 193

def empty? = value.empty?

#filter ⇒ List Also known as: select

Filters elements with a block

Returns:



203
 
# File 'lib/dry/monads/list.rb', line 203

def filter(&) = coerce(value.select(&))

#first ⇒ Object

Returns the first element.

Returns:

  • (Object) 


166
 
# File 'lib/dry/monads/list.rb', line 166

def first = value.first

#fmap(*args) ⇒ List

Maps a block over the list. Acts as ‘Array#map`. As in other monads if no block given the first argument will be treated as callable and used instead.

Examples:

Dry::Monads::List[1, 2].fmap { |x| x + 1 } # => List[2, 3]

Parameters:

  • args (Array<Object>) —

    arguments will be passed to the block or proc

Returns:



117
118
119
120
121
122
123
124
 
# File 'lib/dry/monads/list.rb', line 117

def fmap(*args)
  if block_given?
    List.new(value.map { yield(_1, *args) })
  else
    obj, *rest = args
    List.new(value.map { obj.(_1, *rest) })
  end
end

#fold_left(initial) ⇒ Object Also known as: foldl, reduce

Folds the list from the left.

Parameters:

  • initial (Object) —

    Initial value

Returns:

  • (Object) 


177
 
# File 'lib/dry/monads/list.rb', line 177

def fold_left(initial, &) = value.reduce(initial, &)

#fold_right(initial) ⇒ Object Also known as: foldr

Folds the list from the right.

Parameters:

  • initial (Object) —

    Initial value

Returns:

  • (Object) 


185
186
187
 
# File 'lib/dry/monads/list.rb', line 185

def fold_right(initial)
  value.reverse.reduce(initial) { |a, b| yield(b, a) }
end

#head ⇒ Maybe<Object>

Returns the first element wrapped with a ‘Maybe`.

Returns:

  • (Maybe<Object>) 


219
 
# File 'lib/dry/monads/list.rb', line 219

def head = Monads::Maybe.coerce(value.first)

#inspect ⇒ String Also known as: to_s

Returns a string representation of the list.

Examples:

Dry::Monads::List[1, 2, 3].inspect # => "List[1, 2, 3]"

Returns:

  • (String) 


153
154
155
156
 
# File 'lib/dry/monads/list.rb', line 153

def inspect
  type_ann = typed? ? "<#{type.name.split("::").last}>" : ""
  "List#{type_ann}#{value.inspect}"
end

#last ⇒ Object

Returns the last element.

Returns:

  • (Object) 


171
 
# File 'lib/dry/monads/list.rb', line 171

def last = value.last

#map(&block) ⇒ List, Enumerator

Maps a block over the list. Acts as ‘Array#map`. If called without a block, this method returns an enumerator, not a List

Returns:

  • (List, Enumerator) 


130
131
132
133
134
135
136
 
# File 'lib/dry/monads/list.rb', line 130

def map(&block)
  if block_given?
    fmap(block)
  else
    value.map
  end
end

#monad ⇒ Monad

Returns the List monad.

Returns:

  • (Monad) 


290
 
# File 'lib/dry/monads/list.rb', line 290

def monad = List

#reverse ⇒ List

Reverses the list.

Returns:



214
 
# File 'lib/dry/monads/list.rb', line 214

def reverse = coerce(value.reverse)

#size ⇒ Integer

List size.

Returns:

  • (Integer) 


209
 
# File 'lib/dry/monads/list.rb', line 209

def size = value.size

#sort ⇒ List

Sorts the list.

Returns:



198
 
# File 'lib/dry/monads/list.rb', line 198

def sort = coerce(value.sort)

#tail ⇒ List

Returns list’s tail.

Returns:



224
 
# File 'lib/dry/monads/list.rb', line 224

def tail = coerce(value.drop(1))

#to_monad ⇒ List

Returns self.

Returns:



295
 
# File 'lib/dry/monads/list.rb', line 295

def to_monad = self

#traverse(proc = nil, &block) ⇒ Monad

Traverses the list with a block (or without it). This methods “flips” List structure with the given monad (obtained from the type). Note that traversing requires the list to be typed. Also if a block given, its returning type must be equal list’s type.

Examples:

List<Result>[Success(1), Success(2)].traverse # => Success([1, 2])
List<Maybe>[Some(1), None, Some(3)].traverse # => None

Returns:

  • (Monad) —

    Result is a monadic value



263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/dry/monads/list.rb', line 263

def traverse(proc = nil, &block)
  unless typed?
    raise StandardError, "Cannot traverse an untyped list"
  end

  cons = type.pure { |list, i| list + List.pure(i) }
  with = proc || block || Traverse[type]

  foldl(type.pure(EMPTY)) do |acc, el|
    cons
      .apply(acc)
      .apply { with.(el) }
  end
end

#typed(type = nil) ⇒ List

Turns the list into a typed one. Type is required for some operations like .traverse.

Parameters:

  • type (Monad) (defaults to: nil) —

    Monad instance

Returns:

  • (List) —

    Typed list



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/dry/monads/list.rb', line 231

def typed(type = nil)
  if type.nil?
    if size.zero?
      raise ArgumentError, "Cannot infer a monad for an empty list"
    else
      self.class.warn(
        "Automatic monad inference is deprecated, pass a type explicitly " \
        "or use a predefined constant, e.g. List::Result\n" \
        "#{caller.find { _1 !~ %r{(lib/dry/monads)|(gems)} }}"
      )
      self.class.new(value, value[0].monad)
    end
  else
    self.class.new(value, type)
  end
end

#typed? ⇒ Boolean

Whether the list is types

Returns:

  • (Boolean) 


251
 
# File 'lib/dry/monads/list.rb', line 251

def typed? = !type.nil?