ruby-xz 0.2.2 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 28c451853871a094353485f28db08d64c5a5effa
-  data.tar.gz: 93ef5cba40e6a6330364206caf86dbcca6f95a7e
+SHA256:
+  metadata.gz: c92bf36556e0297676ad48820dc2ba25243e897ac3d4401d4a8ec89d695e77e4
+  data.tar.gz: 77a1b46d9158f80b6ad28c68483a02835fcecb9ae5fa85f9dcda296630238ea2
 SHA512:
-  metadata.gz: 75552a3ee976a8441ff397953bd608a8e9e6e5508b9c7cae73eb05278f509475c00fcea7ade557f758520c5b06b42711d96c162e9e5f2f5cc7ebed05e810a99f
-  data.tar.gz: 11b58af7569d56fe0c7486945a9e5ef87bfb0bf9579d29a82c3f7f21f8aa9ae2d03e118927bdc295585e857b82d5d536ddb9012393646591dc4a58585462587e
+  metadata.gz: 7830929d9fea616430f554cb2a2ae2ef95095b8cf5d90c19e70e5bba697f301a059071c9da83a926ed7654506ccbe317009147c11d444822a47f78f3592dbfbc
+  data.tar.gz: fea094736b25633859b303a17402a59cd673c3fafa80614dd096f5053c92d09604a2e06fbf3a1d75e11e04a34b336a54ffe4bb8ae4231f4766417a49d4cec5c7

data/AUTHORS

@@ -2,7 +2,6 @@
 
 All the people who worked on this project, in alphabetical order.
 
-* Lars Christensen (larsch)
-* Marvin Gülker (Quintus) <quintus ät quintilianus döt eu>
-* Christoph Plank (chrisistuff)
-* Nana Sakisaka (saki7)
+* Marvin Gülker (github.com/Quintus) <m-guelker@phoenixmail.de>
+* Alex Gittemeier (github.com/win93) <me@a.lexg.dev>
+* Christoph Plank (github.com/chrisistuff)

data/HISTORY.rdoc

@@ -1,15 +1,75 @@
 = Version history
 
