GithubHelp home page GithubHelp logo

facebook / remodel Goto Github PK

View Code? Open in Web Editor NEW
608.0 36.0 91.0 1.82 MB

Remodel is a tool that helps iOS and OS X developers avoid repetitive code by generating Objective-C models that support coding, value comparison, and immutability.

License: MIT License

JavaScript 4.19% TypeScript 78.19% Gherkin 17.55% Shell 0.07%

remodel's Introduction

Remodel

Remodel

Support Ukraine

An Objective-C code generation tool specialized for quickly creating and editing model objects

Remodel is a tool that helps iOS and OS X developers avoid repetitive code by generating Objective-C models that support coding, value comparison, and immutability.

For more on Remodel, see our blog post.

Installation

$ npm install -g remodel-gen

Usage

In order to create a new value type you must first create a .value file wherever you want the corresponding Objective-C files to be created. That file should declare both the properties you want the new value object to have, as well as the types of those properties.

For example, here is a simple contact object:

AddressBookContact {
  NSUInteger identifier
  NSString *name
  NSArray<NSString *> *phoneNumbers
}

Once you have created the .value file you can now generate the corresponding Objective-C objects. There are a couple of ways to do this.

# generates this specific value file
$ remodel-gen Path/To/AddressBookModels/AddressBookContact.value

# generates all .values in this sub-directory (and all child directories)
$ remodel-gen Path/To/AddressBookModels/

The script should output the following line for each model object it generates: "Generating ".

If there are any obvious typos the system should detect it and give an error message.

Annotations

Remodel also supports adding annotations to top level objects as well as individual attributes . These allow us to supply the generator with the extra information that is sometimes required to generate a object correctly.

For example, Remodel guesses that any types it needs to import are defined in the same library as the file it's generating.

// AddressBookContact.value
AddressBookContact {
  NSUInteger identifier
  NSString *name
  NSArray<PhoneNumber *> *phoneNumbers
}

// AddressBookContact.h
# import "PhoneNumber.h"

@implemention AddressBookContact
...
@end

This assumption works for many cases, but sometimes we need to import types from other libraries or when the name of the file containing the type we're importing doesn't match doesn't match that type's name.

To afford for this, we have a type attribute that lets the consumer specify more details about a type they are trying to generate:

%type name="PhoneNumber" library="PhoneNumberLib" file="PhoneNumberTypes"
AddressBookContact {
  NSUInteger identifier
  NSString *name
  PhoneNumber *phoneNumbers
}

// This will generate an import in AddressBookContact.h that looks like:
# import <PhoneNumberLib/PhoneNumberTypes.h>
// instead of:
# import "PhoneNumber.h"

Another important annotation is library. This will make things easier for you if you are using header maps. For example:

%type name="PhoneNumber" library="PhoneNumberLib" file="PhoneNumberTypes"
%library name="AddressBookContact"
AddressBookContact {
  NSUInteger identifier
  NSString *name
  PhoneNumber *phoneNumbers
  ContactActivityState *state
}

// This will generate imports in AddressBookContact.h that looks like:
# import <PhoneNumberLib/PhoneNumberTypes.h>
# import <AddressBookContact/ContactActivityState.h>

Handling non-object types

Sometimes, we need to support a type that does not derive from NSObject, for example an enumeration.

Consider:

typedef NS_ENUM(NSInteger, ContactType) {
...
}

If we want use this in a Remodel object we'll have to tell it that is an underlying type, since knowing that type will allow it to generate the correct description and encode/decode methods.

%type name=ContactType library=TypeLib file=ContactEnumDefines canForwardDeclare=false
AddressBookContact {
  NSUInteger identifier
  NSString *name
  ContactType(NSInteger) type;
}

Attribute types should implement NSCopying

Remodel is specialized for building immutable value objects, so by default, it assumes that all attributes types conform to NSCopying. Unfortunately, it's not possible to know at generation time or compile time if an object conforms to NSCopying. Therefore the following will generate an exception at runtime.

