seven_zip_ruby 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6cddf8386211bb8c27016b7bc9adc3e01397485c
-  data.tar.gz: 62bea191d4575a3788562ce06ac4354c71ac6d19
+  metadata.gz: ee5048a454954a7610658f10e463febaa31ecb93
+  data.tar.gz: 70cf302be7166790d2af569eb6b4a109d78934bc
 SHA512:
-  metadata.gz: 242528879f0d204d9f36542361ac2bac674ef5d1973ccd829fd8a1f8500b96fa4d896dbd0e21a9eb352d9f7e7a0d3edc1bd0b0a75f0ca1d2420584faf6570fc3
-  data.tar.gz: e65d5c645b9e7960e8268fa44d1e02e0cb0487caa6f29c6fd6d12bb73e1acc7fa1646073ecb4faa4fe3917cf09f7a04950ac769ee9a97186eda302371b6284c5
+  metadata.gz: 3d94b6a533f37ddae5ca51d8882289884494b7ed783dee966cf3b5e060d0f7c404096bfd2212dc0d29a32125075acfc4e7a11af82aca33eaf65d178b47b25300
+  data.tar.gz: 96635e6baac1b98fed6f7321b4cb039abeddc81f2dada7fcdfc6dd053be9c0a3125fe3d47852a4347fda0dee38b303132b81b9083b0b0b9f6ca27f1f417caa78

data/README.md

@@ -12,12 +12,8 @@ This extension calls the native library, 7z.dll or 7z.so, internally and it is i
 
 ## Examples
 
-**This is a beta version.**  
-The interfaces may be changed.
-
-If you have any comments about interface API, let me know please.
-
 ### Extract archive
+
 ```ruby
 File.open("filename.7z", "rb") do |file|
   SevenZipRuby::Reader.open(file) do |szr|
@@ -27,6 +23,7 @@ end
 ```
 
 You can also use handy method.
+
 ```ruby
 File.open("filename.7z", "rb") do |file|
   SevenZipRuby::Reader.extract_all(file, "path_to_dir")
@@ -34,6 +31,7 @@ end
 ```
 
 ### Show entries in archive
+
 ```ruby
 File.open("filename.7z", "rb") do |file|
   SevenZipRuby::Reader.open(file) do |szr|
@@ -45,6 +43,7 @@ end
 ```
 
 ### Extract encrypted archive
+
 ```ruby
 File.open("filename.7z", "rb") do |file|
   SevenZipRuby::Reader.open(file, { password: "Password String" }) do |szr|
@@ -53,6 +52,7 @@ File.open("filename.7z", "rb") do |file|
 end
 ```
 or
+
 ```ruby
 File.open("filename.7z", "rb") do |file|
   SevenZipRuby::Reader.extract_all(file, "path_to_dir", { password: "Password String" })
@@ -61,6 +61,7 @@ end
 
 
 ### Verify archive
+
 ```ruby
 File.open("filename.7z", "rb") do |file|
   SevenZipRuby::Reader.verify(file)
@@ -69,6 +70,7 @@ end
 ```
 
 ### Compress files
+
 ```ruby
 File.open("filename.7z", "wb") do |file|
   SevenZipRuby::Writer.open(file) do |szr|
@@ -77,6 +79,7 @@ File.open("filename.7z", "wb") do |file|
 end
 ```
 or
+
 ```ruby
 File.open("filename.7z", "wb") do |file|
   SevenZipRuby::Writer.add_directory(file, "dir")
@@ -118,10 +121,11 @@ File.open("filename.7z", "rb") do |file|
 end
 p data
 #  => File content is shown.
