Class: Ruber::World::DocumentList

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/ruber/world/document_list.rb

Overview

A list of documents

It’s an immutable Enumerable class with some convenience methods for dealing with documents.

The documents in the list are set in the constructor and can’t be changed later.

Direct Known Subclasses

MutableDocumentList

Instance Method Summary (collapse)

Methods included from Enumerable

#find!

Constructor Details

- (DocumentList) initialize(docs = [])

A new instance of DocumentList

Parameters:



42
43
44
 
# File 'lib/ruber/world/document_list.rb', line 42

def initialize docs = []
  @documents = docs.is_a?(DocumentList) ? docs.document_array : docs.dup
end

Instance Method Details

- (Boolean) ==(other)

Comparison operator

Parameters:

  • other (Object) —

    the object to compare self with

Returns:

  • (Boolean) —

    true if other is either an Array or a Ruber::World::DocumentList containing the same elements as self in the same order and false otherwise



227
228
229
230
231
232
233
234
 
# File 'lib/ruber/world/document_list.rb', line 227

def == other
  case other
  when DocumentList
    @documents == other.instance_variable_get(:@documents)
  when Array then @documents == other
  else false
  end
end

- (Document?) [](idx) - (Array<Document>?) [](range) - (Document?) [](url) - (Document?) [](file) - (Document?) [](name)

Element access

Overloads:

  • - (Document?) [](idx)

    Returns the document at a given position

    Parameters:

    • idx (Integer) —

      the index of the document to return. If negative, elements are counted from the end of the list

    Returns:

    • (Document, nil) —

      the document at position idx or nil if idx is out of range

  • - (Array<Document>?) [](range)

    Returns an array containing the documents in the given range of indexes

    Parameters:

    • range (Range) —

      the range of indexes of the documents to return. Negative indexes are counted from the end of the list

    Returns:

    • (Array<Document>, nil) —

      an array containing the documents corresponding to the given range. Indexes which are out of range are ignored. If the whole range is out of range, nil is returned

  • - (Document?) [](url)

    Returns the document associated with the given URL

    Parameters:

    • url (KDE::Url) —

      the url to retrieve the document for

    Returns:

    • (Document, nil) —

      the document associated with the given url or nil if the list contains no document associated with the url. If the list contains more than one document associated with the url, the first of them is returned

  • - (Document?) [](file)

    Returns the document associated with the given file

    Parameters:

    • fike (String) —

      the absolute path of the file

    Returns:

    • (Document, nil) —

      the document associated with the given file or nil if the list contains no document associated with the file. If the list contains more than one document associated with the file, the first of them is returned

  • - (Document?) [](name)

    Returns the document with the given document name

    Parameters:

    • name (String) —

      the document name. It must not start with a slash (/)

    Returns:

    • (Document, nil) —

      the document with the given document name or nil if the list contains no document with that name. If the list contains more than one document with that name, the first of them is returned

Returns:



115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/ruber/world/document_list.rb', line 115

def [] arg
  case arg
  when Integer, Range then @documents[arg]
  when KDE::Url then @documents.find{|doc| doc.url == arg}
  when String 
    if arg.start_with? '/'
      @documents.find do |doc|
        doc.url.local_file? and doc.path == arg
      end
    else @documents.find{|doc| doc.document_name == arg}
    end
  end
end

- (Array<Document>) document_array (protected)

The internal array used to keep trace of the documents

Returns:

  • (Array<Document>) —

    the internal array used to keep trace of the documents



264
265
266
 
# File 'lib/ruber/world/document_list.rb', line 264

def document_array
  @documents
end

- (Document?) document_for_file(file)

The document associated with a given file

Parameters:

  • file (String) —

    the absolute path of the file

Returns:

  • (Document, nil) —

    the document associated with the given file or nil if there’s no document associated with it in the list. If there is more than one document associated with the file, the first one will be returned

Raises:

  • (ArgumentError) —

    if the file name is not an absolute path (i.e., it doesn’t start with a /)



138
139
140
141
 
# File 'lib/ruber/world/document_list.rb', line 138

def document_for_file file
  raise ArgumentError, "#{file} is not an absolute path" unless file.start_with?('/')
  @documents.find{|doc| doc.url.local_file? && doc.path == file}
end

- (Boolean) document_for_file?(file)

Whether or not the list contains a document associated with a given file

Parameters:

  • file (String) —

    the absolute path of the file

Returns:

  • (Boolean) —

    true if the list contains a document associated with file and false otherwise

Raises:

  • (ArgumentError) —

    if the file name is not an absolute path (i.e., it doesn’t start with a /)



150
151
152
 
