Bumped version to 1.0.0; updated README and GETTING_STARTED; added podspec

2015-09-09 20:28:10 +02:00
parent 6e0a47fc64
commit dbd1e5962f
27 changed files with 218 additions and 104 deletions
@@ -11,29 +11,40 @@ the zip wrapping.
 Adding Objective-Zip to your project
 ------------------------------------

-The library is distributed as source only, so simply download the unit
-test application and copy-paste these directories in your own project:
+The library is distributed via CocoaPods, you can add a dependency in you pod
+file with the following line:

- ARCHelper
- ZLib
- MiniZip
- Objective-Zip
+    pod 'Objective-Zip', '~> 1.0'

-The first two are simply copies of the distribution of version 1.2.7 of
-ZLib and of version 1.1 of MiniZip (which is itself part of ZLib
-contributions), while the third is their Objective-C wrapper.
+You can then access Objective-Zip classes with the following import
+statement if you plan to use exception handling:
+
+```objective-c
+#import "Objective-Zip.h"
+```
+
+Alternatively you can use the following import statement if you plan to use
+Apple's NSError pattern:
+
+```objective-c
+#import "Objective-Zip+NSError.h"
+```
+
+More on error handling at the end of this document.


 Main concepts
 -------------

 Objective-Zip is centered on a class called (with a lack of fantasy)
-ZipFile. It can be created with the common Objective-C procedure of an
+OZZipFile. It can be created with the common Objective-C procedure of an
 alloc followed by an init, specifying in the latter if the zip file is
 being created, appended or unzipped:

-	ZipFile *zipFile= [[ZipFile alloc] initWithFileName:@"test.zip"
-		mode:ZipFileModeCreate];
+```objective-c
+OZZipFile *zipFile= [[OZZipFile alloc] initWithFileName:@"test.zip"
+    mode:OZZipFileModeCreate];
+```

 Creating and appending are both write-only modalities, while unzipping
 is a read-only modality. You can not request reading operations on a
@@ -46,36 +57,40 @@ Adding a file to a zip file

 The ZipFile class has a couple of methods to add new files to a zip
 file, one of which keeps the file in clear and the other encrypts it
-with a password. Both methods return an instance of a ZipWriteStream
+with a password. Both methods return an instance of a OZZipWriteStream
 class, which will be used solely for the scope of writing the content of
 the file, and then must be closed:

-	ZipWriteStream *stream= [zipFile writeFileInZipWithName:@"abc.txt"
-		compressionLevel:ZipCompressionLevelBest];
+```objective-c
+OZZipWriteStream *stream= [zipFile writeFileInZipWithName:@"abc.txt"
+    compressionLevel:OZZipCompressionLevelBest];

-	[stream writeData:abcData];
-	[stream finishedWriting];
+[stream writeData:abcData];
+[stream finishedWriting];
+```


 Reading a file from a zip file
 ------------------------------

-The ZipFile class, when used in unzip mode, must be treated like a
+The OZZipFile class, when used in unzip mode, must be treated like a
 cursor: you position the instance on a file at a time, either by
 step-forwarding or by locating the file by name. Once you are on the
-correct file, you can obtain an instance of a ZipReadStream that will
+correct file, you can obtain an instance of a OZZipReadStream that will
 let you read the content (and then must be closed):

-	ZipFile *unzipFile= [[ZipFile alloc] initWithFileName:@"test.zip"
-		mode:ZipFileModeUnzip];
+```objective-c
+OZZipFile *unzipFile= [[OZZipFile alloc] initWithFileName:@"test.zip"
+    mode:OZZipFileModeUnzip];

-	[unzipFile goToFirstFileInZip];
+[unzipFile goToFirstFileInZip];

-	ZipReadStream *read= [unzipFile readCurrentFileInZip];
-	NSMutableData *data= [[NSMutableData alloc] initWithLength:256];
-	int bytesRead= [read readDataWithBuffer:data];
+OZZipReadStream *read= [unzipFile readCurrentFileInZip];
+NSMutableData *data= [[NSMutableData alloc] initWithLength:256];
+int bytesRead= [read readDataWithBuffer:data];

-	[read finishedReading];
+[read finishedReading];
+```

 Note that the NSMutableData instance that acts as the read buffer must
 have been set with a length greater than 0: the readDataWithBuffer API
