Module: DumbDelimited::ClassMethods

Defined in:
lib/dumb_delimited.rb

Instance Method Summary collapse

Instance Method Details

#append(path, models) ⇒ void

This method returns an undefined value.

Appends a collection of model objects to a file in delimited format. Convenience shortcut for #write with append: true.

Parameters:

  • path (String, Pathname)
  • models (Enumerable<Struct>) 


295
296
297
 
# File 'lib/dumb_delimited.rb', line 295

def append(path, models)
  write(path, models, append: true)
end

#delimiter ⇒ String

Returns the column delimiter used in IO operations. Defaults to a comma (",").

Equivalent to options[:col_sep].

Returns:

  • (String) 


140
141
142
 
# File 'lib/dumb_delimited.rb', line 140

def delimiter
  self.options[:col_sep]
end

#delimiter=(delim) ⇒ String

Sets the column delimiter used in IO operations. The new value will be used in all future IO operations for the model class. Any delimiter can be safely chosen, and all IO operations will quote field values as necessary.

Equivalent to options[:col_sep] = delim.

Examples:

Point = DumbDelimited[:x, :y, :z]
p = Point.new(1, 2, 3)
p.to_s  # == "1,2,3"
Point.delimiter = "|"
p.to_s  # == "1|2|3"

Parameters:

  • delim (String)

Returns:

  • (String) 


160
161
162
 
# File 'lib/dumb_delimited.rb', line 160

def delimiter=(delim)
  self.options[:col_sep] = delim
end

#options ⇒ Hash<Symbol, Object>

Returns the CSV options Hash. The Hash is not duped and can be modified directly. Any modifications will be applied to all future IO operations for the model class.

For detailed information about available options, see Ruby’s CSV class.

Returns:

  • (Hash<Symbol, Object>) 


109
110
111
112
113
114
115
116
117
118
 
# File 'lib/dumb_delimited.rb', line 109

def options
  @options ||= if superclass == Struct
    CSV::DEFAULT_OPTIONS.merge(
      skip_blanks: true,
      liberal_parsing: true,
    )
  else
    superclass.options.dup
  end
end

#options=(opts) ⇒ Hash<Symbol, Object>

Sets the CSV options Hash. The entire Hash is replaced, and the new values will be applied to all future IO operations for the model class. To set options individually, see #options.

For detailed information about available options, see Ruby’s CSV class.

Parameters:

  • opts (Hash<Symbol, Object>)

Returns:

  • (Hash<Symbol, Object>) 


130
131
132
 
# File 'lib/dumb_delimited.rb', line 130

def options=(opts)
  @options = opts
end

#parse(data) ⇒ Array<Struct> Also known as: parse_text

Parses a string or IO object into an array of model objects.

Examples:

Point = DumbDelimited[:x, :y, :z]
Point.parse("1,2,3\n4,5,6\n7,8,9\n")
  # == [
  #      Point.new(1, 2, 3),
  #      Point.new(4, 5, 6),
  #      Point.new(7, 8, 9)
  #    ]

Parameters:

  • data (String, IO)

Returns:

  • (Array<Struct>) 


189
190
191
 
# File 'lib/dumb_delimited.rb', line 189

def parse(data)
  parse_each(data).to_a
end

#parse_each(data) {|model| ... } ⇒ void #parse_each(data) ⇒ Enumerator<Struct>

Parses a string or IO object one line at a time, yielding a model object for each line.

An Enumerator is returned if no block is given.

Overloads:

  • #parse_each(data) {|model| ... } ⇒ void

    This method returns an undefined value.

    Parameters:

    • data (String, IO)

    Yield Parameters:

    • model (Struct)
  • #parse_each(data) ⇒ Enumerator<Struct>

    Parameters:

    • data (String, IO)

    Returns:

    • (Enumerator<Struct>) 


208
209
210
211
212
 
# File 'lib/dumb_delimited.rb', line 208

def parse_each(data, &block)
  return to_enum(__method__, data) unless block_given?

  csv_each(CSV.new(data, self.options), &block)
end

#parse_line(line) ⇒ Struct

Parses a single delimited line into a model object.

Examples:

Point = DumbDelimited[:x, :y, :z]
Point.parse_line("1,2,3")  # == Point.new(1, 2, 3)

Parameters:

  • line (String)

Returns:

  • (Struct) 


172
173
174
 
# File 'lib/dumb_delimited.rb', line 172

def parse_line(line)
  parse_each(line).first
end

#read(path) ⇒ Array<Struct> Also known as: parse_file

Parses a file into an array of model objects. This will load the entire contents of the file into memory, and may not be suitable for large files. To iterate over file contents without loading it all into memory at once, use #read_each.

Examples:

# CONTENTS OF FILE "points.csv":
# 1,2,3
# 4,5,6
# 7,8,9

Point = DumbDelimited[:x, :y, :z]
Point.read("points.csv")
  # == [
  #      Point.new(1, 2, 3),
  #      Point.new(4, 5, 6),
  #      Point.new(7, 8, 9)
  #    ]

Parameters:

  • path (String, Pathname)

Returns:

  • (Array<Struct>) 


235
236
237
 
# File 'lib/dumb_delimited.rb', line 235

def read(path)
  read_each(path).to_a
end

#read_each(path) {|model| ... } ⇒ void #read_each(path) ⇒ Enumerator<Struct>

Parses a file one line at a time, yielding a model object for each line. This avoids loading the entire contents of the file into memory at once.

An Enumerator is returned if no block is given. Note that some Enumerator methods, such as Enumerator#to_a, can cause the entire contents of the file to be loaded into memory.

Overloads:

  • #read_each(path) {|model| ... } ⇒ void

    This method returns an undefined value.

    Parameters:

    • path (String, Pathname)

    Yield Parameters:

    • model (Struct)
  • #read_each(path) ⇒ Enumerator<Struct>

    Parameters:

    • path (String, Pathname)

    Returns:

    • (Enumerator<Struct>) 


257
258
259
260
261
262
263
 
# File 'lib/dumb_delimited.rb', line 257

def read_each(path, &block)
  return to_enum(__method__, path) unless block_given?

  CSV.open(path, self.options) do |csv|
    csv_each(csv, &block)
  end
end

#write(path, models, append: false) ⇒ void

This method returns an undefined value.

Writes a collection of model objects to a file in delimited format. The previous contents of the file are overwritten, unless append is set to true.

Column headers are written to the file if :write_headers in #options is set to true and either append is false or the file is empty / non-existent. The column headers will be derived from either the value of :headers in #options if it is an Array, or otherwise from the columns defined by the model.

Parameters:

  • path (String, Pathname)
  • models (Enumerable<Struct>)
  • append (Boolean) (defaults to: false) 


279
280
281
282
283
284
285
286
287
 
# File 'lib/dumb_delimited.rb', line 279

def write(path, models, append: false)
  mode = append ? "a" : "w"
  write_headers = options[:write_headers] && !(append && File.exist?(path) && File.size(path) > 0)
  headers = (!options[:headers].is_a?(Array) && write_headers) ? members : options[:headers]

  CSV.open(path, mode, **options, write_headers: write_headers, headers: headers) do |csv|
    models.each{|model| csv << model }
  end
end