# File 'lib/ruber/world/document_list.rb', line 150

def document_for_file? file
  document_for_file(file).to_bool
end

- (Document?) document_for_url(url)

The document associated with a given URL

Parameters:

  • url (KDE::Url, String) —

    the URL associated with the file. If it is a string, it must be in a format suitable to be passed to KDE::Url.new

Returns:

  • (Document, nil) —

    the document associated with the given url or nil if there’s no document associated with it in the list. If there is more than one document associated with the URL, the first one will be returned



162
163
164
 
# File 'lib/ruber/world/document_list.rb', line 162

def document_for_url url
  @documents.find{|doc| doc.url == url}
end

- (Boolean) document_for_url?(url)

Whether or not the list contains a document associated with a given URL

Parameters:

  • url (KDE::Url, String) —

    the URL associated with the file. If it is a string, it must be in a format suitable to be passed to KDE::Url.new

Returns:

  • (Boolean) —

    true if the list contains a document associated with url and false otherwise



172
173
174
 
# File 'lib/ruber/world/document_list.rb', line 172

def document_for_url? url
  document_for_url(url).to_bool
end

- (Document?) document_with_name(name)

The document with a given document_name

Parameters:

  • name (String) —

    the name of the document

Returns:

  • (Document, nil) —

    the document with the given document name or nil if there’s no document with that name. If there is more than one document with the given document name, the first one will be returned



183
184
185
 
# File 'lib/ruber/world/document_list.rb', line 183

def document_with_name name
  @documents.find{|doc| doc.document_name == name}
end

- (Boolean) document_with_name?(name)

Whether or not the list contains a document with a given document name

Parameters:

  • name (String) —

    the name of the document

Returns:

  • (Boolean) —

    true if the list contains a document with the given document name and false otherwise



193
194
195
 
# File 'lib/ruber/world/document_list.rb', line 193

def document_with_name? name
  document_with_name(name).to_bool
end

- (Array<Document>) documents_with_file(which = :any)

A list of the documents having a file associated with them

According to the which argument, this method can return all the documents in the list which have a file associated with them, only those which have a local file associated with them or only those which have a remote file associated with them.

Parameters:

  • which (Symbol) (defaults to: :any) —

    the kind of files which can be associated with the documents. It can be: :local to return only documents associated with local files, :remote to return only documents associated with remote files or :any to return documents associated with either :local or :remote files

Returns:

  • (Array<Document>) —

    a list of the documents associated with a file, according with the restrictions posed by which.



212
213
214
215
216
217
218
 
# File 'lib/ruber/world/document_list.rb', line 212

def documents_with_file which = :any
  case which
  when :local then @documents.select{|doc| doc.url.local_file?}
  when :remote then @documents.select{|doc| doc.url.remote_file?}
  when :any then @documents.select{|doc| doc.has_file?}
  end
end

- (DocumentList) each {|doc| ... } - (Enumerator) each

Iterates on the documents

Overloads:

  • - (DocumentList) each {|doc| ... }

    Calls the block once for each document in the list, in insertion order

    Yield Parameters:

    Returns:

  • - (Enumerator) each

    An enumerator which iterates on the documents

    Returns:

    • (Enumerator) —

      an enumerator which iterates on the documents

Returns:



57
58
59
60
61
62
63
 
# File 'lib/ruber/world/document_list.rb', line 57

def each &blk
  if block_given?
    @documents.each &blk
    self
  else self.to_enum
  end
end

- (Boolean) empty?

Whether or not the list is empty

Returns:

  • (Boolean) —

    true if the list is empty and false otherwise



76
77
78
 
# File 'lib/ruber/world/document_list.rb', line 76

def empty?
  @documents.empty?
end

- (Boolean) eql?(other)

Comparison operator used by Hash

Parameters:

  • other (Object) —

    the object to compare self with

Returns:

  • (Boolean) —

    true if other is a Ruber::World::DocumentList containing the same elements as self in the same order and false otherwise



243
244
245
246
247
248
 
# File 'lib/ruber/world/document_list.rb', line 243

def eql? other
  if other.is_a? DocumentList
    @documents == other.instance_variable_get(:@documents)
  else false
  end
end

- (Integer) hash

Override of Object#hash

Returns:

  • (Integer) —

    the hash value for self



255
256
257
 
# File 'lib/ruber/world/document_list.rb', line 255

def hash
  @documents.hash
end

- (Integer) size

The number of documents in the list

Returns:

  • (Integer) —

    the number of documents in the list



68
69
70
 
# File 'lib/ruber/world/document_list.rb', line 68

def size
  @documents.size
end