@@ -91,25 +106,27 @@ contained in zip by filling an NSArray with instances of FileInZipInfo
 class. You can then use its name property to locate the file inside the
 zip and expand it:

-	ZipFile *unzipFile= [[ZipFile alloc] initWithFileName:@"test.zip"
-		mode:ZipFileModeUnzip];
+```objective-c
+OZZipFile *unzipFile= [[OZZipFile alloc] initWithFileName:@"test.zip"
+    mode:ZipFileModeUnzip];

-	NSArray *infos= [unzipFile listFileInZipInfos];
-	for (FileInZipInfo *info in infos) {
-		NSLog(@"- %@ %@ %d (%d)", info.name, info.date, info.size,
-    		info.level);
+NSArray *infos= [unzipFile listFileInZipInfos];
+for (OZFileInZipInfo *info in infos) {
+    NSLog(@"- %@ %@ %d (%d)", info.name, info.date, info.size,
+        info.level);

-		// Locate the file in the zip
-		[unzipFile locateFileInZip:info.name];
+    // Locate the file in the zip
+    [unzipFile locateFileInZip:info.name];

-		// Expand the file in memory
-		ZipReadStream *read= [unzipFile readCurrentFileInZip];
-		NSMutableData *data= [[NSMutableData alloc] initWithLength:256];
-		int bytesRead= [read readDataWithBuffer:data];
-		[read finishedReading];
-	}
+    // Expand the file in memory
+    OZZipReadStream *read= [unzipFile readCurrentFileInZip];
+    NSMutableData *data= [[NSMutableData alloc] initWithLength:256];
+    int bytesRead= [read readDataWithBuffer:data];
+    [read finishedReading];
+}
+```

-Note that the FileInZipInfo class provide two sizes:
+Note that the OZFileInZipInfo class provide two sizes:

 - **length** is the original (uncompressed) file size, while
 - **size** is the compressed file size.
@@ -118,10 +135,12 @@ Note that the FileInZipInfo class provide two sizes:
 Closing the zip file
 --------------------

-Remember, when you are done, to close your ZipFile instance to avoid
+Remember, when you are done, to close your OZZipFile instance to avoid
 file corruption problems:

-	[zipFile close];
+```objective-c
+[zipFile close];
+```


 Notes
@@ -134,9 +153,9 @@ File/folder hierarchy inide the zip
 Please note that inside the zip files there is no representation of a
 file-folder hierarchy: it is simply embedded in file names (i.e.: a file
 with a name like "x/y/z/file.txt"). It is up to the program that
-extracts the files to consider these file names as expressing a
-structure and rebuild it on the file system (and viceversa during
-creation). Common zippers/unzippers simply follow this rule.
+extracts files to consider these file names as expressing a structure and
+rebuild it on the file system (and viceversa during creation). Common
+zippers/unzippers simply follow this rule.


 Memory management
@@ -145,42 +164,69 @@ Memory management
 If you need to extract huge files that cannot be contained in memory,
 you can do so using a read-then-write buffered loop like this:

