Module: Xqsr3::IO

Defined in:

lib/xqsr3/io/writelines.rb

Class Method Summary

• .writelines(target, contents, options = {}) ⇒ Object

  Writes the contents to the target, subject to the options.

Class Method Details

.writelines(target, contents, options = {}) ⇒ Object

Writes the contents to the target, subject to the options

Signature

• Parameters:

  • target The target of the write, which may be a string containing the path or a stream instance that supports write

  • contents The contents to be write, which may be a Hash, or an Array, or a String containing delimited fields

  • options An options hash, containing any of the following options

• Options:

  • :column_separator optional The column separator, to be applied between each field in the case where contents is a Hash.

  • :eol_lookahead_limit optional The number of content elements (line/pair) to inspect to determine whether element has a terminating end-of-line sequence. Defaults to 20. If 0, and :line_separator is not specified, then will default to "\n". If nil, then every line will be inspected.

  • :line_separator optional The line separator, to be applied to the end of line created from each entry. When not specified, it will be deduced by inspecting contents (according to eol_lookahead_limit).

  • :no_last_eol optional If present and truey, causes suppression of the addition of the :line_separator on the last line.

Return

The number of entries in contents

# File 'lib/xqsr3/io/writelines.rb', line 175

def self.writelines target, contents, options = {}

	# validate parameters

	::Xqsr3::Quality::ParameterChecking.check_parameter(target, 'target', allow_nil: false) do |v|

		raise TypeError, "#{self}#writeline() 'target' parameter must be a #{::String} or respond to <<" unless ::String === v || v.respond_to?(:<<)
		true
	end
	::Xqsr3::Quality::ParameterChecking.check_parameter(contents, 'contents', allow_nil: false, types: [ ::String, ::Hash, ::Array ])

	# process parameters

	if contents.instance_of? String

		if contents.include? "\n"

			contents = contents.split(/\r?\n/, -1)
		else

			contents = [ contents ]
		end
	end

	options				||=	{}
	eol_lookahead_limit	=	options[:eol_lookahead_limit] || WriteLine_Constants_::NUMBER_OF_LINES_TO_EXAMINE
	column_separator	=	options[:column_separator] || ''
	no_last_eol			=	options[:no_last_eol] || false
	line_separator		=	nil
	line_separator		||=	options[:line_separator]
	line_separator		||=	self.deduce_line_separator_(contents, eol_lookahead_limit) unless !eol_lookahead_limit.kind_of?(::Integer) || 0 == eol_lookahead_limit
	line_separator		||=	"\n"

	if not contents.kind_of? ::Enumerable and not contents.instance_of? ::Hash

		raise ArgumentError, "writelines() must be passed a #{::String}, or a #{::Hash}, or an #{::Enumerable} (or derived)"
	end

	# do the writing

	if ::String === target

		File.open(target, "w") do |io|

			self.write_to_target_ io, contents, line_separator, column_separator, no_last_eol
		end
	else

		self.write_to_target_ target, contents, line_separator, column_separator, no_last_eol
	end
end