Class: Zlib::GzipReader

Class | Zlib::GzipReader
In: | zlib/zlib.c
Parent: | Zlib::GzipFile

Zlib::GzipReader is the class for reading a gzipped file. GzipReader should be used an IO, or -IO-lie, object.

      Zlib::GzipReader.open('hoge.gz') {|gz|
        print gz.read
      }

      File.open('hoge.gz') do |f|
        gz = Zlib::GzipReader.new(f)
        print gz.read
        gz.close
      end

      # TODO: test these.  Are they equivalent?  Can GzipReader.new take a
      # block?

## Method Catalogue

The following methods in Zlib::GzipReader are just like their counterparts in IO, but they raise Zlib::Error or Zlib::GzipFile::Error exception if an error was found in the gzip file.

- each
- each_line
- each_byte
- gets
- getc
- lineno
- lineno=
- read
- readchar
- readline
- readlines
- ungetc

Be careful of the footer of the gzip file. A gzip file has the checksum of pre-compressed data in its footer. GzipReader checks all uncompressed data against that checksum at the following cases, and if it fails, raises `Zlib::GzipFile::NoFooter`, `Zlib::GzipFile::CRCError`, or `Zlib::GzipFile::LengthError` exception.

- When an reading request is received beyond the end of file (the end of compressed data). That is, when Zlib::GzipReader#read, Zlib::GzipReader#gets, or some other methods for reading returns nil.
- When Zlib::GzipFile#close method is called after the object reaches the end of file.
- When Zlib::GzipReader#unused method is called after the object reaches the end of file.

The rest of the methods are adequately described in their own documentation.

### Methods

each each_byte each_line eof eof? getc gets lineno lineno= new open pos read readchar readline readlines rewind tell ungetc unused

### Included Modules

Enumerable

### Public Class methods

Zlib::GzipReader.new(io)

Creates a GzipReader object associated with `io`. The GzipReader object reads gzipped data from `io`, and parses/decompresses them. At least, `io` must have a `read` method that behaves same as the `read` method in IO class.

If the gzip file header is incorrect, raises an Zlib::GzipFile::Error exception.

[Source]

    /*
     * call-seq: Zlib::GzipReader.new(io)
     *
     * Creates a GzipReader object associated with +io+. The GzipReader object reads
     * gzipped data from +io+, and parses/decompresses them.  At least, +io+ must have
     * a +read+ method that behaves same as the +read+ method in IO class.
     *
     * If the gzip file header is incorrect, raises an Zlib::GzipFile::Error
     * exception.
     */
    static VALUE
    rb_gzreader_initialize(obj, io)
        VALUE obj, io;
    {
        struct gzfile *gz;
        int err;

        Data_Get_Struct(obj, struct gzfile, gz);

        /* this is undocumented feature of zlib */
        err = inflateInit2(&gz->z.stream, -MAX_WBITS);
        if (err != Z_OK) {
    	raise_zlib_error(err, gz->z.stream.msg);
        }
        gz->io = io;
        ZSTREAM_READY(&gz->z);
        gzfile_read_header(gz);

        return obj;
    }

Zlib::GzipReader.open(filename) {|gz| ... }

Opens a file specified by `filename` as a gzipped file, and returns a GzipReader object associated with that file. Further details of this method are in Zlib::GzipReader.new and ZLib::GzipReader.wrap.

[Source]

    /*
     * call-seq: Zlib::GzipReader.open(filename) {|gz| ... }
     *
     * Opens a file specified by +filename+ as a gzipped file, and returns a
     * GzipReader object associated with that file.  Further details of this method
     * are in Zlib::GzipReader.new and ZLib::GzipReader.wrap.
     */
    static VALUE
    rb_gzreader_s_open(argc, argv, klass)
        int argc;
        VALUE *argv;
        VALUE klass;
    {
        return gzfile_s_open(argc, argv, klass, "rb");
    }

### Public Instance methods

each(...)

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_each(argc, argv, obj)
        int argc;
        VALUE *argv;
        VALUE obj;
    {
        VALUE str;
        while (!NIL_P(str = gzreader_gets(argc, argv, obj))) {
    	rb_yield(str);
        }
        return obj;
    }

each_byte()

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_each_byte(obj)
        VALUE obj;
    {
        VALUE c;
        while (!NIL_P(c = rb_gzreader_getc(obj))) {
    	rb_yield(c);
        }
        return Qnil;
    }

each_line(...)

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_each(argc, argv, obj)
        int argc;
        VALUE *argv;
        VALUE obj;
    {
        VALUE str;
        while (!NIL_P(str = gzreader_gets(argc, argv, obj))) {
    	rb_yield(str);
        }
        return obj;
    }

eof()

???

[Source]

    /*
     * ???
     */
    static VALUE
    rb_gzfile_eof_p(obj)
        VALUE obj;
    {
        struct gzfile *gz = get_gzfile(obj);
        return GZFILE_IS_FINISHED(gz) ? Qtrue : Qfalse;
    }

eof?()

???

