Class Bzip2::Reader
In: lib/bzip2/reader.rb
ext/bzip2.c
Parent: Object

Methods

allocate   close   close!   closed   closed?   each   each_byte   each_line   eof   eof?   eoz   eoz?   finish   foreach   getc   gets   lineno   lineno=   new   new   open   read   readchar   readline   readlines   readlines   to_io   ungetc   ungets   unused   unused=  

Included Modules

Enumerable

External Aliases

each -> each_line
closed? -> closed
eoz? -> eoz
eof? -> eof

Public Class methods

Internally allocates data for a new Reader @private

Reads a bz2 compressed file and yields each line to the block

   Bzip2::Writer.open('file'){ |f| f << "a\n" << "b\n" << "c\n\nd" }
   Bzip2::Reader.foreach('file'){ |l| p l }

   # Output:
   # "a\n"
   # "b\n"
   # "c\n"
   # "\n"
   # "d"

@param [String] filename the path to the file to open @yieldparam [String] each line of the file

Creates a new stream for reading a bzip file or string

@param [File, string, read] io the source for input data. If the source is

   a file or something responding to #read, then data will be read via #read,
   otherwise if the input is a string it will be taken as the literal data
   to decompress

Internally allocates data,

@see Bzip2::Writer#initialize @see Bzip2::Reader#initialize @private

@param [String] filename the name of the file to read from @yieldparam [Bzip2::Reader] reader the Bzip2::Reader instance

If a block is given, the created Bzip2::Reader instance is yielded to the block and will be closed when the block completes. It is guaranteed via ensure that the reader is closed

If a block is not given, a Bzip2::Reader instance will be returned

   Bzip2::Reader.open('file') { |f| puts f.gets }

   reader = Bzip2::Reader.open('file')
   puts reader.gets
   reader.close

@return [Bzip2::Reader, nil]

Opens the given bz2 compressed file for reading and decompresses the file, returning an array of the lines of the file. A line is denoted by the separator argument.

   Bzip2::Writer.open('file'){ |f| f << "a\n" << "b\n" << "c\n\nd" }

   Bzip2::Reader.readlines('file')      # => ["a\n", "b\n", "c\n", "\n", "d"]
   Bzip2::Reader.readlines('file', 'c') # => ["a\nb\nc", "\n\nd"]

@param [String] filename the path to the file to read @param [String] separator the character to denote a newline in the file @see Bzip2::Reader#readlines @return [Array] an array of lines for the file @raise [Bzip2::Error] if the file is not a valid bz2 compressed file

Public Instance methods

Closes this reader to disallow further reads.

   reader = Bzip2::Reader.new File.open('file')
   reader.close

   reader.closed? # => true

@return [File] the io with which the reader was created. @raise [IOError] if the stream has already been closed

Originally undocument and had no sepcs. Appears to work nearly the same as Bzip2::Reader#close

closed()

Alias for closed?

Tests whether this reader has be closed.

@return [Boolean] true if it is or false otherwise.

Iterates over the lines of the stream.

@param [String] sep the byte which separates lines @yieldparam [String] line the next line of the file (including the separator

   character)

@see Bzip2::Reader.foreach

Iterates over the decompressed bytes of the file.

   Bzip2::Writer.open('file'){ |f| f << 'asdf' }
   reader = Bzip2::Reader.new File.open('file')
   reader.each_byte{ |b| puts "#{b} #{b.chr}" }

   # Output:
   # 97 a
   # 115 s
   # 100 d
   # 102 f

@yieldparam [Integer] byte the decompressed bytes of the file

each_line(...)

Alias for each

eof()

Alias for eof?

