Create a centralized configuration API

CHANGELOG.md

@@ -14,6 +14,7 @@
 - [ASCollectionNode] Added support for interactive item movement. [Adlai Holler](https://github.com/Adlai-Holler)
 - Added an experimental "no-copy" rendering API. See ASGraphicsContext.h for info. [Adlai Holler](https://github.com/Adlai-Holler)
 - Dropped support for iOS 8. [Adlai Holler](https://github.com/Adlai-Holler)
+- Added a configuration API – a unified place to turn on/off experimental Texture features. See `ASConfiguration.h` for info. [Adlai Holler](https://github.com/Adlai-Holler)
 - Removed +load static initializer from ASDisplayNode. [Adlai Holler](https://github.com/Adlai-Holler)
 
 ## 2.6

Schemas/configuration.json

@@ -0,0 +1,19 @@
+{
+    "id": "configuration.json",
+    "title": "configuration",
+    "description" : "Schema definition of a Texture Configuration",
+    "$schema": "http://json-schema.org/schema#",
+    "type": "object",
+    "properties": {
+    	"experimental_features": {
+    		"type": "array",
+    		"items": {
+        		"type": "string",
+        		"enum": [
+                    "exp_graphics_contexts",
+                    "exp_text_node"
+                ]
+    		}
+		}
+    }
+}

Source/ASConfiguration.h

@@ -0,0 +1,53 @@
+//
+//  ASConfiguration.h
+//  Texture
+//
+//  Copyright (c) 2018-present, Pinterest, Inc.  All rights reserved.
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#import <Foundation/Foundation.h>
+#import <AsyncDisplayKit/ASBaseDefines.h>
+#import <AsyncDisplayKit/ASExperimentalFeatures.h>
+
+@protocol ASConfigurationDelegate;
+
+NS_ASSUME_NONNULL_BEGIN
+
+AS_SUBCLASSING_RESTRICTED
+@interface ASConfiguration : NSObject <NSCopying>
+
+/**
+ * Create a configuration from the provided JSON object.
+ * The mapping follows the schema in `configuration.json`.
+ */
+- (instancetype)initWithJSONObject:(NSDictionary *)jsonObject;
+
+/**
+ * The delegate for configuration-related events.
+ * Delegate methods are called from a serial queue.
+ */
+@property (strong, nullable) id<ASConfigurationDelegate> delegate;
+
+/**
+ * The experimental features to enable in Texture.
+ * See ASExperimentalFeatures for functions to convert to/from a string array.
+ */
+@property ASExperimentalFeatures experimentalFeatures;
+
+@end
+
+/**
+ * Implement this method in a category to make your
+ * configuration available to Texture. It will be read
+ * only once and copied.
+ */
+@interface ASConfiguration (UserProvided)
++ (ASConfiguration *)textureConfiguration;
+@end
+
+NS_ASSUME_NONNULL_END

Source/ASConfiguration.m

@@ -0,0 +1,40 @@
+//
+//  ASConfiguration.m
+//  Texture
+//
+//  Copyright (c) 2018-present, Pinterest, Inc.  All rights reserved.
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#import <AsyncDisplayKit/ASConfiguration.h>
+#import <AsyncDisplayKit/ASConfigurationInternal.h>
+
+/// Not too performance-sensitive here.
+
+/// Get this from C++, without the extra exception handling.
+#define autotype __auto_type
+
+@implementation ASConfiguration
+
+- (instancetype)initWithJSONObject:(NSDictionary *)jsonObject
+{
+  if (self = [self init]) {
+    autotype featureStrings = ASDynamicCast(jsonObject[@"experimental_features"], NSArray);
+    self.experimentalFeatures = ASExperimentalFeaturesFromArray(featureStrings);
+  }
+  return self;
+}
+
+- (id)copyWithZone:(NSZone *)zone
+{
+  ASConfiguration *config = [[ASConfiguration alloc] init];
+  config.experimentalFeatures = self.experimentalFeatures;
+  config.delegate = self.delegate;
+  return config;
+}
+
+@end

Source/ASConfigurationDelegate.h

@@ -0,0 +1,32 @@
+//
+//  ASConfigurationDelegate.h
+//  Texture
+//
+//  Copyright (c) 2018-present, Pinterest, Inc.  All rights reserved.
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#import <Foundation/Foundation.h>
+#import <AsyncDisplayKit/ASConfiguration.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Used to communicate configuration-related events to the client.
+ */
+@protocol ASConfigurationDelegate <NSObject>
+@optional
+
+/**
+ * Texture performed its first behavior related to the feature(s).
+ * This can be useful for tracking the impact of the behavior (A/B testing).
+ */
+- (void)textureDidActivateExperimentalFeatures:(ASExperimentalFeatures)features;
+
+@end
+
+NS_ASSUME_NONNULL_END

Source/ASExperimentalFeatures.h

@@ -0,0 +1,31 @@
+//
+//  ASExperimentalFeatures.h
+//  AsyncDisplayKit
+//
+//  Created by Adlai on 1/15/18.
+//  Copyright © 2018 Facebook. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+#import <AsyncDisplayKit/ASBaseDefines.h>
+
+NS_ASSUME_NONNULL_BEGIN
+ASDISPLAYNODE_EXTERN_C_BEGIN
+
+/**
+ * A bit mask of features.
+ */
+typedef NS_OPTIONS(NSUInteger, ASExperimentalFeatures) {
+  ASExperimentalGraphicsContexts = 1 << 0,  // exp_graphics_contexts
+  ASExperimentalTextNode = 1 << 1,          // exp_text_node
+  ASExperimentalFeatureAll = 0xFFFFFFFF
+};
+
+/// Convert flags -> name array.
+NSArray<NSString *> *ASExperimentalFeaturesGetNames(ASExperimentalFeatures flags);
+
+/// Convert name array -> flags.
+ASExperimentalFeatures ASExperimentalFeaturesFromArray(NSArray<NSString *> *array);
+
+ASDISPLAYNODE_EXTERN_C_END
+NS_ASSUME_NONNULL_END

Source/ASExperimentalFeatures.m

@@ -0,0 +1,40 @@
+//
+//  ASExperimentalFeatures.m
+//  AsyncDisplayKit
+//
+//  Created by Adlai on 1/15/18.
+//  Copyright © 2018 Facebook. All rights reserved.
+//
+
+#import <AsyncDisplayKit/ASExperimentalFeatures.h>
+
+NSArray<NSString *> *ASExperimentalFeaturesGetNames(ASExperimentalFeatures flags)
+{
+  NSArray *allNames = ASCreateOnce((@[@"exp_graphics_contexts",
+                                      @"exp_text_node"]));
+
+  if (flags == ASExperimentalFeatureAll) {
+    return allNames;
+  }
+
+  // Go through all names, testing each bit.
+  NSUInteger i = 0;
+  return ASArrayByFlatMapping(allNames, NSString *name, ({
+    (flags & (1 << i++)) ? name : nil;
+  }));
+}
+
+// O(N^2) but with counts this small, it's probably faster
+// than hashing the strings.
+ASExperimentalFeatures ASExperimentalFeaturesFromArray(NSArray<NSString *> *array)
+{
+  NSArray *allNames = ASExperimentalFeaturesGetNames(ASExperimentalFeatureAll);
+  ASExperimentalFeatures result = 0;
+  for (NSString *str in array) {
+    NSUInteger i = [allNames indexOfObject:str];
+    if (i != NSNotFound) {
+      result |= (1 << i);
+    }
+  }
+  return result;
+}

Source/ASTextNode+Beta.h

@@ -21,20 +21,6 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-// When enabled, use ASTextNode2 for subclasses, random instances, or all instances of ASTextNode.
-// See ASAvailability.h declaration of ASTEXTNODE_EXPERIMENT_GLOBAL_ENABLE for a compile-time option.
-typedef NS_OPTIONS(NSUInteger, ASTextNodeExperimentOptions) {
-  // All subclass instances use the experimental implementation.
-  ASTextNodeExperimentSubclasses = 1 << 0,
-  // Random instances of ASTextNode (50% chance) (not subclasses) use experimental impl.
-  // Useful for profiling with apps that have no custom text node subclasses.
-  ASTextNodeExperimentRandomInstances = 1 << 1,
-  // All instances of ASTextNode itself use experimental implementation. Supersedes `.randomInstances`.
-  ASTextNodeExperimentAllInstances = 1 << 2,
-  // Add highlighting etc. for debugging.
-  ASTextNodeExperimentDebugging = 1 << 3
-};
-
 @interface ASTextNode ()
 
 /**
@@ -52,14 +38,6 @@ typedef NS_OPTIONS(NSUInteger, ASTextNodeExperimentOptions) {
  */
 @property (nonatomic, assign) UIEdgeInsets textContainerInset;
 
-/**
- * Opt in to an experimental implementation of text node. The implementation may improve performance and correctness,
- * but may not support all features and has not been thoroughly tested in production.
- *
- * @precondition You may not call this after allocating any text nodes. You may only call this once.
- */
-+ (void)setExperimentOptions:(ASTextNodeExperimentOptions)options;
-
 /**
  * Returns YES if this node is using the experimental implementation. NO otherwise. Will not change.
  */

Source/ASTextNode.h

@@ -17,31 +17,10 @@
 
 #import <AsyncDisplayKit/ASAvailability.h>
 #import <AsyncDisplayKit/ASControlNode.h>
-#if ASTEXTNODE_EXPERIMENT_GLOBAL_ENABLE
-  #import <AsyncDisplayKit/ASTextNode2.h>
-#endif
+#import <AsyncDisplayKit/ASTextNodeCommon.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
-@protocol ASTextNodeDelegate;
-
-#if !ASTEXTNODE_EXPERIMENT_GLOBAL_ENABLE
-
-/**
- * Highlight styles.
- */
-typedef NS_ENUM(NSUInteger, ASTextNodeHighlightStyle) {
-  /**
-   * Highlight style for text on a light background.
-   */
-  ASTextNodeHighlightStyleLight,
-
-  /**
-   * Highlight style for text on a dark background.
-   */
-  ASTextNodeHighlightStyleDark
-};
-
 /**
  @abstract Draws interactive rich text.
  @discussion Backed by TextKit.
@@ -238,70 +217,6 @@ typedef NS_ENUM(NSUInteger, ASTextNodeHighlightStyle) {
 
 @end
 
-#else
-
-@interface ASTextNode : ASTextNode2
-@end
-
-#endif
-
-/**
- * @abstract Text node delegate.
- */
-@protocol ASTextNodeDelegate <NSObject>
-@optional
-
-/**
- @abstract Indicates to the delegate that a link was tapped within a text node.
- @param textNode The ASTextNode containing the link that was tapped.
- @param attribute The attribute that was tapped. Will not be nil.
- @param value The value of the tapped attribute.
- @param point The point within textNode, in textNode's coordinate system, that was tapped.
- @param textRange The range of highlighted text.
- */
-- (void)textNode:(ASTextNode *)textNode tappedLinkAttribute:(NSString *)attribute value:(id)value atPoint:(CGPoint)point textRange:(NSRange)textRange;
-
-/**
- @abstract Indicates to the delegate that a link was tapped within a text node.
- @param textNode The ASTextNode containing the link that was tapped.
- @param attribute The attribute that was tapped. Will not be nil.
- @param value The value of the tapped attribute.
- @param point The point within textNode, in textNode's coordinate system, that was tapped.
- @param textRange The range of highlighted text.
- @discussion In addition to implementing this method, the delegate must be set on the text
-             node before it is loaded (the recognizer is created in -didLoad)
- */
-- (void)textNode:(ASTextNode *)textNode longPressedLinkAttribute:(NSString *)attribute value:(id)value atPoint:(CGPoint)point textRange:(NSRange)textRange;
-
-//! @abstract Called when the text node's truncation string has been tapped.
-- (void)textNodeTappedTruncationToken:(ASTextNode *)textNode;
-
-/**
- @abstract Indicates to the text node if an attribute should be considered a link.
- @param textNode The text node containing the entity attribute.
- @param attribute The attribute that was tapped. Will not be nil.
- @param value The value of the tapped attribute.
- @param point The point within textNode, in textNode's coordinate system, that was touched to trigger a highlight.
- @discussion If not implemented, the default value is YES.
- @return YES if the entity attribute should be a link, NO otherwise.
- */
-- (BOOL)textNode:(ASTextNode *)textNode shouldHighlightLinkAttribute:(NSString *)attribute value:(id)value atPoint:(CGPoint)point;
-
-/**
- @abstract Indicates to the text node if an attribute is a valid long-press target
- @param textNode The text node containing the entity attribute.
- @param attribute The attribute that was tapped. Will not be nil.
- @param value The value of the tapped attribute.
- @param point The point within textNode, in textNode's coordinate system, that was long-pressed.
- @discussion If not implemented, the default value is NO.
- @return YES if the entity attribute should be treated as a long-press target, NO otherwise.
- */
-- (BOOL)textNode:(ASTextNode *)textNode shouldLongPressLinkAttribute:(NSString *)attribute value:(id)value atPoint:(CGPoint)point;
-
-@end
-
-#if !ASTEXTNODE_EXPERIMENT_GLOBAL_ENABLE
-
 @interface ASTextNode (Unavailable)
 
 - (instancetype)initWithLayerBlock:(ASDisplayNodeLayerBlock)viewBlock didLoadBlock:(nullable ASDisplayNodeDidLoadBlock)didLoadBlock __unavailable;
@@ -334,6 +249,4 @@ typedef NS_ENUM(NSUInteger, ASTextNodeHighlightStyle) {
 
 @end
 
-#endif
-
 NS_ASSUME_NONNULL_END