Swiftpack.co - Package - pinterest/plank

Plank logo

Plank

Build Status

Plank is a command-line tool for generating robust immutable models from JSON Schemas. It will save you time writing boilerplate and eliminate model errors as your application scales in complexity.

We currently support the following languages:

Schema-defined

Models are defined in JSON, a well-defined, extensible and language-independent specification.

Immutable Classes

Model classes are generated to be immutable. Each class provides a “Builder” class to handle mutation.

Type safe

Based on the type information specified in the schema definition, each class provides type validation and null reference checks to ensure model integrity.

Installation

MacOS

$ brew install plank

Linux

Plank supports building in Ubuntu Linux via Docker. The Dockerfile in the repository will fetch the most recent release of plank and build dependencies including the Swift snapshot.

$ docker build -t plank .

Build from source

Plank is built using the Swift Package Manager. Although you’ll be able to build Plank using swift build directly, for distribution of the binary we’d recommend using the commands in the Makefile since they will pass the necessary flags to bundle the Swift runtime.

$ make archive

Getting Started

Keep reading to learn about Plank’s features or get your try it yourself with the tutorial.

Defining a schema

Plank takes a schema file as an input. Schemas are based on JSON, a well-defined, extensible and language-independent specification. Defining schemas in JSON allowed us to avoid writing unnecessary parser code and opened up the possibility of generating code from the same type system used on the server.

{
    "id": "pin.json",
    "title": "pin",
    "description" : "Schema definition of a Pin",
    "$schema": "http://json-schema.org/schema#",
    "type": "object",
    "properties": {
        "id": { "type": "string" },
        "link": { "type": "string", "format": "uri"}
    }
}

You’ll notice we specify the name of the model and a list of its properties. Note that link specifies an additional format attribute which tells Plank to use a more concrete type like NSURL or NSDate.

Generating a model

Generate a schema file (pin.json) using Plank using the format plank [options] file1 file2 file3 ...

$ plank pin.json

This will generate files (Pin.h, Pin.m) in the current directory:

$ ls
pin.json Pin.h Pin.m

Learn more about usage on the installation page.

Generated Output

Plank will generate the necessary header and implementation file for your schema definition. Here is the output of the Pin.h header.

@interface Pin
@property (nonatomic, copy, readonly) NSString *identifier;
@property (nonatomic, strong, readonly) NSURL *link;
@end

All properties are readonly, as this makes the class immutable. Populating instances of your model with values is performed by builder classes.

Mutations through builders

Model mutations are performed through a builder class. The builder class is a separate type which contains readwrite properties and a build method that will create a new object. Here is the header of the builder that Plank generated for the Pin model:

@interface PinBuilder
@property (nonatomic, copy, readwrite) NSString *identifier;
@property (nonatomic, strong, readwrite) NSURL *link;
- (Pin *)build;
@end

@interface Pin (BuilderAdditions)
- (instancetype)initWithBuilder:(PinBuilder *)builder;
@end

JSON parsing

Plank will create an initializer method called initWithModelDictionary: that handles parsing NSDictionary objects that conform to your schema. The generated implementation will perform validation checks based on the schema’s types, avoiding the dreaded [NSNull null] showing up in your objects:

@interface Pin (JSON)
- (instancetype)initWithModelDictionary:(NSDictionary *)dictionary;
@end

Serialization

All Plank generated models implement methods to conform to NSSecureCoding, providing native serialization support out of the box.

+ (BOOL)supportsSecureCoding {
    return YES;
}

- (instancetype)initWithCoder:(NSCoder *)aDecoder {
    if (!(self = [super init])) { return self; }
    _identifier = [aDecoder decodeObjectOfClass:[NSString class] forKey:@"identifier"];
    _link = [aDecoder decodeObjectOfClass:[NSURL class] forKey:@"link"];
    return self;
}

- (void)encodeWithCoder:(NSCoder *)aCoder {
    [aCoder encodeObject:self.identifier forKey:@"identifier"];
    [aCoder encodeObject:self.link forKey:@"link"];
}

With this implementation objects are serialized using NSKeyedArchiver:

// Create a pin from a server response
Pin *pin = [[Pin alloc] initWithModelDictionary:/* server response */];
// Cache the pin
[NSKeyedArchiver archiveRootObject:pin toFile:/* cached pin path */];
// App goes on, terminates, restarts...
// Load the cached object
Pin *cachedPin = [NSKeyedUnarchiver unarchiveObjectWithFile:/* cached pin path */];

