lib/symmetric_encryption/writer.rb in symmetric-encryption-0.5.2 vs lib/symmetric_encryption/writer.rb in symmetric-encryption-0.6.0

@@ -1,31 +1,15 @@
 module SymmetricEncryption
+  # Write to encrypted files and other IO streams
+  #
+  # Features:
+  # * Encryption on the fly whilst writing files.
+  # * Large file support by only buffering small amounts of data in memory
+  # * Underlying buffering to ensure that encrypted data fits
+  #   into the Symmetric Encryption Cipher block size
+  #   Only the last block in the file will be padded if it is less than the block size
   class Writer
-    # Write to encrypted files and other IO streams
-    #
-    # Features:
-    # * Encryption on the fly whilst writing files.
-    # * Large file support by only buffering small amounts of data in memory
-    # * Underlying buffering to ensure that encrypted data fits
-    #   into the Symmetric Encryption Cipher block size
-    #   Only the last block in the file will be padded if it is less than the block size
-    #
-    # # Example: Encrypt and write data to a file
-    # SymmetricEncryption::Writer.open('test_file') do |file|
-    #   file.write "Hello World\n"
-    #   file.write "Keep this secret"
-    # end
-    #
-    # # Example: Compress, Encrypt and write data to a file
-    # SymmetricEncryption::Writer.open('encrypted_compressed.zip', :compress => true) do |file|
-    #   file.write "Hello World\n"
-    #   file.write "Compress this\n"
-    #   file.write "Keep this safe and secure\n"
-    # end
-    #
-
-
     # Open a file for writing, or use the supplied IO Stream
     #
     # Parameters:
     #   filename_or_stream:
     #     The filename to open if a string, otherwise the stream to use
@@ -55,22 +39,45 @@
     #          See File.open for open modes
     #          Default: 'w'
     #
     # Note: Compression occurs before encryption
     #
+    #
+    # # Example: Encrypt and write data to a file
+    # SymmetricEncryption::Writer.open('test_file') do |file|
+    #   file.write "Hello World\n"
+    #   file.write "Keep this secret"
+    # end
+    #
+    # # Example: Compress, Encrypt and write data to a file
+    # SymmetricEncryption::Writer.open('encrypted_compressed.zip', :compress => true) do |file|
+    #   file.write "Hello World\n"
+    #   file.write "Compress this\n"
+    #   file.write "Keep this safe and secure\n"
+    # end
+    #
+    # # Example: Writing to a CSV file
+    #  require 'fastercsv'
+    #  begin
+    #    # Must supply :row_sep for FasterCSV otherwise it will attempt to read from and then rewind the file
+    #    csv = FasterCSV.new(SymmetricEncryption::Writer.open('csv_encrypted'), :row_sep => "\n")
+    #    csv << [1,2,3,4,5]
+    #  ensure
+    #    csv.close if csv
+    #  end
     def self.open(filename_or_stream, options={}, &block)
       raise "options must be a hash" unless options.respond_to?(:each_pair)
       mode = options.fetch(:mode, 'w')
       compress = options.fetch(:compress, false)
       ios = filename_or_stream.is_a?(String) ? ::File.open(filename_or_stream, mode) : filename_or_stream
 
       begin
         file = self.new(ios, options)
         file = Zlib::GzipWriter.new(file) if compress
-        block.call(file)
+        block ? block.call(file) : file
       ensure
-        file.close if file
+        file.close if block && file
       end
     end
 
     # Encrypt data before writing to the supplied stream
     def initialize(ios,options={})
@@ -110,9 +117,19 @@
     # Returns the number of bytes written
     def write(data)
       partial = @stream_cipher.update(data.to_s)
       @ios.write(partial) if partial.length > 0
       data.length
+    end
+
+    # Write to the IO Stream as encrypted data
+    # Returns self
+    #
+    # Example:
+    #   file << "Hello.\n" << "This is Jack"
+    def <<(data)
+      write(data)
+      self
     end
 
     private
 
     # Write the Encryption header if this is the first write