Merge branch 'release/1.2.0'

* release/1.2.0: (32 commits) Bump copyright years. Change framework version to 1.2.0. Update podspec to 1.2.0. Add compile time check of ARC and blocks. Update Xcode project. Fix ARC setting in podspec. Add podspec by @dwlnetnl (#13). Remove link to GitHub messages. Correctly handle path that contains spaces Made CDEvents class create CDEvent objects with file URLs instead of normal URLs (allows easier comparison with NSURL objects returned by eg. NSFileManager) Update README.mdown Fix contributors URL. Change the authors section in the readme. Update readme with link to new website. Ignore "docs" directory. Update readme to reflect online documentation. Add license file. Add script to generate documentation using appledoc. Update the read me to reflect the new changes. Update the test app to be able to use blocks API. ...
rastersize · Nov 21, 2012 · 08c19ee · 08c19ee
2 parents d560344 + 5beb7cd
commit 08c19ee
Show file tree

Hide file tree

Showing 14 changed files with 482 additions and 157 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -1,3 +1,2 @@
-*.pbxproj	binary
 *.m		diff=objc
 *.mm		diff=objc
diff --git a/.gitignore b/.gitignore
@@ -27,3 +27,4 @@ build
 *~.xib
 
 api
+docs
diff --git a/CDEvent.h b/CDEvent.h
@@ -1,7 +1,7 @@
 /**
  * CDEvents
  *
- * Copyright (c) 2010 Aron Cedercrantz
+ * Copyright (c) 2010-2012 Aron Cedercrantz
  * http://github.com/rastersize/CDEvents/
  *
  * Permission is hereby granted, free of charge, to any person
@@ -67,13 +67,7 @@ typedef FSEventStreamEventFlags CDEventFlags;
  *
  * @since 1.0.0
  */
-@interface CDEvent : NSObject <NSCoding, NSCopying> {
-@private
-	CDEventIdentifier			_identifier;
-	NSDate						*_date;
-	NSURL						*_URL;
-	CDEventFlags				_flags;
-}
+@interface CDEvent : NSObject <NSCoding, NSCopying> {}
 
 #pragma mark Properties
 /** @name Getting Event Properties */
@@ -95,7 +89,7 @@ typedef FSEventStreamEventFlags CDEventFlags;
  *
  * @since 1.0.0
  */
-@property (readonly) NSDate						*date;
+@property (unsafe_unretained, readonly) NSDate	*date;
 
 /**
  * The URL of the item which changed.
@@ -104,7 +98,7 @@ typedef FSEventStreamEventFlags CDEventFlags;
  *
  * @since 1.0.0
  */
-@property (readonly) NSURL						*URL;
+@property (unsafe_unretained, readonly) NSURL	*URL;
 
 
 /** @name Getting Event Flags */

diff --git a/CDEvent.m b/CDEvent.m
@@ -1,7 +1,7 @@
 /**
  * CDEvents
  *
- * Copyright (c) 2010 Aron Cedercrantz
+ * Copyright (c) 2010-2012 Aron Cedercrantz
  * http://github.com/rastersize/CDEvents/
  *
  * Permission is hereby granted, free of charge, to any person
@@ -44,22 +44,14 @@ + (CDEvent *)eventWithIdentifier:(NSUInteger)identifier
 							 URL:(NSURL *)URL
 						   flags:(CDEventFlags)flags
 {
-	return [[[CDEvent alloc] initWithIdentifier:identifier
+	return [[CDEvent alloc] initWithIdentifier:identifier
 										   date:date
 											URL:URL
-										  flags:flags]
-			autorelease];
+										  flags:flags];
 }
 
 
 #pragma mark Init/dealloc methods
-- (void)dealloc
-{
-	[_date release];
-	[_URL release];
-
-	[super dealloc];
-}
 
 - (id)initWithIdentifier:(NSUInteger)identifier
 					date:(NSDate *)date
@@ -69,8 +61,8 @@ - (id)initWithIdentifier:(NSUInteger)identifier
 	if ((self = [super init])) {
 		_identifier	= identifier;
 		_flags		= flags;
-		_date		= [date retain];
-		_URL		= [URL retain];
+		_date		= date;
+		_URL		= URL;
 	}
 
 	return self;
@@ -101,7 +93,7 @@ - (id)initWithCoder:(NSCoder *)aDecoder
 - (id)copyWithZone:(NSZone *)zone
 {
 	// We can do this since we are immutable.
-	return [self retain];
+	return self;
 }
 
 #pragma mark Specific flag properties 

diff --git a/CDEvents.h b/CDEvents.h
@@ -1,7 +1,7 @@
 /**
  * CDEvents
  *
- * Copyright (c) 2010 Aron Cedercrantz
+ * Copyright (c) 2010-2012 Aron Cedercrantz
  * http://github.com/rastersize/CDEvents/
  *
  * Permission is hereby granted, free of charge, to any person
@@ -94,6 +94,17 @@ extern const CDEventsEventStreamCreationFlags kCDEventsDefaultEventStreamFlags;
 extern const CDEventIdentifier kCDEventsSinceEventNow;
 
 
+#pragma mark -
+#pragma mark CDEvents Block Type
+@class CDEvents;
+/**
+ * Type of the block which gets called when an event occurs.
+ *
+ * @since head
+ */
+typedef void (^CDEventsEventBlock)(CDEvents *watcher, CDEvent *event);
+
+
 #pragma mark -
 #pragma mark CDEvents interface
 /**
@@ -105,23 +116,7 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
  *
  * @since 1.0.0
  */
-@interface CDEvents : NSObject <NSCopying> {
-@private
-	__weak id<CDEventsDelegate>	_delegate;
-
-	FSEventStreamRef			_eventStream;
-	CFTimeInterval				_notificationLatency;
-
-	CDEventIdentifier			_sinceEventIdentifier;
-	NSUInteger					_eventStreamCreationFlags;
-
-	BOOL						_ignoreEventsFromSubDirectories;
-
-	CDEvent						*_lastEvent;
-
-	NSArray						*_watchedURLs;
-	NSArray						*_excludedURLs;
-}
+@interface CDEvents : NSObject <NSCopying> {}
 
 #pragma mark Properties
 /** @name Managing the Delegate */
@@ -135,7 +130,17 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
  *
  * @since 1.0.0
  */
-@property (assign) __weak id<CDEventsDelegate>	delegate;
+@property (unsafe_unretained) id<CDEventsDelegate>	delegate;
+
+/** @name Getting Event Block */
+/**
+ * The event block.
+ *
+ * @return The CDEventsEventBlock block which is executed when an event occurs.
+ *
+ * @since head
+ */
+@property (readonly) CDEventsEventBlock				eventBlock;
 
 /** @name Getting Event Watcher Properties */
 /**
@@ -145,7 +150,7 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
  *
  * @since 1.0.0
  */
-@property (readonly) CFTimeInterval				notificationLatency;
+@property (readonly) CFTimeInterval					notificationLatency;
 
 /**
  * The event identifier from which events will be supplied to the delegate.
@@ -154,16 +159,16 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
  *
  * @since 1.0.0
  */
-@property (readonly) CDEventIdentifier			sinceEventIdentifier;
+@property (readonly) CDEventIdentifier				sinceEventIdentifier;
 
 /**
- * The last event that occured and thas has been delivered to the delegate.
+ * The last event that occured and has been delivered to the delegate.
  *
- * @return The last event that occured and thas has been delivered to the delegate.
+ * @return The last event that occured and has been delivered to the delegate.
  *
  * @since 1.0.0
  */
-@property (retain, readonly) CDEvent			*lastEvent;
+@property (strong, readonly) CDEvent				*lastEvent;
 
 /**
  * The URLs that we watch for events.
@@ -172,7 +177,7 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
  *
  * @since 1.0.0
  */
-@property (readonly) NSArray					*watchedURLs;
+@property (copy, readonly) NSArray					*watchedURLs;
 
 
 /** @name Configuring the Event watcher */
@@ -184,7 +189,7 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
  *
  * @since 1.0.0
  */
-@property (copy) NSArray						*excludedURLs;
+@property (copy) NSArray							*excludedURLs;
 
 /**
  * Wheter events from sub-directories of the watched URLs should be ignored or not.
@@ -194,7 +199,7 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
  *
  * @since 1.0.0
  */
-@property (assign) BOOL							ignoreEventsFromSubDirectories;
+@property (assign) BOOL								ignoreEventsFromSubDirectories;
 
 
 #pragma mark Event identifier class methods
@@ -211,8 +216,8 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
 + (CDEventIdentifier)currentEventIdentifier;
 
 
-#pragma mark Init methods
-/** @name Creating CDEvents Objects */
+#pragma mark Creating CDEvents Objects With a Delegate
+/** @name Creating CDEvents Objects With a Delegate */
 /**
  * Returns an <code>CDEvents</code> object initialized with the given URLs to watch.
  *
@@ -271,8 +276,6 @@ extern const CDEventIdentifier kCDEventsSinceEventNow;
 			delegate:(id<CDEventsDelegate>)delegate
 		  onRunLoop:(NSRunLoop *)runLoop;
 
-
-
 /**
  * Returns an <code>CDEvents</code> object initialized with the given URLs to watch, URLs to exclude, wheter events from sub-directories are ignored or not and schedules the watcher on the given run loop.
  *
@@ -311,6 +314,104 @@ ignoreEventsFromSubDirs:(BOOL)ignoreEventsFromSubDirs
 		 excludeURLs:(NSArray *)exludeURLs
  streamCreationFlags:(CDEventsEventStreamCreationFlags)streamCreationFlags;
 
+#pragma mark Creating CDEvents Objects With a Block
+/** @name Creating CDEvents Objects With a Block */
+/**
+ * Returns an <code>CDEvents</code> object initialized with the given URLs to watch.
+ *
+ * @param URLs An array of URLs we want to watch.
+ * @param block The block which the CDEvents object executes when it recieves an event.
+ * @return An CDEvents object initialized with the given URLs to watch. 
+ * @throws NSInvalidArgumentException if <em>URLs</em> is empty or points to <code>nil</code>.
+ * @throws NSInvalidArgumentException if <em>delegate</em>is <code>nil</code>.
+ * @throws CDEventsEventStreamCreationFailureException if we failed to create a event stream.
+ *
+ * @see initWithURLs:delegate:onRunLoop:
+ * @see initWithURLs:delegate:onRunLoop:sinceEventIdentifier:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
+ * @see CDEventsEventBlock
+ * @see kCDEventsDefaultEventStreamFlags
+ * @see kCDEventsSinceEventNow
+ *
+ * @discussion Calls initWithURLs:block:onRunLoop:sinceEventIdentifier:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
+ * with <code>sinceEventIdentifier</code> with the event identifier for "event
+ * since now", <code>notificationLatency</code> set to 3.0 seconds,
+ * <code>ignoreEventsFromSubDirectories</code> set to <code>NO</code>,
+ * <code>excludedURLs</code> to <code>nil</code>, the event stream creation
+ * flags will be set to <code>kCDEventsDefaultEventStreamFlags</code> and
+ * schedueled on the current run loop.
+ *
+ * @since head
+ */
+- (id)initWithURLs:(NSArray *)URLs block:(CDEventsEventBlock)block;
+
+/**
+ * Returns an <code>CDEvents</code> object initialized with the given URLs to watch and schedules the watcher on the given run loop.
+ *
+ * @param URLs An array of URLs we want to watch.
+ * @param block The block which the CDEvents object executes when it recieves an event.
+ * @param runLoop The run loop which the which the watcher should be schedueled on.
+ * @return An CDEvents object initialized with the given URLs to watch.
+ * @throws NSInvalidArgumentException if <em>URLs</em> is empty or points to <code>nil</code>.
+ * @throws NSInvalidArgumentException if <em>delegate</em>is <code>nil</code>.
+ * @throws CDEventsEventStreamCreationFailureException if we failed to create a event stream.
+ *
+ * @see initWithURLs:delegate:
+ * @see initWithURLs:delegate:onRunLoop:sinceEventIdentifier:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
+ * @see CDEventsEventBlock
+ * @see kCDEventsDefaultEventStreamFlags
+ * @see kCDEventsSinceEventNow
+ *
+ * @discussion Calls initWithURLs:delegate:onRunLoop:sinceEventIdentifier:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
+ * with <code>sinceEventIdentifier</code> with the event identifier for "event
+ * since now", <code>notificationLatency</code> set to 3.0 seconds,
+ * <code>ignoreEventsFromSubDirectories</code> set to <code>NO</code>,
+ * <code>excludedURLs</code> to <code>nil</code> and the event stream creation
+ * flags will be set to <code>kCDEventsDefaultEventStreamFlags</code>.
+ *
+ * @since head
+ */
+- (id)initWithURLs:(NSArray *)URLs
+			 block:(CDEventsEventBlock)block
+		 onRunLoop:(NSRunLoop *)runLoop;
+
+/**
+ * Returns an <code>CDEvents</code> object initialized with the given URLs to watch, URLs to exclude, wheter events from sub-directories are ignored or not and schedules the watcher on the given run loop.
+ *
+ * @param URLs An array of URLs (<code>NSURL</code>) we want to watch.
+ * @param block The block which the CDEvents object executes when it recieves an event.
+ * @param runLoop The run loop which the which the watcher should be schedueled on.
+ * @param sinceEventIdentifier Events that have happened after the given event identifier will be supplied.
+ * @param notificationLatency The (approximate) time intervall between notifications sent to the delegate.
+ * @param ignoreEventsFromSubDirs Wheter events from sub-directories of the watched URLs should be ignored or not.
+ * @param exludeURLs An array of URLs that we should ignore events from. Pass <code>nil</code> if none should be excluded.
+ * @param streamCreationFlags The event stream creation flags.
+ * @return An CDEvents object initialized with the given URLs to watch, URLs to exclude, wheter events from sub-directories are ignored or not and run on the given run loop.
+ * @throws NSInvalidArgumentException if the parameter URLs is empty or points to <code>nil</code>.
+ * @throws NSInvalidArgumentException if <em>delegate</em>is <code>nil</code>.
+ * @throws CDEventsEventStreamCreationFailureException if we failed to create a event stream.
+ *
+ * @see initWithURLs:delegate:
+ * @see initWithURLs:delegate:onRunLoop:
+ * @see ignoreEventsFromSubDirectories
+ * @see excludedURLs
+ * @see CDEventsEventBlock
+ * @see FSEventStreamCreateFlags
+ *
+ * @discussion To ask for events "since now" pass the return value of
+ * currentEventIdentifier as the parameter <code>sinceEventIdentifier</code>.
+ * CDEventStreamCreationFailureException should be extremely rare.
+ *
+ * @since head
+ */
+- (id)initWithURLs:(NSArray *)URLs
+			 block:(CDEventsEventBlock)block
+		 onRunLoop:(NSRunLoop *)runLoop
+sinceEventIdentifier:(CDEventIdentifier)sinceEventIdentifier
+notificationLantency:(CFTimeInterval)notificationLatency
+ignoreEventsFromSubDirs:(BOOL)ignoreEventsFromSubDirs
+	   excludeURLs:(NSArray *)exludeURLs
+streamCreationFlags:(CDEventsEventStreamCreationFlags)streamCreationFlags;
+
 #pragma mark Flush methods
 /** @name Flushing Events */
 /**