-	NSFileHandle *file= [NSFileHandle fileHandleForWritingAtPath:filePath];
-	NSMutableData *buffer= [[NSMutableData alloc]
-		initWithLength:BUFFER_SIZE];
+```objective-c
+NSFileHandle *file= [NSFileHandle fileHandleForWritingAtPath:filePath];
+NSMutableData *buffer= [[NSMutableData alloc]
+    initWithLength:BUFFER_SIZE];

-	ZipReadStream *read= [unzipFile readCurrentFileInZip];
+OZZipReadStream *read= [unzipFile readCurrentFileInZip];

-	// Read-then-write buffered loop
-	do {
+// Read-then-write buffered loop
+do {

-		// Reset buffer length
-		[buffer setLength:BUFFER_SIZE];
+    // Reset buffer length
+    [buffer setLength:BUFFER_SIZE];

-		// Expand next chunk of bytes
-		int bytesRead= [read readDataWithBuffer:buffer];
-		if (bytesRead > 0) {
+    // Expand next chunk of bytes
+    int bytesRead= [read readDataWithBuffer:buffer];
+    if (bytesRead > 0) {

-			// Write what we have read
-			[buffer setLength:bytesRead];
-			[file writeData:buffer];
+        // Write what we have read
+        [buffer setLength:bytesRead];
+        [file writeData:buffer];

-		} else
-			break;
+    } else
+        break;

-	} while (YES);
+} while (YES);

-	// Clean up
-	[file closeFile];
-	[read finishedReading];
-	[buffer release];
+// Clean up
+[file closeFile];
+[read finishedReading];
+[buffer release];
+```


-Exception handling
------------------
+Error handling
+--------------

-If something goes wrong during an operation, Objective-Zip will always
-throw an exception of class ZipException, which contains a property with
-the specific error number of MiniZip. With that number you are supposed
-to find the reason of the error.
+Objective-Zip provides two kinds of error handling:
+
+- standard exception handling;
+- Apple's NSError pattern.
+
+With standard exception handling, Objective-Zip will throw an exception of
+class OZZipException any time an error occurs (programmer or runtime errors).
+
+To use standard exception handling import Objective-Zip in your project with
+this statement:
+
+```objective-c
+#import "Objective-Zip.h"
+```
+
+With Apple's NSError pattern, Objective-Zip will expect a NSError
+pointer-to-pointer argument and will fill it with an NSError instance
+whenever a runtime error occurs. Will revert to throwing an exception (of
+OZZipException class) in case of programmer errors.
+
+To use Apple's NSError pattern import Objective-Zip in your project with this
+statement:
+
+```objective-c
+#import "Objective-Zip+NSError.h"
+```
+
+Apple's NSError pattern is of course mandatory with Swift programming
+language, since it does not support exception handling.

@@ -0,0 +1,56 @@
+Pod::Spec.new do |s|
+
+  # ―――  Spec Metadata  ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+
+  s.name         = "Objective-Zip"
+  s.version      = "1.0.0"
+  s.summary      = "An object-oriented friendly wrapper library for ZLib and MiniZip, in Objective-C for iOS and OS X"
+
+  s.description  = <<-DESC
+                   Objective-Zip is a small Objective-C library that wraps ZLib and
+                   MiniZip in an object-oriented friendly way. It supports:
+
+                   * Zipping and unzipping of common zip file formats.
+                   * Multi-GB zip files thanks to 64-bit APIs, even with limited memory available.
+                   * Per-file compression level and encryption.
+
+                   Objective-Zip includes sources of latest versions of ZLib and MiniZip.
+                   DESC
+
+  s.homepage     = "https://github.com/gianlucabertani/Objective-Zip"
+
+
+  # ―――  Spec License  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+
+  s.license      = { :type => "BSD 2.0", :file => "LICENSE.md" }
+
+
+  # ――― Author Metadata  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+
+  s.author             = { "Gianluca Bertani" => "gianluca.bertani@email.it" }
+  s.social_media_url   = "https://twitter.com/self_vs_this"
+
+
+  # ――― Platform Specifics ――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+
+  s.ios.deployment_target = "5.1"
+  s.osx.deployment_target = "10.7"
+
+
+  # ――― Source Location ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+
+  s.source       = { :git => "https://github.com/gianlucabertani/Objective-Zip.git",
+                     :tag => s.version.to_s }
+
+
+  # ――― Source Code ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+
+  s.source_files  = "Objective-Zip/**/*.{h,m}", "MiniZip/**/*.{h,c}", "ZLib/**/*.{h,c}"
+
+
+  # ――― Project Settings ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+
+  s.requires_arc = true
+  s.xcconfig = { "OTHER_LDFLAGS" => "-ObjC" }
+
+end
@@ -1,6 +1,6 @@
 //
 //  OZFileInZipInfo+Internals.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/08/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZFileInZipInfo.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZFileInZipInfo.m
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipCompressionLevel.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/08/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipException+Internals.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/08/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipException.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 25/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipException.m
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 25/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipFile+NSError.h
-//  Objective-Zip
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 09/09/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipFile+Standard.h
-//  Objective-Zip
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 09/09/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipFile.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 25/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipFile.m
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 25/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipFileMode.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/08/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipReadStream+Internals.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/08/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipReadStream+NSError.h
-//  Objective-Zip
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 09/09/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipReadStream+Standard.h
-//  Objective-Zip
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 09/09/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipReadStream.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 28/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipReadStream.m
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 28/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipWriteStream+Internals.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/08/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipWriteStream+NSError.h
-//  Objective-Zip
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 09/09/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipWriteStream+Standard.h
-//  Objective-Zip
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 09/09/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipWriteStream.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 25/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  OZZipWriteStream.m
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 25/12/09.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  Objective-Zip+NSError.h
-//  Objective-Zip
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 09/09/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -1,6 +1,6 @@
 //
 //  Objective-Zip.h