// Counter example
AddressBookContact {
  NSUInteger identifier
  NSString *name
  UIView *myView // this does not work because UIView does not conform to NSCopying
}

Likewise, Remodel does not support attributes with protocol types at this time since, in general, data should not be protocolized.

// Counter example
AddressBookContact {
  NSUInteger identifier
  NSString *name
  id<NSCopying> myInfo // This will cause a generation time failure since Remodel does not support protocol types for attributes
}

Comments

Remodel supports adding comments to the objects it generates.

# Represents a contact in the AddressBook system
AddressBookContact {
  NSUInteger identifier
  # The full name of this contact, formatted for the current locale and to be displayed directly in the UI
  NSString *name
}

Plugins

.value files can choose which features they want Remodel to include in their generated files. For example, to generate coding/decoding methods, you can use the RMCoding plugin:

AddressBookContact includes(RMCoding) {
  NSUInteger identifier
  NSString *name
  PhoneNumber *phoneNumbers
}

The inclusion of the RMCoding plugin will cause Remodel to generate AddressBookContact as conforming to NSCoding along with the appropriate encode/decode methods. Note that PhoneNumber must itself conform to NSCoding, otherwise there will be an error when we try to compile AddressBookContact.

A complete list of plugins included in Remodel can be found here

Algebraic Data Types

Algebraic data types (ADT) are a cousin to the immutable value objects Remodel generates. ADTs allow clean expression of abstract data. For example, consider the case of two mutually exclusive sources for a contact, each with its owns means of identification.

AddressBookContact {
  // set if contact is synced from AD
  uint64_t activeDirectoryId
  // set if the contact was imported from email
  NSString *email
}

With a setup like this, it's pretty easy to create invalid objects and it's unclear how much validation consumers should do. For example:

// There is no easy way to know that the following object is invalid
AddressBookContact *contact = [[AddressBookContact alloc] initWithActiveDirectoryId:1 email:@"[email protected]"];

// Also, methods or functions that interact with Contacts have to deal with the fact that they may receive invalid contact configurations
AddressBookContact *contact = GetContact();
Assert(contact.activeDirectoryId != 0 || contact.email.length > 0);
Assert(!(contact.activeDirectoryId != 0 && contact.email.length > 0));

Using an ADT we can express this data more cleanly:

// AddressBookContactIdentifier.adtValue

AddressBookContactIdentifier {
  ActiveDirectory {
    uint64_t activeDirectoryId
  }
  email {
    NSString *email
  }
}

// AddressBookContact.value
AddressBookContact {
  AddressBookContactIdentifier *identifier;
  ...
}

Methods or functions using AddressBookContact would now look like

AddressBookContact *contact = GetContact();
[contact.identifier
   matchActiveDirectory:^(uint64_t activeDirectoryId) {
     // handle AD contact
   }
   email:^(NSString *email) {
    // handle email contact
   }
 ];

Likewise, creating a AddressBookContactIdentifier is a lot clearer, since the object only allows valid configurations:

AddressBookContactIdentifier *identifier = [AddressBookContactIdentifier activeDirectoryWithId:_id];

To generate ADTs, use the generateAlgebraicDataTypes command.

$ remodel-gen Path/To/AddressBookModels/AddressBookContactIdentifier.adtValue

Configuring and Customing Remodel

For advanced users, there are few ways to tailor how Remodel works in your repo. These are documented in their own file.

Contributing

We welcome pull requests. Please see our docs on contributing for details

License

Copyright (c) 2016-present, Facebook, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

remodel's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

remodel's Issues

Cast to %ld and %lu instead of issuing %zd and %tu specifiers for NSInteger and NSUInteger variables

Xcode 9.3 is not happy when you use %zd and %tu as a specifier for NSInteger and NSUInteger variables. They will generate warnings either when compiling on an iPhone 5c, or when compiling on an iPhone 5s+ (compile to Generic iOS device to test it):

Enum values with underlying type 'NSInteger' should not be used as format arguments; add an explicit cast to 'long' instead

This sucks if you have a project treating warnings as errors.