[Source]

    /*
     * ???
     */
    static VALUE
    rb_gzfile_eof_p(obj)
        VALUE obj;
    {
        struct gzfile *gz = get_gzfile(obj);
        return GZFILE_IS_FINISHED(gz) ? Qtrue : Qfalse;
    }

getc()

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_getc(obj)
        VALUE obj;
    {
        struct gzfile *gz = get_gzfile(obj);
        VALUE dst;

        dst = gzfile_read(gz, 1);
        if (!NIL_P(dst)) {
    	dst = INT2FIX((unsigned int)(RSTRING(dst)->ptr[0]) & 0xff);
        }
        return dst;
    }

gets(...)

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_gets(argc, argv, obj)
        int argc;
        VALUE *argv;
        VALUE obj;
    {
        VALUE dst;
        dst = gzreader_gets(argc, argv, obj);
        if (!NIL_P(dst)) {
    	rb_lastline_set(dst);
        }
        return dst;
    }

lineno()

???

[Source]

    /*
     * ???
     */
    static VALUE
    rb_gzfile_lineno(obj)
        VALUE obj;
    {
        return INT2NUM(get_gzfile(obj)->lineno);
    }

lineno=(p1)

???

[Source]

    /*
     * ???
     */
    static VALUE
    rb_gzfile_set_lineno(obj, lineno)
        VALUE obj, lineno;
    {
        struct gzfile *gz = get_gzfile(obj);
        gz->lineno = NUM2INT(lineno);
        return lineno;
    }

pos()

???

[Source]

    /*
     * ???
     */
    static VALUE
    rb_gzfile_total_out(obj)
        VALUE obj;
    {
        struct gzfile *gz = get_gzfile(obj);
        return rb_uint2inum(gz->z.stream.total_out - gz->z.buf_filled);
    }

read(...)

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_read(argc, argv, obj)
        int argc;
        VALUE *argv;
        VALUE obj;
    {
        struct gzfile *gz = get_gzfile(obj);
        VALUE vlen;
        int len;

        rb_scan_args(argc, argv, "01", &vlen);
        if (NIL_P(vlen)) {
    	return gzfile_read_all(gz);
        }

        len = NUM2INT(vlen);
        if (len < 0) {
    	rb_raise(rb_eArgError, "negative length %d given", len);
        }
        return gzfile_read(gz, len);
    }

readchar()

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_readchar(obj)
        VALUE obj;
    {
        VALUE dst;
        dst = rb_gzreader_getc(obj);
        if (NIL_P(dst)) {
    	rb_raise(rb_eEOFError, "end of file reached");
        }
        return dst;
    }

readline(...)

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_readline(argc, argv, obj)
        int argc;
        VALUE *argv;
        VALUE obj;
    {
        VALUE dst;
        dst = rb_gzreader_gets(argc, argv, obj);
        if (NIL_P(dst)) {
    	rb_raise(rb_eEOFError, "end of file reached");
        }
        return dst;
    }

readlines(...)

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_readlines(argc, argv, obj)
        int argc;
        VALUE *argv;
        VALUE obj;
    {
        VALUE str, dst;
        dst = rb_ary_new();
        while (!NIL_P(str = gzreader_gets(argc, argv, obj))) {
    	rb_ary_push(dst, str);
        }
        return dst;
    }

rewind()

Resets the position of the file pointer to the point created the GzipReader object. The associated IO object needs to respond to the `seek` method.

[Source]

    /*
     * Resets the position of the file pointer to the point created the GzipReader
     * object.  The associated IO object needs to respond to the +seek+ method.
     */
    static VALUE
    rb_gzreader_rewind(obj)
        VALUE obj;
    {
        struct gzfile *gz = get_gzfile(obj);
        gzfile_reader_rewind(gz);
        return INT2FIX(0);
    }

tell()

???

[Source]

    /*
     * ???
     */
    static VALUE
    rb_gzfile_total_out(obj)
        VALUE obj;
    {
        struct gzfile *gz = get_gzfile(obj);
        return rb_uint2inum(gz->z.stream.total_out - gz->z.buf_filled);
    }

ungetc(p1)

See Zlib::GzipReader documentation for a description.

[Source]

    /*
     * See Zlib::GzipReader documentation for a description.
     */
    static VALUE
    rb_gzreader_ungetc(obj, ch)
        VALUE obj, ch;
    {
        struct gzfile *gz = get_gzfile(obj);
        gzfile_ungetc(gz, NUM2CHR(ch));
        return Qnil;
    }

unused()

Returns the rest of the data which had read for parsing gzip format, or `nil` if the whole gzip file is not parsed yet.

[Source]

    /*
     * Returns the rest of the data which had read for parsing gzip format, or
     * +nil+ if the whole gzip file is not parsed yet.
     */
    static VALUE
    rb_gzreader_unused(obj)
        VALUE obj;
    {
        struct gzfile *gz;
        Data_Get_Struct(obj, struct gzfile, gz);
        return gzfile_reader_get_unused(gz);
    }

[Validate]