-== 0.2.2 (unreleased)
+== 1.0.2 (2021-11-28)
+* Fix a deprecation warning and some other gemspec concerns (PR win93#6 by Alex Gittemeier)
 
-* *Add* XZ.disable_deprecation_notes
+== 1.0.1 (2021-11-13)
+* Fix a buffer overflow error in XZ::Stream (PR Quintus#17 by genail)
+* Fix an issue with transcode_options that was introduced by Ruby 3 (PR win93#1 by Alex Gittemeier)
+* Update project README, gemspec, and other metadata to reflect a change in
+  maintainership. All prior releases were released by Marvin Gülker.
+
+== 1.0.0 (2018-05-20)
+
+* *BreakingChange* The XZ module's methods now take any parameters
+  beyond the IO object as real Ruby keyword arguments rather than
+  a long argument list.
+* *BreakingChange* XZ.decompress_stream now honours Ruby's
+  external and internal encoding concept instead of just
+  returning BINARY-tagged strings.
+* *BreakingChange* Remove deprecated API on stream reader/writer
+  class and instead sync the API with Ruby's zlib library
+  (Ticket Quintus#12 by Quintus).
+* *BreakingChange* StreamWriter.new and StreamReader.new do not accept
+  a block anymore. This is part of syncing with Ruby's zlib API.
+* *BreakingChange* StreamReader.open and StreamWriter.open always
+  return the new instance, even if a block is given to the method
+  (previous behaviour was to return the return value of the block).
+  This is part of the syncing with Ruby's zlib API.
+* *BreakingChange* StreamReader.new and StreamWriter.new as well as
+  the ::open variants take additional arguments as real Ruby keyword
+  arguments now instead of a long parameter list plus options hash.
+  This is different from Ruby's own zlib API as that one takes both
+  a long parameter list and a hash of additional options. ruby-xz
+  is meant to follow zlib's semantics mostly, but not as a drop-in
+  replacement, so this divergence from zlib's API is okay (also
+  given that it isn't possible to replicate all possible options
+  1:1 anyway, since liblzma simply accepts different options as
+  libz). If you've never used these methods' optional arguments,
+  you should be fine.
+* *BreakingChange* Stream#close now returns nil instead of the
+  number of bytes written. This syncs Stream#close with Ruby's
+  own IO#close, which also returns nil.
+* *BreakingChange* Remove Stream#pos=, Stream#seek, Stream#stat. These
+  methods irritated the minitar gem, which doesn't expect them to
+  raise NotImplementedError, but directly to be missing if the object
+  does not support seeking.
+* *BreakingChange* StreamReader and StreamWriter now honour Ruby's
+  encoding system instead of returning only BINARY-tagged strings.
+* *Dependency* Remove dependency on ffi. ruby-xz now uses fiddle from
+  the stdlib instead.
+* *Dependency* Remove dependency on io-like. ruby-xz now implements
+  all the IO mechanics itself. (Ticket Quintus#10 by Quintus)
+* *Dependency* Bump required Ruby version to 2.3.0.
+* *Fix* libzlma.dylib not being found on OS X (Ticket Quintus#15 by
+  s0nspark).
+
+== 0.2.3 (2015-12-29)
+
+* *Fix* documentation of XZ module (a :nodoc: was causing havoc
+  in the XZ module so it appeared to have no methods).
+* No other changes this release.
+
+== 0.2.2 (2015-12-27)
+
+* *Add* XZ.disable_deprecation_notices
 * *Deprecate* use of XZ::StreamReader.open with an IO argument
 * *Deprecate* use of XZ::StreamReader.new with a filename argument
 * *Deprecate* use of XZ::StreamWriter.open with an IO argument
 * *Deprecate* use of XZ::StreamWriter.new with a filename argument
 * *Deprecate* nonautomatic IO close in XZ::StreamReader#close
 * *Deprecate* nonautomatic IO close in XZ::StreamWriter#close
-* *Fix* incompatibility with Resolv.getaddress() in Ruby 2.2 (Ticket #13
+* *Fix* incompatibility with Resolv.getaddress() in Ruby 2.2 (Ticket Quintus#13
   by Ken Simon)
 * Goal of these deprecations is to sync the API with Ruby’s own
   Zlib::GzipWriter and Zlib::GzipReader mostly.
@@ -20,12 +80,12 @@
 
 == 0.2.1 (2014-02-08)
 
-* Build the gem properly on Ruby 2.0+ (PR #8 by Nana Sakisaka (saki7))
-* Release the GIL when interfacing with liblzma (PR #7 by Lars Christensen (larsch))
+* Build the gem properly on Ruby 2.0+ (PR Quintus#8 by Nana Sakisaka (saki7))
+* Release the GIL when interfacing with liblzma (PR Quintus#7 by Lars Christensen (larsch))
 
 == 0.2.0 (2013-06-23)
 
-* Fix #6 (errors on JRuby) by Ben Nagy
+* Fix Quintus#6 (errors on JRuby) by Ben Nagy
 * <b>Remove 1.8 compatibility</b>
 
 == 0.1.0 (2013-02-17)

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright © 2011-2018 Marvin Gülker et al.
+
+See AUTHORS for the full list of contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the ‘Software’),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,67 +1,66 @@
-ruby-xz
-=======
+# ruby-xz
 
-**ruby-xz** is a basic binding to the famous [liblzma library][1],
-best known for the extreme compression-ratio it's native *XZ* format
-achieves. ruby-xz gives you the possibility of creating and extracting
-XZ archives on any platform where liblzma is installed. No compilation
-is needed, because ruby-xz is written ontop of
-[ffi][2].
+**ruby-xz** is a basic binding to the famous [liblzma] library,
+best known for the extreme compression-ratio it's native *XZ* format achieves.
+ruby-xz gives you the possibility of creating and extracting XZ archives on any
+platform where liblzma is installed.
+No compilation is needed, because ruby-xz is written on top of Ruby's [fiddle]
+library (part of the standard library).
+ruby-xz does not have any dependencies other than Ruby itself.
 
-ruby-xz supports both "intuitive" (de)compression by providing methods to
-directly operate on strings and files, but also allows you to operate
-directly on IO streams (see the various methods of the XZ module). On top
-of that, ruby-xz offers an advanced interface that allows you to treat
-XZ-compressed data as IO streams, both for reading and for writing. See the
-XZ::StreamReader and XZ::StreamWriter classes for more information on this.
+rubv-xz supports compression and decompression via methods that operate on
+strings and files, and it also supports compression and decompression on IO
+streams.
+the XZ::StreamReader and XZ::StreamWriter offer advanced interfaces that allow
+you to treat XZ-compressed data as IO streams, both for reading and for writing.
+<!-- TODO: link to relevant parts of the source code and/or documentation  -->
 
-Installation
-------------
+**Note**: Version 1.0.0 breaks the API quite heavily.
+Refer to HISTORY.rdoc for details.
 
-Install it the way you install all your gems.
+## Installation
 
-```
-$ gem install ruby-xz
+Install with `gem` from your Ruby installation:
+
+```sh
+gem install ruby-xz
 ```
 
-Alternatively, you can clone the repository and build the most recent
-code yourself:
+Alternatively, add it to your Gemfile via:
 
-```
-$ git clone git://github.com/Quintus/ruby-xz.git
-$ cd ruby-xz
-$ rake gem
-$ gem install pkg/ruby-xz-*.gem
+```sh
+bundle add ruby-xz
 ```
 
-Usage
------
+If you want to be on the bleeding edge, you can clone the repository and build
+the most recent code yourself:
 
-The documentation of the XZ module is well and you should be able to find
-everything you need to use ruby-xz. As said, it's not big, but powerful:
-You can create and extract whole archive files, compress or decompress
-streams of data or just plain strings.
+```sh
+git clone https://github.com/win93/ruby-xz.git
+cd ruby-xz
+rake gem
+gem install pkg/ruby-xz-*.gem
+```
 
-You can read the documentation on your local gemserver, or browse it [online][3].
+## Usage
 
-### First step ###
+You should be able to find everything you need to use ruby-xz in the
+documentation.
+It's small but powerful: You can create and extract whole archive files,
+compress or decompress whole files, strings, or streams of data.
 
-You have to require ruby-xz. Note the file you have to require is named
-"xz.rb", so do
+You can read the documentation on your local gemserver, or browse it [online][rubydoc].
+ <!-- TODO how do I read the docs on my local gemserver? -->
 
-``` ruby
-require "xz"
-```
-
-to get it.
-
-### Examples ###
+### Examples
 
 ``` ruby
-# Compress a TAR archive
-XZ.compress_file("myfile.tar", "myfile.tar.xz")
+require 'xz'
+
+# Compress a file
+XZ.compress_file("myfile.txt", "myfile.txt.xz")
 # Decompress it
-XZ.decompress_file("myfile.tar.xz", "myfile.tar")
+XZ.decompress_file("myfile.txt.xz", "myfile.txt")
 
 # Compress everything you get from a socket (note that there HAS to be a EOF
 # sometime, otherwise this will run infinitely)
@@ -73,45 +72,68 @@ comp = XZ.compress("Mydata")
 data = XZ.decompress(comp)
 ```
 
-Have a look at the XZ module's documentation for an in-depth description of
-what is possible.
+Have a look at the XZ module's documentation for an in-depth description of what
+is possible.
+<!-- TODO link to such documentation -->
+
+### Usage with the minitar gem
+
+ruby-xz can be used together with the [minitar] library (formerly
+“archive-tar-minitar”) to create XZ-compressed tarballs.
+This works by employing the IO-like classes XZ::StreamReader and
+XZ::StreamWriter analogous to how one would use Ruby's “zlib” library together
+with “minitar”:
+
+``` ruby
+require "xz"
+require "minitar"
+
+# Create an XZ-compressed tarball
+XZ::StreamWriter.open("tarball.tar.xz") do |txz|
+  Minitar.pack("path/to/directory", txz)
+end
+
+# Unpack it again
+XZ::StreamReader.open("tarball.tar.xz") do |txz|
+  Minitar.unpack(txz, "path/to/target/directory")
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+To install this gem onto your local machine, run `rake install`.
 
-Links
------
+To release a new version:
 
-* Code repository: https://github.com/Quintus/ruby-xz
-* Issue tracker: https://github.com/Quintus/ruby-xz/issues
-* Online documentation: http://quintus.github.io/ruby-xz
+- Switch to the `development` branch.
+- Bump `lib/xz/version.rb`, run `bundle install`, then commit the result.
+- Switch to the `stable` branch.
+- Run `git merge --no-ff development`
+- Run `rake release`, which will create/push a git tag and publish the `.gem`
+  file to [rubygems.org].
 
-License
--------
+[rubygems.org]: https://rubygems.org
 
-(The MIT License)
+## Links
 
-Basic liblzma-bindings for Ruby.
+* Online documentation: <https://rubydoc.info/gems/ruby-xz>
+* Code repository: <https://github.com/win93/ruby-xz>
+* Issue tracker: <https://github.com/win93/ruby-xz/issues>
 
-Copyright © 2011-2015 Marvin Gülker et al.
+## License
 
-See AUTHORS for the full list of contributors.
+MIT license; see LICENSE for the full license text.
 
-Permission is hereby granted, free of charge, to any person obtaining a
-copy of this software and associated documentation files (the ‘Software’),
-to deal in the Software without restriction, including without limitation
-the rights to use, copy, modify, merge, publish, distribute, sublicense,
-and/or sell copies of the Software, and to permit persons to whom the Software
-is furnished to do so, subject to the following conditions:
+## Acknowledgements
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+On November 2021, I volunteered to take over maintenance of this project, which
+was forked from <https://github.com/Quintus/ruby-xz>.
+@Quintus maintained this project until 1.0.0, see HISTORY.rdoc for more details.
 
-THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
 
-[1]: http://tukaani.org/xz/
-[2]: https://github.com/ffi/ffi
-[3]: http://quintus.github.io/ruby-xz
+[fiddle]: https://github.com/ruby/fiddle
+[liblzma]: https://tukaani.org/xz/
+[rubydoc]: https://www.rubydoc.info/gems/ruby-xz
+[minitar]: https://github.com/halostatue/minitar

data/lib/xz/fiddle_helper.rb

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+#--
+# Basic liblzma-bindings for Ruby.
+#
+# Copyright © 2011-2018 Marvin Gülker et al.
+#
+# See AUTHORS for the full list of contributors.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the ‘Software’),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the Software
+# is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+
+module XZ
+
+  # This is an internal API not meant for users of ruby-xz.
+  # This mixin modules defines some helper functions on top
+  # of Fiddle's functionality.
+  module FiddleHelper # :nodoc:
+
+    # Define constants that have numeric constants assigned as if
+    # it was a C enum definition. You can specificy values explicitely
+    # or rely on the implicit incrementation; the first implicit value
+    # is zero.
+    #
+    # Example:
+    #
+    #   enum :FOO, :BAR, 5, :BAZ
+    #
+    # This defines a constant FOO with value 0, BAR with value 5, BAZ
+    # with value 6.
+    def enum(*args)
+      @next_enum_val = 0 # First value of an enum is 0 in C
+
+      args.each_cons(2) do |val1, val2|
+        next if val1.respond_to?(:to_int)
+
+        if val2.respond_to?(:to_int)
+          const_set(val1, val2.to_int)
+          @next_enum_val = val2.to_int + 1
+        else
+          const_set(val1, @next_enum_val)
+          @next_enum_val += 1
+        end
+      end
+
+      # Cater for the last element in case it is not an explicit
+      # value that has already been assigned above.
+      unless args.last.respond_to?(:to_int)
+        const_set(args.last, @next_enum_val)
+      end
+
+      @next_enum_val = 0
+      nil
+    end
+
+    # Try loading any of the given names as a shared
+    # object. Raises Fiddle::DLError if none can
+    # be opened.
+    def dlloadanyof(*names)
+      names.each do |name|
+        begin
+          dlload(name)
+        rescue Fiddle::DLError
+          # Continue with next one
+        else
+          # Success
+          return name
+        end
+      end
+
+      raise Fiddle::DLError, "Failed to open any of these shared object files: #{names.join(', ')}"
+    end
+
+  end
+
+end