+```
 
 ### Create archive manually
 
-```
+```ruby
 File.open("filename.7z", "rb") do |file|
   SevenZipRuby::Writer.open(file) do |szr|
     szr.add_file "entry1.txt"
@@ -174,3 +178,10 @@ p(Time.now - start)
 ## License
 LGPL and unRAR license. Please refer to LICENSE.txt.
 
+## Releases
+
+* 1.1.0
+  Raise error when wrong password is specified.
+* 1.0.0  
+  Initial release.
+

data/ext/seven_zip_ruby/seven_zip_archive.cpp

@@ -756,6 +756,10 @@ VALUE ArchiveWriter::addItem(VALUE item)
 
 VALUE ArchiveWriter::compress(VALUE callback_proc)
 {
+    if (m_state == STATE_COMPRESSED){
+        return Qnil;
+    }
+
     checkStateToBeginOperation(STATE_OPENED);
     prepareAction();
     EventLoopThreadExecuter te(this);
@@ -1598,14 +1602,19 @@ extern "C" void Init_seven_zip_archive(void)
     rb_define_method_ext(cls, "level", WRITER_FUNC2(level, 0));
     rb_define_method_ext(cls, "solid=", WRITER_FUNC2(setSolid, 1));
     rb_define_method_ext(cls, "solid", WRITER_FUNC2(solid, 0));
+    rb_define_method_ext(cls, "solid?", WRITER_FUNC2(solid, 0));
     rb_define_method_ext(cls, "header_compression=", WRITER_FUNC2(setHeaderCompression, 1));
     rb_define_method_ext(cls, "header_compression", WRITER_FUNC2(headerCompression, 0));
+    rb_define_method_ext(cls, "header_compression?", WRITER_FUNC2(headerCompression, 0));
     rb_define_method_ext(cls, "header_encryption=", WRITER_FUNC2(setHeaderEncryption, 1));
     rb_define_method_ext(cls, "header_encryption", WRITER_FUNC2(headerEncryption, 0));
+    rb_define_method_ext(cls, "header_encryption?", WRITER_FUNC2(headerEncryption, 0));
     rb_define_method_ext(cls, "multi_threading=", WRITER_FUNC2(setMultiThreading, 1));
     rb_define_method_ext(cls, "multi_thread=", WRITER_FUNC2(setMultiThreading, 1));
     rb_define_method_ext(cls, "multi_threading", WRITER_FUNC2(multiThreading, 0));
+    rb_define_method_ext(cls, "multi_threading?", WRITER_FUNC2(multiThreading, 0));
     rb_define_method_ext(cls, "multi_thread", WRITER_FUNC2(multiThreading, 0));
+    rb_define_method_ext(cls, "multi_thread?", WRITER_FUNC2(multiThreading, 0));
 
 #undef WRITER_FUNC2
 #undef WRITER_FUNC

data/lib/seven_zip_ruby/exception.rb

@@ -3,5 +3,8 @@
 module SevenZipRuby
   class InvalidOperation < StandardError
   end
+
+  class InvalidArchive < StandardError
+  end
 end
 

data/lib/seven_zip_ruby/seven_zip_reader.rb

@@ -1,11 +1,100 @@
 require("stringio")
 
 module SevenZipRuby
+
+  # SevenZipReader reads 7zip archive and extract it.
+  #
+  # == Examples
+  # === Get archive information
+  #   # Archive property
+  #   File.open("filename.7z", "rb") do |file|
+  #     SevenZipRuby::Reader.open(file) do |szr|
+  #       info = szr.archive_property  # Return ArchiveInfo instance.
+  #     end
+  #   end
+  #
+  #   # Entry information
+  #   File.open("filename.7z", "rb") do |file|
+  #     SevenZipRuby::Reader.open(file) do |szr|
+  #       entries = szr.entries
+  #     end
+  #   end
+  #
+  # === Extract 7zip archive.
+  #   # Extract archive
+  #   File.open("filename.7z", "rb") do |file|
+  #     SevenZipRuby::Reader.open(file) do |szr|
+  #       szr.extract(:all, "path_to_dir")
+  #     end
+  #   end
+  #
+  #   # Extract encrypted archive
+  #   File.open("filename.7z", "rb") do |file|
+  #     SevenZipRuby::Reader.open(file, password: "Password String") do |szr|
+  #       szr.extract(:all, "path_to_dir")
+  #     end
+  #   end
+  #
+  #   # Extract only small files
+  #   File.open("filename.7z", "rb") do |file|
+  #     SevenZipRuby::Reader.open(file) do |szr|
+  #       small_files = szr.entries.select{ |i| i.file? && i.size < 1024 }
+  #       szr.extract(small_files, "path_to_dir")
+  #     end
+  #   end
+  #
+  #   # Extract archive on memory
+  #   archive_data = "....."
+  #   stream = StringIO.new(archive_data)
+  #   SevenZipRuby::Reader.open(stream) do |szr|
+  #     entry_data = szr.extract_data(:all)
+  #     # => [ "data", ... ]
+  #   end
+  #
+  # === Verify archive
+  #   File.open("filename.7z", "rb") do |file|
+  #     SevenZipRuby::Reader.verify(file)
+  #     # => true/false
+  #   end
   class SevenZipReader
     class << self
-      def open(*args, &block)
+      # Open 7zip archive to read.
+      #
+      # ==== Args
+      # +stream+ :: Input stream to read 7zip archive. <tt>stream.seek</tt> and <tt>stream.read</tt> are needed.
+      # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+      #
+      # ==== Examples
+      #   # Open archive
+      #   File.open("filename.7z", "rb") do |file|
+      #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+      #       # Read and extract archive.
+      #     end
+      #   end
+      #
+      #   # Open encrypted archive
+      #   File.open("filename.7z", "rb") do |file|
+      #     SevenZipRuby::SevenZipReader.open(file, password: "PasswordOfArchive") do |szr|
+      #       # Read and extract archive.
+      #     end
+      #   end
+      #
+      #   # Open without block.
+      #   File.open("filename.7z", "rb") do |file|
+      #     szr = SevenZipRuby::SevenZipReader.open(file)
+      #     # Read and extract archive.
+      #     szr.close
+      #   end
+      #
+      #   # Open archive on memory.
+      #   archive_data = "....."
+      #   stream = StringIO.new(archive_data)
+      #   SevenZipRuby::Reader.open(stream) do |szr|
+      #     szr.extract(:all, "path_to_dir")
+      #   end
+      def open(stream, param = {}, &block)  # :yield: szr
         szr = self.new
-        szr.open(*args)
+        szr.open(stream, param)
         if (block)
           block.call(szr)
           szr.close
@@ -14,6 +103,26 @@ module SevenZipRuby
         end
       end
 
+      # Open and extract 7zip archive.
+      #
+      # ==== Args
+      # +stream+ :: Input stream to read 7zip archive. <tt>stream.seek</tt> and <tt>stream.read</tt> are needed, such as <tt>File</tt> and <tt>StringIO</tt>.
+      # +index+ :: Index of the entry to extract. Integer or Array of Integer can be specified.
+      # +dir+ :: Directory to extract the archive to.
+      # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+      #
+      # ==== Examples
+      #   File.open("filename.7z", "rb") do |file|
+      #     SevenZipRuby::SevenZipReader.extract(file, 1, "path_to_dir")
+      #   end
+      #
+      #   File.open("filename.7z", "rb") do |file|
+      #     SevenZipRuby::SevenZipReader.extract(file, [1, 2, 4], "path_to_dir", password: "PasswordOfArchive")
+      #   end
+      #
+      #   File.open("filename.7z", "rb") do |file|
+      #     SevenZipRuby::SevenZipReader.extract(file, :all, "path_to_dir")
+      #   end
       def extract(stream, index, dir = ".", param = {})
         password = { password: param.delete(:password) }
         self.open(stream, password) do |szr|
@@ -21,6 +130,17 @@ module SevenZipRuby
         end
       end
 
+      # Open and extract 7zip archive.
+      #
+      # ==== Args
+      # +stream+ :: Input stream to read 7zip archive. <tt>stream.seek</tt> and <tt>stream.read</tt> are needed.
+      # +dir+ :: Directory to extract the archive to.
+      # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+      #
+      # ==== Examples
+      #   File.open("filename.7z", "rb") do |file|
+      #     SevenZipRuby::SevenZipReader.extract_all(file, "path_to_dir")
+      #   end
       def extract_all(stream, dir = ".", param = {})
         password = { password: param.delete(:password) }
         self.open(stream, password) do |szr|
@@ -28,14 +148,38 @@ module SevenZipRuby
         end
       end
 
-      def verify(*args)
-        szr = self.open(*args)
+      # Open and verify 7zip archive.
+      #
+      # ==== Args
+      # +stream+ :: Input stream to read 7zip archive. <tt>stream.seek</tt> and <tt>stream.read</tt> are needed.
+      # +opt+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+      #
+      # ==== Examples
+      #   File.open("filename.7z", "rb") do |file|
+      #     ret = SevenZipRuby::SevenZipReader.verify(file)
+      #     # => true/false
+      #   end
+      def verify(stream, opt = {})
+        szr = self.open(stream, opt)
         ret = szr.verify
         szr.close
         return ret
       end
     end
 
+    # Open 7zip archive.
+    #
+    # ==== Args
+    # +stream+ :: Input stream to read 7zip archive. <tt>stream.seek</tt> and <tt>stream.read</tt> are needed.
+    # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "rb") do |file|
+    #     szr = SevenZipRuby::SevenZipReader.new
+    #     szr.open(file)
+    #     # ...
+    #     szr.close
+    #   end
     def open(stream, param = {})
       param[:password] = param[:password].to_s if (param[:password])
       stream.set_encoding(Encoding::ASCII_8BIT)
@@ -43,61 +187,18 @@ module SevenZipRuby
       return self
     end
 
-
-    def file_proc(base_dir)
-      base_dir = base_dir.to_s
-      return Proc.new do |type, arg|
-        case(type)
-        when :stream
-          ret = nil
-          if (arg.anti?)
-            arg.path.rmtree if (arg.path.exist?)
-          elsif (arg.file?)
-            path = arg.path.expand_path(base_dir)
-            path.parent.mkpath
-            ret = File.open(path, "wb")
-          else
-            path = arg.path.expand_path(base_dir)
-            path.mkpath
-            set_file_attribute(path.to_s, arg.attrib) if (arg.attrib)
-            path.utime(arg.atime || path.atime, arg.mtime || path.mtime)
-          end
-          next ret
-
-        when :result
-          arg[:stream].close
-          unless (arg[:info].anti?)
-            path = arg[:info].path.expand_path(base_dir)
-            set_file_attribute(path.to_s, arg[:info].attrib) if (arg[:info].attrib)
-            path.utime(arg[:info].atime || path.atime, arg[:info].mtime || path.mtime)
-          end
-        end
-      end
-    end
-    private :file_proc
-
-    def data_proc(output, idx_prj)
-      return Proc.new do |type, arg|
-        case(type)
-        when :stream
-          ret = (arg.has_data? ? StringIO.new("".b) : nil)
-          unless (arg.has_data?)
-            output[idx_prj[arg.index]] = nil
-          end
-          next ret
-
-        when :result
-          arg[:stream].close
-          if (arg[:info].has_data?)
-            output[idx_prj[arg[:info].index]] = arg[:stream].string
-          end
-
-        end
-      end
-    end
-    private :data_proc
-
-
+    # Verify 7zip archive.
+    #
+    # ==== Args
+    # none
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       ret = szr.verify
+    #       # => true/false
+    #     end
+    #   end
     def test
       begin
         return test_all_impl(nil)
@@ -107,6 +208,18 @@ module SevenZipRuby
     end
     alias verify test
 
+    # Verify 7zip archive and return the result of each entry.
+    #
+    # ==== Args
+    # none
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       ret = szr.verify_detail
+    #       # => [ true, :DataError, :DataError, ... ]
+    #     end
+    #   end
     def verify_detail
       begin
         return test_all_impl(true)
@@ -115,6 +228,24 @@ module SevenZipRuby
       end
     end
 
+    # Extract some entries of 7zip archive to local directory.
+    #
+    # ==== Args
+    # +index+ :: Index of the entry to extract. Integer or Array of Integer can be specified.
+    # +dir+ :: Directory to extract the archive to.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       szr.extract([ 1, 2, 4 ], "path_to_dir")
+    #     end
+    #   end
+    #
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       szr.extract(:all, "path_to_dir")
+    #     end
+    #   end
     def extract(index, dir = ".")
       path = File.expand_path(dir)
       case(index)
@@ -129,14 +260,62 @@ module SevenZipRuby
       end
     end
 
+    # Extract all entries of 7zip archive to local directory.
+    #
+    # ==== Args
+    # +dir+ :: Directory to extract the archive to.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       szr.extract_all("path_to_dir")
+    #     end
+    #   end
     def extract_all(dir = ".")
       extract_all_impl(file_proc(File.expand_path(dir)))
     end
 
-    def extract_if(dir = ".", &block)
+    # Extract entires of 7zip archive to local directory based on the block return value.
+    #
+    # ==== Args
+    # +dir+ :: Directory to extract the archive to.
+    #
+    # ==== Examples
+    #   # Extract files whose size is less than 1024.
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       szr.extract_if("path_to_dir") do |entry|
+    #         next entry.size < 1024
+    #       end
+    #     end
+    #   end
+    def extract_if(dir = ".", &block)  # :yield: entry_info
       extract(entries.select(&block).map(&:index), dir)
     end
 
+    # Extract some entries of 7zip archive and return the extracted data.
+    #
+    # ==== Args
+    # +index+ :: Index of the entry to extract. :all, Integer or Array of Integer can be specified.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       small_entries = szr.entries.select{ |i| i.size < 1024 }
+    #
+    #       data_list = szr.extract_data(small_entries)
+    #       # => [ "file contents1", "file contents2", ... ]
+    #     end
+    #   end
+    #
+    #   File.open("filename.7z", "rb") do |file|
+    #     SevenZipRuby::SevenZipReader.open(file) do |szr|
+    #       largest_entry = szr.entries.max_by{ |i| i.file? ? i.size : 0 }
+    #
+    #       data_list = szr.extract_data(largest_entry)
+    #       # => "file contents..."
+    #     end
+    #   end
     def extract_data(index)
       case(index)
       when :all
@@ -173,8 +352,67 @@ module SevenZipRuby
 
       end
     end
+
+
+    def file_proc(base_dir)  # :nodoc:
+      base_dir = base_dir.to_s
+      return Proc.new do |type, arg|
+        case(type)
+        when :stream
+          ret = nil
+          if (arg.anti?)
+            arg.path.rmtree if (arg.path.exist?)
+          elsif (arg.file?)
+            path = arg.path.expand_path(base_dir)
+            path.parent.mkpath
+            ret = File.open(path, "wb")
+          else
+            path = arg.path.expand_path(base_dir)
+            path.mkpath
+            set_file_attribute(path.to_s, arg.attrib) if (arg.attrib)
+            path.utime(arg.atime || path.atime, arg.mtime || path.mtime)
+          end
+          next ret
+
+        when :result
+          arg[:stream].close
+          raise InvalidArchive.new("Corrupted archive or invalid password") unless (arg[:success])
+
+          unless (arg[:info].anti?)
+            path = arg[:info].path.expand_path(base_dir)
+            set_file_attribute(path.to_s, arg[:info].attrib) if (arg[:info].attrib)
+            path.utime(arg[:info].atime || path.atime, arg[:info].mtime || path.mtime)
+          end
+        end
+      end
+    end
+    private :file_proc
+
+    def data_proc(output, idx_prj)  # :nodoc:
+      return Proc.new do |type, arg|
+        case(type)
+        when :stream
+          ret = (arg.has_data? ? StringIO.new("".b) : nil)
+          unless (arg.has_data?)
+            output[idx_prj[arg.index]] = nil
+          end
+          next ret
+
+        when :result
+          arg[:stream].close
+          raise InvalidArchive.new("Corrupted archive or invalid password") unless (arg[:success])
+
+          if (arg[:info].has_data?)
+            output[idx_prj[arg[:info].index]] = arg[:stream].string
+          end
+
+        end
+      end
+    end
+    private :data_proc
   end
 
 
+  # +Reader+ is an alias of +SevenZipReader+.
   Reader = SevenZipReader
 end

data/lib/seven_zip_ruby/seven_zip_writer.rb

@@ -1,11 +1,77 @@
 require("stringio")
 
 module SevenZipRuby
+
+  # SevenZipWriter creates 7zip archive.
+  #
+  # == Properties
+  # +method+ :: Compression method. "LZMA", "LZMA2", "PPMd", "BZIP2", "DEFLATE" or "COPY". Default value is "LZMA".
+  # +level+ :: Compression level. 0, 1, 3, 5, 7 or 9. Default value is 5.
+  # +solid+ :: Solid compression. <tt>true</tt> or <tt>false</tt>. Default value is <tt>true</tt>.
+  # +header_compression+ :: Header compression. <tt>true</tt> or <tt>false</tt>. Default value is <tt>true</tt>.
+  # +header_encryption+ :: Header encryption. <tt>true</tt> or <tt>false</tt>. Default value is <tt>false</tt>.
+  # +multi_threading+ :: Multi threading. <tt>true</tt> or <tt>false</tt>. Default value is <tt>true</tt>.
+  #
+  # == Examples
+  # === Compress files
+  #   # Compress files
+  #   File.open("filename.7z", "wb") do |file|
+  #     SevenZipRuby::SevenZipWriter.open(file) do |szw|
+  #       szw.add_directory("test_dir")
+  #       szw.add_file("test.txt")
+  #     end
+  #   end
+  #
+  #   stream = StringIO.new("")
+  #   SevenZipRuby::SevenZipWriter.open(stream) do |szw|
+  #     szw.add_file("test.txt")
+  #     szw.add_data(data, "test.bin")
+  #   end
+  #   # p stream.string
+  #
+  # === Set various properties
+  #   File.open("filename.7z", "wb") do |file|
+  #     SevenZipRuby::SevenZipWriter.open(file, password: "Password") do |szw|
+  #       szw.method = "LZMA"
+  #       szw.level = 9
+  #       szw.solid = false
+  #       szw.header_compression = false
+  #       szw.header_encryption = true
+  #       szw.multi_threading = false
+  #
+  #       szw.add_directory("test_dir")
+  #     end
+  #   end
   class SevenZipWriter
+    # Encoding used for path string in 7zip archive.
     PATH_ENCODING = Encoding::UTF_8
 
     class << self
-      def open(stream, param = {}, &block)
+      # Open 7zip archive to write.
+      #
+      # ==== Args
+      # +stream+ :: Output stream to write 7zip archive. <tt>stream.write</tt> is needed.
+      # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+      #
+      # ==== Examples
+      #   # Open archive
+      #   File.open("filename.7z", "wb") do |file|
+      #     SevenZipRuby::SevenZipWriter.open(file) do |szw|
+      #       # Create archive.
+      #       # ...
+      #       # You don't have to call szw.compress. Of cource, you may call it.
+      #       # szw.compress
+      #     end
+      #   end
+      #
+      #   # Open without block.
+      #   File.open("filename.7z", "wb") do |file|
+      #     szw = SevenZipRuby::SevenZipWriter.open(file)
+      #     # Create archive.
+      #     szw.compress  # Compress must be called in this case.
+      #     szw.close
+      #   end
+      def open(stream, param = {}, &block)  # :yield: szw
         szw = self.new
         szw.open(stream, param)
         if (block)
@@ -17,14 +83,38 @@ module SevenZipRuby
         end
       end
 
+      # Create 7zip archive which includes the specified directory recursively.
+      #
+      # ==== Args
+      # +stream+ :: Output stream to write 7zip archive. <tt>stream.write</tt> is needed.
+      # +dir+ :: Directory to be added to the 7zip archive. <b><tt>dir</tt></b> must be a <b>relative path</b>.
+      # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+      #
+      # ==== Examples
+      #   # Create 7zip archive which includes 'dir'.
+      #   File.open("filename.7z", "wb") do |file|
+      #     SevenZipRuby::SevenZipWriter.add_directory(file, 'dir')
+      #   end
       def add_directory(stream, dir, param = {})
         password = { password: param.delete(:password) }
         self.open(stream, password) do |szw|
           szw.add_directory(dir, param)
         end
       end
-      alias add_dir add_directory
+      alias add_dir add_directory  # +add_dir+ is an alias of +add_directory+.
 
+      # Create 7zip archive which includes the specified file recursively.
+      #
+      # ==== Args
+      # +stream+ :: Output stream to write 7zip archive. <tt>stream.write</tt> is needed.
+      # +file+ :: File to be added to the 7zip archive. <b><tt>file</tt></b> must be a <b>relative path</b>.
+      # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+      #
+      # ==== Examples
+      #   # Create 7zip archive which includes 'file.txt'.
+      #   File.open("filename.7z", "wb") do |file|
+      #     SevenZipRuby::SevenZipWriter.add_file(file, 'file.txt')
+      #   end
       def add_file(stream, filename, param = {})
         password = { password: param.delete(:password) }
         self.open(stream, password) do |szw|
@@ -33,17 +123,69 @@ module SevenZipRuby
       end
     end
 
+    # Open 7zip archive to create.
+    #
+    # ==== Args
+    # +stream+ :: Output stream to write 7zip archive. <tt>stream.write</tt> is needed.
+    # +param+ :: Optional hash parameter. <tt>:password</tt> key represents password of this archive.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "wb") do |file|
+    #     szw = SevenZipRuby::SevenZipWriter.open(file)
+    #     # ...
+    #     szw.compress
+    #     szw.close
+    #   end
     def open(stream, param = {})
       stream.set_encoding(Encoding::ASCII_8BIT)
       open_impl(stream, param)
       return self
     end
 
+    # Compress and output data to archive file.
+    # You don't have to call this method when you use block-style SevenZipWriter.open.
+    #
+    # ==== Examples
+    #  # Open archive
+    #  File.open("filename.7z", "wb") do |file|
+    #    SevenZipRuby::SevenZipWriter.open(file) do |szw|
+    #      # Create archive.
+    #      # ...
+    #      # You don't have to call szw.compress. Of cource, you may call it.
+    #      # szw.compress
+    #    end
+    #  end
+    #
+    #  # Open without block.
+    #  File.open("filename.7z", "wb") do |file|
+    #    szw = SevenZipRuby::SevenZipWriter.open(file)
+    #    # Create archive.
+    #    szw.compress  # Compress must be called in this case.
+    #    szw.close
+    #  end
     def compress
       compress_impl(compress_proc)
       return self
     end
 
+    # Add file entry to 7zip archive.
+    #
+    # ==== Args
+    # +filename+ :: File to be added to the 7zip archive. <tt>file</tt> must be a <b>relative path</b> if <tt>:as</tt> option is not specified.
+    # +opt+ :: Optional hash parameter. <tt>:as</tt> key represents filename used in this archive.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "wb") do |file|
+    #     SevenZipRuby::SevenZipWriter.open(file) do |szw|
+    #       # Add file entry 'test.txt' in 7zip archive.
+    #       # This entry has the contents of the local file 'test.txt'.
+    #       szw.add_file("test.txt")
+    #
+    #       # Add file entry 'desk/test.txt' in 7zip archive.
+    #       # This entry has the contents of the local file 'C:/Users/test/Desktop/test2.txt'.
+    #       szw.add_file("C:/Users/test/Desktop/test2.txt", as: "desk/test.txt")
+    #     end
+    #   end
     def add_file(filename, opt={})
       path = Pathname(filename)
       check_option(opt, [ :as ])
@@ -60,6 +202,23 @@ module SevenZipRuby
       return self
     end
 
+    # Add file entry to 7zip archive.
+    #
+    # ==== Args
+    # +data+ :: Data to be added to the 7zip archive.
+    # +filename+ :: File name of the entry to be added to the 7zip archive. <tt>filename</tt> must be a <b>relative path</b>.
+    # +opt+ :: Optional hash parameter. <tt>:ctime</tt>, <tt>:atime</tt> and <tt>:mtime</tt> keys can be specified as timestamp.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "wb") do |file|
+    #     SevenZipRuby::SevenZipWriter.open(file) do |szw|
+    #       data = "1234567890"
+    #
+    #       # Add file entry 'data.bin' in 7zip archive.
+    #       # This entry has the contents "1234567890".
+    #       szw.add_data(data, "data.bin")
+    #     end
+    #   end
     def add_data(data, filename, opt={})
       path = Pathname(filename)
       raise ArgumentError.new("filename should be relative") if (path.absolute?)
@@ -70,6 +229,22 @@ module SevenZipRuby
       return self
     end
 
+    # Add directory and files recursively to 7zip archive.
+    #
+    # ==== Args
+    # +directory+ :: Directory to be added to the 7zip archive. <tt>directory</tt> must be a <b>relative path</b> if <tt>:as</tt> option is not specified.
+    # +opt+ :: Optional hash parameter. <tt>:as</tt> key represents directory name used in this archive.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "wb") do |file|
+    #     SevenZipRuby::SevenZipWriter.open(file) do |szw|
+    #       # Add "dir1" and entries under "dir" recursively.
+    #       szw.add_directory("dir1")
+    #
+    #       # Add "C:/Users/test/Desktop/dir" and entries under it recursively.
+    #       szw.add_directory("C:/Users/test/Desktop/dir", as: "test/dir")
+    #     end
+    #   end
     def add_directory(directory, opt={})
       directory = Pathname(directory).cleanpath
       check_option(opt, [ :as ])
@@ -100,8 +275,21 @@ module SevenZipRuby
 
       return self
     end
-    alias add_dir add_directory
+    alias add_dir add_directory  # +add_dir+ is an alias of +add_directory+.
 
+    # Add an entry of empty directory to 7zip archive.
+    #
+    # ==== Args
+    # +directory_name+ :: Directory name to be added to 7z archive.
+    # +opt+ :: Optional hash parameter. <tt>:ctime</tt>, <tt>:atime</tt> and <tt>:mtime</tt> keys can be specified as timestamp.
+    #
+    # ==== Examples
+    #   File.open("filename.7z", "wb") do |file|
+    #     SevenZipRuby::SevenZipWriter.open(file) do |szw|
+    #       # Add an empty directory "dir1".
+    #       szw.mkdir("dir1")
+    #     end
+    #   end
     def mkdir(directory_name, opt={})
       path = Pathname(directory_name)
       raise ArgumentError.new("directory_name should be relative") if (path.absolute?)
@@ -113,13 +301,13 @@ module SevenZipRuby
     end
 
 
-    def check_option(opt, keys)
+    def check_option(opt, keys)  # :nodoc:
       invalid_keys = opt.keys - keys
       raise ArgumentError.new("invalid option: " + invalid_keys.join(", ")) unless (invalid_keys.empty?)
     end
+    private :check_option
 
-
-    def compress_proc
+    def compress_proc  # :nodoc:
       return Proc.new do |type, info|
         case(type)
         when :stream
@@ -139,5 +327,6 @@ module SevenZipRuby
   end
 
 
+  # +Writer+ is an alias of +SevenZipWriter+.
   Writer = SevenZipWriter
 end

data/lib/seven_zip_ruby/version.rb

@@ -1,3 +1,3 @@
 module SevenZipRuby
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/spec/seven_zip_ruby_spec.rb

@@ -158,6 +158,16 @@ describe SevenZipRuby do
         end
       end
 
+      example "invalid password" do
+        File.open(SevenZipRubySpecHelper::SEVEN_ZIP_PASSWORD_FILE, "rb") do |file|
+          expect{ SevenZipRuby::Reader.open(file){ |szr| szr.extract_data(1) } }.to raise_error
+        end
+
+        File.open(SevenZipRubySpecHelper::SEVEN_ZIP_PASSWORD_FILE, "rb") do |file|
+          expect{ SevenZipRuby::Reader.open(file, password: "a"){ |szr| szr.extract_data(1) } }.to raise_error
+        end
+      end
+
       example "raise error in open" do
         error = StandardError.new
 
@@ -265,6 +275,7 @@ describe SevenZipRuby do
         szw.add_data("This is hoge.txt content.", "hoge.txt")
         szw.add_data("This is hoge2.txt content.", "hoge2.txt")
         szw.mkdir("hoge/hoge/hoge")
+        szw.compress
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: seven_zip_ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Masamitsu MURASE
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-30 00:00:00.000000000 Z
+date: 2013-12-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -811,7 +811,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.2
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: This is a gem library to read and write 7-Zip files.