-//  Objective-Zip v. 0.8.3
+//  Objective-Zip v. 1.0.0
 //
 //  Created by Gianluca Bertani on 27/08/15.
 //  Copyright 2009-2015 Gianluca Bertani. All rights reserved.
@@ -14,9 +14,8 @@ an object-oriented friendly way.
 What is contained here
 ----------------------

-The source repository contains a sample application with full
-sources for ZLib, MiniZip and Objective-Zip, together with a unit test
-UI. The versions included are:
+The source repository contains full sources for ZLib, MiniZip and
+Objective-Zip, together with some unit tests. The versions included are:

 - 1.2.8 for [ZLib](http://zlib.net).
 - 1.1 for [MiniZip](https://github.com/nmoinvaz/minizip).
@@ -32,7 +31,7 @@ informations.
 Getting started
 ---------------

-Please see [Getting Started](https://github.com/flyingdolphinstudio/Objective-Zip/blob/master/GETTING_STARTED.md).
+Please see [Getting Started](https://github.com/gianlucabertani/Objective-Zip/blob/master/GETTING_STARTED.md).


 License
@@ -44,6 +43,19 @@ The library is distributed under the New BSD License.
 Version history
 ---------------

+Version 1.0.0:
+
+- Added official podspec to distribute via CocoaPods.
+- Added API docs.
+- Added nullability annotations.
+- Refactored DIY tests as unit tests.
+- Added targets for static libraries.
+- Added alternative interfaces with NSError pattern in place of exceptions.
+- Added support for legacy 32-bit zip files.
+- Added class prefix "OZ" to make Objective-Zip a good citizen.
+- Fully ARC-ified (removed ARCHelper)
+- Some code clean-up.
+
 Version 0.8.3:

 - Finally used correctly the 64 bit APIs. Thanks to Nathan Moinvaziri for advicing.
@@ -91,7 +103,7 @@ Version 0.7.0:
 Compatibility
 -------------

-Version 0.8.3 has been tested with iOS from 5.1 to 6.1, but should be
-compatible with earlier versions too. Le me know of any issues that
-should arise.
+Version 1.0.0 has been tested with iOS up to 8.4.1 and OS X up to 10.10.5, but
+should be compatible with earlier versions too, down to iOS 5.1 and OS X 10.7.
+Le me know of any issues that should arise.