Create a centralized configuration API

CHANGELOG.md

@@ -21,6 +21,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)
 - **Breaking** Changes to ASNetworkImageNode: [Adlai Holler](https://github.com/Adlai-Holler)
   - Modified `ASImageDownloaderCompletion` to add an optional `id userInfo` field. Your custom downloader can pass `nil`.
   - Modified the last argument to `-[ASNetworkImageNodeDelegate imageNode:didLoadImage:info:]` method from a struct to an object of new class `ASNetworkImageLoadInfo` which includes other metadata about the load operation.

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,55 @@
+//
+//  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>
+
+/**
+ * Initialize this configuration with the provided dictionary,
+ * or nil to create an empty configuration.
+ *
+ * The schema is located in `schemas/configuration.json`.
+ */
+- (instancetype)initWithDictionary:(nullable NSDictionary *)dictionary;
+
+/**
+ * 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)initWithDictionary:(NSDictionary *)dictionary
+{
+  if (self = [super init]) {
+    autotype featureStrings = ASDynamicCast(dictionary[@"experimental_features"], NSArray);
+    self.experimentalFeatures = ASExperimentalFeaturesFromArray(featureStrings);
+  }
+  return self;
+}
+
+- (id)copyWithZone:(NSZone *)zone
+{
+  ASConfiguration *config = [[ASConfiguration alloc] initWithDictionary:nil];
+  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,35 @@
+//
+//  ASExperimentalFeatures.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>
+
+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,44 @@
+//
+//  ASExperimentalFeatures.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/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/ASNetworkImageLoadInfo.h

@@ -1,9 +1,13 @@
 //
 //  ASNetworkImageLoadInfo.h
-//  AsyncDisplayKit
+//  Texture
 //
-//  Created by Adlai on 1/30/18.
-//  Copyright © 2018 Facebook. All rights reserved.
+//  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>

Source/ASNetworkImageLoadInfo.m

@@ -1,9 +1,13 @@
 //
 //  ASNetworkImageLoadInfo.m
-//  AsyncDisplayKit
+//  Texture
 //
-//  Created by Adlai on 1/30/18.
-//  Copyright © 2018 Facebook. All rights reserved.
+//  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/ASNetworkImageLoadInfo.h>

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.
  */