README.md.erb

<%
  # This is the template file for README.md.  The gemspec details are available
  # within the _spec_ attribute, and all methods defined in the Rakefile are
  # also available.  The Rakefile will use this file to regenerate README.md
  # when necessary.
-%>
# Archive::Zip - ZIP Archival Made Easy

<%= word_wrap(spec.summary) %>

Basic archive creation and extraction can be handled using only a few methods.
More complex operations involving the manipulation of existing archives in place
(adding, removing, and modifying entries) are also possible with a little more
work.  Even adding advanced features such as new compression codecs are
supported with a moderate amount of effort.

## LINKS

* Homepage :: <%= spec.homepage %>
* Documentation :: http://rdoc.info/gems/archive-zip/frames
* Source :: http://github.com/javanthropus/archive-zip

## DESCRIPTION

<%= spec.description -%>

## FEATURES

* 100% native Ruby.  (Well, almost... depends on zlib.)
* Archive creation and extraction is supported with only a few lines of code.
* Archives can be updated "in place" or dumped out to other files or pipes.
* Files, symlinks, and directories are supported within archives.
* Unix permission/mode bits are supported.
* Unix user and group ownerships are supported.
* Unix last accessed and last modified times are supported.
* Entry extension (AKA extra field) implementations can be added on the fly.
* Unknown entry extension types are preserved during archive processing.
* The Deflate and Store compression codecs are supported out of the box.
* More compression codecs can be added on the fly.
* Traditional (weak) encryption is supported out of the box.

## KNOWN BUGS/LIMITATIONS

* More testcases are needed.
* All file entries are archived and extracted in binary mode.  No attempt is
  made to normalize text files to the line ending convention of any target
  system.
* Hard links and device files are not currently supported within archives.
* Reading archives from non-seekable IO, such as pipes and sockets, is not
  supported.
* MSDOS permission attributes are not supported.
* Strong encryption is not supported.
* Zip64 is not supported.
* Digital signatures are not supported.

## SYNOPSIS

More examples can be found in the `examples` directory of the source
distribution.

Create a few archives:

```ruby
require 'archive/zip'

# Add a_directory and its contents to example1.zip.
Archive::Zip.archive('example1.zip', 'a_directory')

# Add the contents of a_directory to example2.zip.
Archive::Zip.archive('example2.zip', 'a_directory/.')

# Add a_file and a_directory and its contents to example3.zip.
Archive::Zip.archive('example3.zip', ['a_directory', 'a_file'])

# Add only the files and symlinks contained in a_directory under the path
# a/b/c/a_directory in example4.zip.
Archive::Zip.archive(
  'example4.zip',
  'a_directory',
  :directories => false,
  :path_prefix => 'a/b/c'
)

# Add the contents of a_directory to example5.zip and encrypt Ruby source
# files.
require 'archive/zip/codec/null_encryption'
require 'archive/zip/codec/traditional_encryption'
Archive::Zip.archive(
  'example5.zip',
  'a_directory/.',
  :encryption_codec => lambda do |entry|
    if entry.file? and entry.zip_path =~ /\.rb$/ then
      Archive::Zip::Codec::TraditionalEncryption
    else
      Archive::Zip::Codec::NullEncryption
    end
  end,
  :password => 'seakrit'
)

# Create a new archive which will be written to a pipe.
# Assume $stdout is the write end a pipe.
# (ruby example.rb | cat >example.zip)
Archive::Zip.open($stdout, :w) do |z|
  z.archive('a_directory')
end
```

Now extract those archives:

```ruby
require 'archive/zip'

# Extract example1.zip to a_destination.
Archive::Zip.extract('example1.zip', 'a_destination')

# Extract example2.zip to a_destination, skipping directory entries.
Archive::Zip.extract(
  'example2.zip',
  'a_destination',
  :directories => false
)

# Extract example3.zip to a_destination, skipping symlinks.
Archive::Zip.extract(
  'example3.zip',
  'a_destination',
  :symlinks => false
)

# Extract example4.zip to a_destination, skipping entries for which files
# already exist but are newer or for which files do not exist at all.
Archive::Zip.extract(
  'example4.zip',
  'a_destination',
  :create => false,
  :overwrite => :older
)

# Extract example5.zip to a_destination, decrypting the contents.
Archive::Zip.extract(
  'example5.zip',
  'a_destination',
  :password => 'seakrit'
)
```

## FUTURE WORK ITEMS (in no particular order):

* Add test cases for all classes.
* Add support for using non-seekable IO objects as archive sources.
* Add support for 0x5855 and 0x7855 extra fields.

## REQUIREMENTS

* io-like

## INSTALL

Download the GEM file and install it with:

    $ gem install archive-zip-VERSION.gem

or directly with:

    $ gem install archive-zip

Removal is the same in either case:

    $ gem uninstall archive-zip

## DEVELOPERS

After checking out the source, run:

    $ bundle install
    $ bundle exec rake test yard

This will install all dependencies, run the tests/specs, and generate the
documentation.

## AUTHORS and CONTRIBUTORS

Thanks to all contributors.  Without your help this project would not exist.

<% spec.authors.zip(spec.email).each do |author, email| -%>
* <%= author %> :: <%= email %>
<% end -%>

## CONTRIBUTING

Contributions for bug fixes, documentation, extensions, tests, etc. are
encouraged.

1. Clone the repository.
2. Fix a bug or add a feature.
3. Add tests for the fix or feature.
4. Make a pull request.

### CODING STYLE

The following points are not necessarily set in stone but should rather be used
as a good guideline.  Consistency is the goal of coding style, and changes will
be more easily accepted if they are consistent with the rest of the code.

* **File Encoding**
  * UTF-8
* **Indentation**
  * Two spaces; no tabs
* **Line length**
  * Limit lines to a maximum of 80 characters
* **Comments**
  * Document classes, attributes, methods, and code
* **Method Calls with Arguments**
  * Use `a_method(arg, arg, etc)`; **not** `a_method( arg, arg, etc )`,
    `a_method arg, arg, etc`, or any other variation
* **Method Calls without Arguments**
  * Use `a_method`; avoid parenthesis
* **String Literals**
  * Use single quotes by default
  * Use double quotes when interpolation is necessary
  * Use `%{...}` and similar when embedding the quoting character is cumbersome
* **Blocks**
  * `do ... end` for multi-line blocks and `{ ... }` for single-line blocks
* **Boolean Operators**
  * Use `&&` and `||` for boolean tests; avoid `and` and `or`
* **In General**
  * Try to follow the flow and style of the rest of the code

## LICENSE

```
<%= File.read('LICENSE') -%>
```
<% # vim: set ts=2 sw=2 et: -%>