Model merging and partial data

Plank models support merging and partial object materialization through a conventional “last writer wins” approach. By calling the mergeWithModel: on a generated model with a newer instance, the properties set on the newer instance will be preserved. To know which properties are set, the information is tracked internally within the model during initialization or through any mutation methods. In this example, an identifier property is used as a primary key for object equality:

static inline id valueOrNil(NSDictionary *dict, NSString *key);
struct PinSetProperties {
  unsigned int Identifier:1;
  unsigned int Link:1;
};
- (instancetype)initWithModelDictionary:(NSDictionary *)modelDictionary {
  [modelDictionary enumerateKeysAndObjectsUsingBlock:^(NSString *  _Nonnull key, id obj, BOOL *stop){
    if ([key isEqualToString:@"identifier"]) {
        // ... Set self.identifier
        self->_pinSetProperties.Identifier = 1;
    }
    if ([key isEqualToString:@"link"]) {
        // ... Set self.link
        self->_pinSetProperties.Link = 1;
    }
  }];
  // Post notification
  [[NSNotificationCenter defaultCenter] postNotificationName:@"kPlankModelDidInitializeNotification" object:self];
}

With immutable models, you have to think through how data flows through your application and how to keep a consistent state. At the end of every model class initializer, there’s a notification posted with the updated model. This is useful for integrating with your data consistency framework. With this you can track whenever a model has updated and can use internal tracking to merge the new model.

@implementation Pin(ModelMerge)
- (instancetype)mergeWithModel:(Pin *)modelObject {
    PinBuilder *builder = [[PinBuilder alloc] initWithModelObject:self];
    if (modelObject.pinSetProperties.Identifier) {
        builder.identifier = modelObject.identifier;
    }
    if (modelObject.pinSetProperties.Link) {
        builder.link = modelObject.link;
    }
    return [builder build];
}
@end

Algebraic data types

Plank provides support for specifying multiple model types in a single property, commonly referred to as an Algebraic Data Type (ADT). In this example, the Pin schema receives an attribution property that will be either a User, Board, or Interest. Assume we have separate schemas defined in files user.json, board.json and interest.json, respectively.

{
    "title": "pin",
    "properties": {
        "identifier": { "type": "string" },
        "link": { "type": "string", "format": "uri"},
        "attribution": {
          "oneOf": [
            { "$ref": "user.json" },
            { "$ref": "board.json" },
            { "$ref": "interest.json" }
          ]
        }
    }
}

Plank takes this definition of attribution and creates the necessary boilerplate code to handle each possibility. It also provides additional type-safety by generating a new class to represent your ADT.

@interface PinAttribution : NSObject<NSCopying, NSSecureCoding>
+ (instancetype)objectWithUser:(User *)user;
+ (instancetype)objectWithBoard:(Board *)board;
+ (instancetype)objectWithInterest:(Interest *)interest;
- (void)matchUser:(void (^)(User * pin))userMatchHandler
          orBoard:(void (^)(Board * board))boardMatchHandler
       orInterest:(void (^)(Interest * interest))interestMatchHandler;
@end

Note there’s a “match” function declared in the header. This is how you extract the true underlying value of your ADT instance. This approach guarantees at compile-time you have explicitly handled every possible case preventing bugs and reducing the needs to use runtime reflection which hinders performance. The example below shows how you’d use this match function.

PinAttribution *attribution;
[attribution matchUser:^(User *user) {
   // Do something with "user"
} orBoard:^(Board *board) {
   // Do something with "board"
} orInterest:^(Interest *interest) {
   // Do something with "interest"
}];

Contributing

Pull requests for bug fixes and features welcomed.

License

Copyright 2019 Pinterest, Inc.

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

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Github

link
Stars: 420
Help us keep the lights on

Used By

Total: 1

Releases

v1.5 - Feb 27, 2019

This release contains a lot of internal cleanup as well as new functionality.

Updates

Objective-C

Added isSet methods for each property which will allow callers to differentiate if a property has been set: This is useful for differentiating:

  • Default values for primitive types (i.e. int properties will still be 0 if not set)
  • nil values for reference types (i.e. pointers to objects are nil if not set)

Bazel

Initial support for building plank and integrating it within your local bazel project.