I suggest changing the implementation to the recommended Xcode fix-it solution: explicitly cast to (long) or (unsigned long) and use the %ld/%lu specifiers.

run 'remodel-gen' command error

try to generates the sample value file encounter a error:

remodel-gen ~/desktop/AddressBookContact.value

/usr/local/lib/node_modules/remodel-gen/bin/dist/js/object-mona-parser/value-object/value-object-parser.js:32
foundType: parsedType
^

ReferenceError: parsedType is not defined
at Object.parse as parseValueObject
at Object.parse (/usr/local/lib/node_modules/remodel-gen/bin/dist/value-object-parser.js:72:35)
at evaluateUnparsedValueObjectCreationRequest (/usr/local/lib/node_modules/remodel-gen/bin/dist/value-objects.js:31:41)
at right (/usr/local/lib/node_modules/remodel-gen/bin/dist/either.js:46:39)
at match (/usr/local/lib/node_modules/remodel-gen/bin/dist/either.js:34:16)
at Object.mbind (/usr/local/lib/node_modules/remodel-gen/bin/dist/either.js:47:12)
at parseValues (/usr/local/lib/node_modules/remodel-gen/bin/dist/value-objects.js:39:47)
at /usr/local/lib/node_modules/remodel-gen/bin/dist/logged-sequence-utils.js:20:26
at /usr/local/lib/node_modules/remodel-gen/bin/dist/promise.js:74:12
at /usr/local/lib/node_modules/remodel-gen/bin/dist/promise.js:30:13

Parser rejects comments after %type directives

The remodel parser rejects the following valid type definition:

%type name=FIGColorType library=FIGColor file=FIGColor canForwardDeclare=false

# Attributes of FIG Buttons
FIGButtonAttributes {
}

With the following error message:

[error][Tue Jan 23 2018 10:08:14 GMT-0800 (PST)] [/Users/dthurn/path/to/code/FIGButtonAttributes.value] (line 3, column 1) expected string matching {{}
expected string matching {,}
expected space
Successfuly generated 0 objects. Encountered 1 errors in other files

It should allow comments to be placed after %type directives.

(also: 'successfully' is spelled wrong, which always slightly annoys me?)

Travis CI

It'd be great to setup the functional and unit tests to run automatically on Travis CI.

Alternative Kotlin or Java output?

Do you guys have something similar for Android? I am wondering if one could keep a model repository that would generate code for both iOS and Android version of the app so one could keep consistency across.

Issue Getting IGListDiffable Plugin Installed

I've not used Typescript much before (in fact, just installed it before using Remodel) and use NPM maybe twice a year, so I might be missing something entirely obvious. I've browsed the past issues and wasn't able to get things quite working.

I'm attempting to install the IGListDiffable plugin documented here. The hang up occurs when I try to build things.

I've cloned this repo locally, and for brevity it's installed at something like this:
desktop/test/remodel-master

With a clean clone, I'm not quite able to build it:
cd /path/to/remodel
./bin/build

I get this error (it seems it can't locate promise.ts which appears to be in the src folder):

/Users/Jordan/Desktop/Test/remodel-master/bin/build ; exit;
module.js:549
    throw err;
    ^

Error: Cannot find module 'promise'
    at Function.Module._resolveFilename (module.js:547:15)
    at Function.Module._load (module.js:474:25)
    at Module.require (module.js:596:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (/Users/Jordan/Desktop/Test/remodel-master/bin/build.js:10:17)
    at Module._compile (module.js:652:30)
    at Object.Module._extensions..js (module.js:663:10)
    at Module.load (module.js:565:32)
    at tryModuleLoad (module.js:505:12)
    at Function.Module._load (module.js:497:3)
logout
Saving session...
...copying shared history...
...saving history...truncating history files...
...completed.

[Process completed]

More than happy to provide more details, and thanks releasing such a useful project!

Properties of type (or backing type) dispatch_block_t should be copied

Blocks are by default stack allocated, and as I understand it, there are cases where losing the type can cause ARC to retain rather than transfer ownership from stack to heap โ€“ and I think no automatic copy happens in MRR.

In the ARC case, the block could be retained rather than copied by the blocks runtime, in the MRR case, neither might happen. I think it would be safe to treat blocks as immutable types and copy them in initializers.

Support of Alternative Encoding Format

Hi,

I am trying to add support (a new custom plugin) for alternative encoding format such as flatbuffer. There is a difficulty of supporting these encoding format, because they do not have switch cases in the decoding / encoding process. I am currently thinking of two possible solutions: 1) creating additional classes for each subtype, and then encode/decode an _adtObject (this will be casted to different subtype classes) instead; 2) simply encode/decode every declared properties.

Please let me know which approach will you recommend. Thanks!

Comparison with Pinterest Plank

What's the main difference and pros/cons between Remodel and Plank? Have you guys done any testing or comparison?

Both seems quite similar and have the same goal, generate immutable models.

Using a repeated function prefix with different parameter names

It seems impossible to generate a class with repeated function prefixes:

MyClass  {
  create:1 {
    NSString *username
  }
  create:2 {
    NSString *userId
  }
}

should be able to generate the code

@interface MyClass : NSObject <NSCopying>

+ (instancetype)createWithUsername:(NSString *)username;

+ (instancetype)createWithUserId:(NSString *)userId;

...
@end

but because in the .value file both have the same key create the generation fails with

Algebraic types cannot have two subtypes with the same name, but found two or more subtypes with the name create

Having issues with requiring dependencies for custom plugin

Warning : Javascript noob (apologies in advance)

Trying to create a custom plugin but getting hung up on requiring various js files.

What I have done:

  1. Installed via 'npm install -g remodel-gen'
  2. Made custom plugin 'dictionary_plugin.ts'
  3. Referenced the plugin in .valueObjectConfig as follows:
{
    "customPluginPaths": [
        "plugins/dictionary_plugin.ts"
    ]
}
  1. Require via absolute path in dictionary_plugin.ts
var ValueObject = require('/usr/local/lib/node_modules/remodel-gen/bin/dist/value-object');

No errors occur when I gen (it finds the plugin properly and I refer to it in my .value object). However any time I access an attribute of ValueObject it crashes. Looking at the contents of value-object.js in particular was confusing as it only contains a single line

"use strict";

So theres a couple things odd to me that may stem from my lack knowledge on nodejs.

  1. When installed via npm all dependencies i.e. value-object are .js files, however on this repo they are all .ts files (understand the difference in language, just unsure why the discrepency).
  2. When trying to install directly from github using 'npm install -g https://github.com/facebook/remodel.git' none of the ts files get included

Ultimately, my question is what is the simplest way I can import/require all of the files required for creating the plugin from the npm installation inside of dictionary_plugin.ts. In general I am looking for objc.js, value-object.js, maybe.js, etc. Unable to figure out a straight forward way to do this. Thanks a ton for any help you can provide!

dictionary_plugin.ts path

 ProjectRoot/ValueModels/plugins/dictionary_plugin.ts

.valueObjectConfig path

 ProjectRoot/ValueModels/.valueObjectConfig

Doesn't import classes which are included via generics, even given an explicit `%import`

This is probably easier to explain as an example:

Foo.value

%library name=FooLib
Foo {
  %import library=BarLib file=Bar
  NSArray<Bar *> *bars
}

Generates:

#import <FBValueObject/FBValueObject.h>
#import <Foundation/Foundation.h>

@interface Foo : FBValueObject <NSCopying>

@property (nonatomic, readonly, copy) NSArray<Bar *> *bars;

- (instancetype)initWithBars:(NSArray<Bar *> *)bars;

@end

Notice that #import <BarLib/Bar.h> is missing, therefore causing it to fail to compile. Whereas if you do:

Foo2.value

%library name=FooLib
Foo {
  %import library=BarLib file=Bar
  Bar *singleBar
}

It generates the correct import:

#import <FBValueObject/FBValueObject.h>
#import <Foundation/Foundation.h>
#import <BarLib/Bar.h>

@interface Foo : FBValueObject <NSCopying>

@property (nonatomic, readonly, copy) Bar *singleBar;

- (instancetype)initWithSingleBar:(Bar *)singleBar;

@end

Seems to me we should just be importing everything that explicitly included via %import, but not sure whether that was an explicit product decision.

Self-referential algebraic data type does not forward-declare if the reference is within generics

AlgebraicType {
  TypeA
  TypeB {
    NSDictionary<AlgebraicType *> *algebraicTypes
  }
}

produces:

#import <Foundation/Foundation.h>

typedef void (^AlgebraicTypeTypeAMatchHandler)();
typedef void (^AlgebraicTypeTypeBMatchHandler)(NSDictionary<AlgebraicType *> *algebraicTypes);

@interface AlgebraicType : NSObject <NSCopying>

+ (instancetype)typeA;

+ (instancetype)typeBWithAlgebraicTypes:(NSDictionary<AlgebraicType *> *)algebraicTypes;

- (void)matchTypeA:(AlgebraicTypeTypeAMatchHandler)typeAMatchHandler typeB:(AlgebraicTypeTypeBMatchHandler)typeBMatchHandler;

@end

Allow algebraic matching blocks to be nil

Currently, algebraic type matchers are implemented approximately like so:

switch (_subtype) {
  case _SomethingA:
    aMatchHandler();
  ...

This means that it's required to create and pass in empty blocks for every handler, because a match that tries to call nil as a function will cause a crash. It would be convenient for code that is aiming to only handle specific matches to not need the wordy implementation of empty blocks, and this could be achieved by if (aMatchHandler) { aMatchHandler(); }.

How to use SIMD types

I tried this:

%library name="simd"
%type name=vector_int2 library=simd canForwardDeclare=false
MyObject {
  NSString *identifier
  vector_int2 position
}

Output:

[error][Thu Jan 24 2019 15:31:14 GMT-0500 (Eastern Standard Time)] [/REDACTED/Broken.value]The Description plugin does not know how to format the type "vector_int2" from MyObject.position. Did you forget to declare a backing type?
[/REDACTED/Broken.value]The Equality plugin does not know how to compare or hash the type "vector_int2" from MyObject.position. Did you forget to declare a backing type?
Successfuly generated 0 objects. Encountered 1 errors in other files

Based on the documentation for a value type, it seems like I can declare an "underlying" type, but vector_int2 can't be composed out of the builtin types.

How do I tell remodel that it's a value type you can compare with == and copy with =? Does this require changes to remodel-gen to support?

ReferenceError: parsedType is not defined

When I run remodel-gen,


/usr/local/lib/node_modules/remodel-gen/bin/dist/js/object-mona-parser/value-object/value-object-parser.js:32
    foundType: parsedType
               ^

ReferenceError: parsedType is not defined
    at Object.parse [as parseValueObject] (/usr/local/lib/node_modules/remodel-gen/bin/dist/js/object-mona-parser/value-object/value-object-parser.js:32:16)
    at Object.parse (/usr/local/lib/node_modules/remodel-gen/bin/dist/value-object-parser.js:72:35)
    at evaluateUnparsedValueObjectCreationRequest (/usr/local/lib/node_modules/remodel-gen/bin/dist/value-objects.js:31:41)
    at right (/usr/local/lib/node_modules/remodel-gen/bin/dist/either.js:46:39)
    at match (/usr/local/lib/node_modules/remodel-gen/bin/dist/either.js:34:16)
    at Object.mbind (/usr/local/lib/node_modules/remodel-gen/bin/dist/either.js:47:12)
    at parseValues (/usr/local/lib/node_modules/remodel-gen/bin/dist/value-objects.js:39:47)
    at /usr/local/lib/node_modules/remodel-gen/bin/dist/logged-sequence-utils.js:20:26
    at /usr/local/lib/node_modules/remodel-gen/bin/dist/promise.js:74:12
    at /usr/local/lib/node_modules/remodel-gen/bin/dist/promise.js:30:13

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.