Test whether the bzip stream has reached its end (see Bzip2::Reader#eoz?) and then tests that the undlerying IO has also reached an eof

@return [Boolean] true if the stream has reached or false otherwise.

eoz()

Alias for eoz?

Test whether the end of the bzip stream has been reached

@return [Boolean] true if the reader is at the end of the bz stream or

                  +false+ otherwise

Originally undocument and had no sepcs. Appears to call Bzip2::Reader#read and then mark the stream as finished, but this didn‘t work for me…

Reads one character from the stream, returning the byte read.

   reader = Bzip2::Reader.new Bzip2.compress('ab')
   reader.getc # => 97
   reader.getc # => 98
   reader.getc # => nil

@return [Integer, nil] the byte value of the character read or nil if eoz

   has been reached

Reads a line from the stream until the separator is reached. This does not throw an exception, but rather returns nil if an eoz/eof error occurs

   reader = Bzip2::Reader.new Bzip2.compress("a\nb")
   reader.gets # => "a\n"
   reader.gets # => "b"
   reader.gets # => nil

@return [String, nil] the read data or nil if eoz has been reached @see Bzip2::Reader#readline

Returns the current line number that the stream is at. This number is based on the newline separator being "\n"

   reader = Bzip2::Reader.new Bzip2.compress("a\nb")
   reader.lineno     # => 0
   reader.readline   # => "a\n"
   reader.lineno     # => 1
   reader.readline   # => "b"
   reader.lineno     # => 2

@return [Integer] the current line number

Sets the internal line number count that this stream should be set at

   reader = Bzip2::Reader.new Bzip2.compress("a\nb")
   reader.lineno     # => 0
   reader.readline   # => "a\n"
   reader.lineno     # => 1
   reader.lineno = 0
   reader.readline   # => "b"
   reader.lineno     # => 1

@note This does not actually rewind or move the stream forward @param [Integer] lineno the line number which the stream should consider

   being set at

@return [Integer] the line number provided

Read decompressed data from the stream.

   Bzip2::Reader.new(Bzip2.compress('ab')).read    # => "ab"
   Bzip2::Reader.new(Bzip2.compress('ab')).read(1) # => "a"

@return [String, nil] the decompressed data read or nil if eoz has been

   reached

@param [Integer] len the number of decompressed bytes which should be read.

   If nothing is specified, the entire stream is read

Performs the same as Bzip2::Reader#getc except Bzip2::EOZError is raised if eoz has been readhed

@raise [Bzip2::EOZError] if eoz has been reached

Reads one line from the stream and returns it (including the separator)

   reader = Bzip2::Reader.new Bzip2.compress("a\nb")
   reader.readline # => "a\n"
   reader.readline # => "b"
   reader.readline # => raises Bzip2::EOZError

@param [String] sep the newline separator character @return [String] the read line @see Bzip2::Reader.readlines @raise [Bzip2::EOZError] if the stream has reached its end

Reads the lines of the files and returns the result as an array.

If the stream has reached eoz, then an empty array is returned

@param [String] sep the newline separator character @return [Array] an array of lines read @see Bzip2::Reader.readlines

Returns the io stream underlying this stream. If the strem was constructed with a file, that is returned. Otherwise, an empty string is returned.

@return [File, String] similar to whatever the stream was constructed with @raise [IOError] if the stream has been closed

"Ungets" a character/byte. This rewinds the stream by 1 character and inserts the given character into that position. The next read will return the given character as the first one read

   reader = Bzip2::Reader.new Bzip2.compress('abc')
   reader.getc         # => 97
   reader.ungetc 97    # => nil
   reader.getc         # => 97
   reader.ungetc 42    # => nil
   reader.getc         # => 42
   reader.getc         # => 98
   reader.getc         # => 99
   reader.ungetc 100   # => nil
   reader.getc         # => 100

@param [Integer] byte the byte to ‘unget’ @return [nil] always

Equivalently "unget" a string. When called on a string that was just read from the stream, this inserts the string back into the stream to br read again.

When called with a string which hasn‘t been read from the stream, it does the same thing, and the next read line/data will start from the beginning of the given data and the continue on with the rest of the stream.

   reader = Bzip2::Reader.new Bzip2.compress("a\nb")
   reader.gets           # => "a\n"
   reader.ungets "a\n"   # => nil
   reader.gets           # => "a\n"
   reader.ungets "foo"   # => nil
   reader.gets           # => "foob"

@param [String] str the string to insert back into the stream @return [nil] always

Specs were missing for this method originally and playing around with it gave some very odd results, so unless you know what you‘re doing, I wouldn‘t mess around with this…

Specs were missing for this method originally and playing around with it gave some very odd results, so unless you know what you‘re doing, I wouldn‘t mess around with this…

[Validate]