First add plank to your WORKSPACE file

git_repository(
    name = "plank",
    remote = "https://github.com/pinterest/plank.git",
    tag = "1.5"
)

Then you can run plank using: bazel run @plank//:plank -- [YOUR ARGS HERE]

Java (alpha)

  • Initial support is available and depends on AutoValue and GSON. AutoValue is likely to be removed soon as a requirement.
  • Java support is in active development and breaking changes are likely
  • Audience is focused on Android development which could influence some of the design decisions / dependencies

Changes

eaaccea [Objective-C] Option for adding abilities to tell if a method is set. fa1a00d [Objective-C] Fix issues that cause unstable output (#160) bec7ec9 Update WORKSPACE to latest rules_swift dependencies (#163) e041f8e Enable Swiftlint for PRs (#154) 27f2219 Update README.md ce0dbea Migrate Plank to Travis CI (#152) 71a3a5c Fix typo (#146) c387215 Update bazel build to use rules_swift 7328fa0 Refactor version number to use a struct (#145) 8053ab1 Add version to CLI (#144) 87197a3 Add flag to avoid runtime files from getting generated (#137) 9439de7 Fix nil-checking issue in dictionary representation (#135) 0c2bf4e Update to Swift 4.1, fix inheritance issue with equality (#133) 42838c3 Update Java enum rendering to avoid collisions when multiple enums are (#130) db6c647 Use fancy string enums and remove unused runtime function (#128) 6eb769b Fix linux build (#127) 153ebe7 Use @NonNull for nonnull Java properties. Add nullability to documentation 1b4641c Add initial Java documentation 7a0b6aa Separate CLI reference into its own page 56097d2 Add flow documenation overview a86117d Initial support for Java (#106)

v1.4.1 - Mar 9, 2018

Overview

This release contains additional fixes to the generation of dictionaryObjectRepresentation for cases where you have model schema with nested collections (lists within lists, maps within maps, lists within maps, ...).

Changes

a5e132e Fix issues with nested collections in dictionaryObjectRepresentation (#126)

v1.4 - Mar 5, 2018

Additions

  • Objective-C models can now render themselves to Dictionaries This was previously supported but had a number of edge cases where issues were present. We have now addressed those issues and we are ready to support this capability.
  • A foundation for writing more integration tests between Objective-C and Flow bridging. This can be helpful if you share schemas between them.
  • Generated ObjC models test coverage has improved for testing initialization and dictionary representation. We will continue this trend for other capabilities.

Changes

aa069d2 Add basic Objective-C and JS bridging test (#124) f09ae27 Fix Docker builds (#125) fe78418 Restore dictionaryObjectRepresentation for Objective-C (#122)

v1.3 - Feb 14, 2018

Whats in this release?

Breaking changes

For Objective-C, an enum type will no longer have "Type" added to it's name. This introduced issues (https://github.com/pinterest/plank/issues/119) and was inconsistent with the logic we use for Flow.

Previous behavior: A enum property some_prop on a type Foo would generate a enum named FooSomePropType

New behavior: A enum property some_prop on a type Foo will generate a enum named FooSomeProp

If you are currently using Enums you'll likely need to update references to these types in your code base but the functionality remains the same. In the future we'll strive to keep these naming strategies consistent between languages.

Notable bug fixes

  • Improve the nullability support for Objective-C
  • Fix the ordering of properties during generation to ensure we don't have variance in our generation.

Changes

991a465 Align naming logic between Flow and ObjC for enums. Fix naming collis… (#120) f8f7c17 Correct extends field example (#117) a8d8676 Fixed missing "" (#118) 0e2668c Update README.md (#114) 47fdfdd Builder setter should consider copy memoryAssignmentType (#113) bcc7bef Enumeration of schema properties should occur in a specific order to ensure a (#110) df1e444 Update homebrew installation instructions

v1.2.1 - Jan 17, 2018

Summary

  • Added make install to Makefile. Use PREFIX to specify a different installation path than /usr/local

Basic Usage:

make install

Usage with custom installation path:

make install PREFIX=/usr/local/Cellar/plank/1.2.1
  • Address issues identified by SwiftLint
  • Add documentation for Set type

Commits

56012d6 Add make install target to Makefile (#109) 4c3f228 Add autocorrect step to Swiftlint (#107) 3bdc34f Add Set to docs on property fields (#105)