gyro 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 30319d692b235808740716342f2e77b76d8cee30
+  data.tar.gz: c8f35a028991c3313f8edc72900abfa809f805f7
+SHA512:
+  metadata.gz: fa5a072a603e117f45190b741c3c1df3dfa04b248345949318e55caec3ea308ff75c96b173d154a373135bf671e08d55d910ec5e6fdf0c78963b0da3a2f42f56
+  data.tar.gz: 446e8e2e43e7c1414bc891c85b0b113ad2298487bf16e118b33034cdb9bcc7dfe0cc168af971c989ad9e658d9185dffbd9ce011627471ffe81daa696f4f0d4ff

data/LICENSE

@@ -0,0 +1,201 @@
+                          Apache License
+                    Version 2.0, January 2004
+                http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   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.

data/README.md

@@ -0,0 +1,840 @@
+# Gyro
+
+Gyro is a tool to generate [Realm](https://realm.io) model classes, for both Android (Java) and iOS/macOS (ObjC & Swift), from an `.xcdatamodel` file.
+
+---
+
+
+## Introduction
+
+The `.xcdatamodel` file is usually used to represent Core Data entities in Xcode in a graphical way. It can be created or edited with a graphical user interface in Xcode.
+
+But with Gyro, you will now be able to **use an `xcdatamodel` to create a [Realm](https://realm.io) model files as well!**
+
+This will allow you to design your model in a visual way (rather than by code), only once (rather than once for Android and once for iOS), and have the code generated for you.
+
+![Simple Entity](documentation/simple_entity.png)
+
+The `.xcdatamodel` file is the input of the script.
+
+
+## License
+
+This tool is under [the Apache 2 License](LICENSE).
+
+It has been initially developed by [Niji](http://www.niji.fr) and is in no way affiliated to the [Realm](https://realm.io) company.
+
+
+## Installation
+
+Simply clone this repository anywhere you want on your machine, then run the `bin/gyro` ruby script with the appropriate options (see below). For example:
+
+```
+~/Dev/Gyro/bin/gyro -m <model> --ios ~/Dev/MyProject/RealmModel --swift
+```
+
+
+
+
+## Command line arguments
+
+Gyro is a command line tool. The available parameters are as follows. You can also use `-h` do display the usage and available parameters/flags in the Terminal of course.
+
+| Short flag | Long flag | Description | Android | iOS |
+| ---------- | --------- | ----------- |:-------:|:---:|
+| `-m` | `--model` | Path to the  `.xcdatamodel` file. If this parameter is not given, Gyro will look for a `.xcdatamodel` | ✅ | ✅ |
+| `-a` | `--android` | Path to the directory where the generated files for Android will be created (e.g.: home/documents/dev/android/realm_project/com/niji/data) | ✅ | ➖ |
+| `-p` | `--package` | Full name of the Android "data" package (e.g.: com.niji.data) | ✅ | ➖ |
+| `-i` | `--ios` | Path to the directory where the generated files for iOS/macOS will be created | ➖ | ✅ |
+| `-j` | `--json` | Create the Realm-JSON categories (https://github.com/matthewcheok/Realm-JSON) | ➖ | ☑️ |
+| `-f` | `--framework` | Tells whether the project uses CocoaPods Frameworks  | ➖ | ☑️ |
+| `-s` | `--swift` | Use Swift for the iOS/macOS generation | ➖ | ☑️ |
+| `-n` | `--nsnumber` | Generate `NSNumber`s instead of Int/BOOL/Float types | ➖ | ☑️ |
+| `-w` | `--wrappers` | Use type wrappers for Java (Integer, Double, …) for optional attributes instead of primitive types (int, double, …) | ☑️ | ➖ |
+| `-x` | `--annotations` | Annotate the getters/setters of the generated classes with `@Nullable` for any optional attribute/relationship, and with `@NonNull` for any non-optional attribute/relationship | ☑️ | ➖ |
+| `-h` | `--help` | Show help | ☑️ | ☑️ |
+| `-v` | `--version` | Show the current version number of Gyro | ☑️ | ☑️ |
+
+_Caption: ✅ Mandatory flag for this platform / ☑️ Optional flag usable for this platform / ➖ Not applicable for this platform_
+
+
+
+## Annotating your `xcdatamodel`
+
+The `.xcdatamodel` Xcode editor allows you to add "user infos" to your entities, attributes or relationships. Each "user info" entry is an arbitrary key/value pair.
+
+_To define a User Info key in Xcode's xcdatamodel editor, select the entity or attribute you want to add a User Info to, then select the 3rd tab in the inspector on the right ("Data Model Inspector", or Cmd-Alt-3), and fill the information you want in the "User Info" section there._
+
+With the help of these "user infos", you will be able to give Gyro extra information about your model classes. For example, you can tell which attribute is the primary key, the attributes to ignore, the JSON mappings, …
+
+Below are details about how to annotate your `.xcdatamodel` entities and attributes to be able to leverage each Realm features when generating your Realm models with Gyro.
+
+
+---
+
+
+### Primary key
+
+To tell which attribute will be used as a primary key, add the following 'user info' to **the entity**:
+
+| Key | Value |
+|-----|-------|
+| `identityAttribute` | `name_of_the_attribute` |
+
+
+__Example__: On the "FidelityCard" entity:
+
+![Primary Key](documentation/primary_key.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+```java
+package com.niji.data;
+
+import io.realm.RealmObject;
+import io.realm.annotations.PrimaryKey;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public class FidelityCard extends RealmObject {
+
+    @PrimaryKey
+    private short identifier;
+    private int points;
+    private User user;
+	[...]
+}
+```
+</details>
+
+<details>
+<summary>📑 Sample of the generated code in Objective-C (iOS)</summary>
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Imports
+
+#import "RLMFidelityCard.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Implementation
+
+@implementation RLMFidelityCard
+
+#pragma mark - Superclass Overrides
+
++ (NSString *)primaryKey
+{
+    return @"identifier";
+}
+
+@end
+```
+</details>
+
+
+---
+
+
+### Ignore attribute
+
+You can decide to ignore some attributes of the `.xcdatamodel` file. They will not be persisted to Realm. To do so, add the following 'user info' to **the attribute**:
+
+| Key | Value |
+|-----|-------|
+| `realmIgnored` | `value` |
+
+
+__Example__: on the attribute `ignored` of the entity `Shop`:
+
+![Ignored Attribute](documentation/ignored.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+```java
+package com.niji.data;
+
+import io.realm.RealmList;
+import io.realm.RealmObject;
+import io.realm.annotations.Ignore;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public class Shop extends RealmObject {
+
+    private String name;
+    private String readOnly;
+    private RealmList<Product> products;
+    @Ignore
+    private String ignored;
+    [...]
+}
+```
+</details>
+
+<details>
+<summary>📑 Sample of the generated code in Objective-C (iOS)</summary>
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Imports
+
+#import "RLMShop.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Implementation
+
+@implementation RLMShop
+
+#pragma mark - Superclass Overrides
+
+// Specify properties to ignore (Realm won't persist these)
++ (NSArray *)ignoredProperties
+{
+    return @[@"ignored"];
+}
+@end
+```
+</details>
+
+
+---
+
+
+### Read only
+
+On iOS/macOS, you can define attributes which are not persisted and whose value is computed dynamically.
+To do so, add the following 'user info' to **the attribute**
+
+| Key | Value |
+|-----|-------|
+| `realmReadOnly` | `the_code_source_to_generate` |
+
+
+__Example__: On the `readOnly`  attribute of the `Shop`  entity:
+
+![Read Only](documentation/read_only.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Objective-C (iOS)</summary>
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Imports
+
+#import "RLMShop.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Implementation
+
+@implementation RLMShop
+
+#pragma mark - Superclass Overrides
+
+- (NSString *)readOnly
+{
+    return self.name;
+}
+
+@end
+```
+</details>
+
+
+---
+
+
+### Inverse Relationships
+
+In realm, when you have both A -> B and B -> A relationships, you have to choose one of those relationships to be the primary one (e.g. A -> B) — that will be stored in Realm — and the other inverse relationship will then be **computed** by code. [For more information, see the related RealmSwift documentation on Inverse Relationships](https://realm.io/docs/swift/latest/#inverse-relationships).
+
+To mark a relationship as being an inverse relationship (the B -> A relationship and not the primary A -> B one), the convention in `gyro` is to **suffix the name of the relationship with an underscore `_`** .
+
+This will then generate the following code in Swift for that inverse relationship:
+
+```swift
+LinkingObjects(fromType: A.self, property: "b")`
+```
+
+If your inverse relationship is defined to point to a unique object (inverse of a `1-*` relationship for exemple, and not a `*-*` one), the generated code will contain both the plural form of the computed variable and a singular form returning its first element, for convenience:
+
+```swift
+let owners = LinkingObjects(fromType: Person.self, property: "dogs")`
+var owner: Person? { return owners.first }
+```
+
+
+---
+
+
+### Optionnals fields and wrapper types
+
+On Android, the `-w`/`--wrappers` flag allows you to use wrapper types (`Double`, `Short`, …) for optional fields instead of primitive types (`double`, `short`, …).
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+```java
+package com.niji.data;
+
+import io.realm.RealmObject;
+import io.realm.annotations.PrimaryKey;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public class FidelityCard extends RealmObject {
+
+    @PrimaryKey
+    private short identifier;   // "optional" checkbox not checked in the xcdatamodel
+    private Integer points;     // "optional" checkbox checked in the xcdatamodel
+    private User user;
+	[...]
+}
+```
+</details>
+
+
+---
+
+
+### Support Annotations
+
+On Android, the flag `-x`/`--annotations` allows you to annotate class attributes' getters & setters with `@Nullable` (if the attribute is optional) or `@NonNull` (if it isn't) attributes.  
+This option can be combined with the `-w` wrapper flag to generate a safer and more secure code in Android Studio, generating proper warnings if misused.
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+```java
+package com.niji.data;
+
+import io.realm.RealmObject;
+import io.realm.annotations.PrimaryKey;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public class FidelityCard extends RealmObject {
+
+    @PrimaryKey
+    private short identifier;   // "optional" checkbox not checked in the xcdatamodel
+    private Integer points;     // "optional" checkbox checked in the xcdatamodel
+    private User user;
+	[...]
+
+	@android.support.annotation.Nullable
+	public Integer getPoints() {
+	    return points;
+	}
+
+	public void setPoints(@android.support.annotation.Nullable final Integer points) {
+	    this.points = points;
+	}
+
+}
+```
+</details>
+
+Furthermore, it's possible to add custom annotations to your fields.
+To do that, simply add the key/value pair to the UserInfos of the attribute to annotate:
+
+| Key | Value |
+|-----|-------|
+| `supportAnnotation` | `AnnotationToAdd` |
+
+
+__Example__: If you wish to add the `IntRange(from=0,to=255)` annotation to an attribute, use the following:
+
+![Support Annotation](documentation/support_annotation.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+```java
+package com.gyro.tests;
+
+import io.realm.RealmObject;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public class FidelityCard extends RealmObject {
+
+    public interface Attributes {
+        String IDENTIFIER = "identifier";
+        String POINTS = "points";
+    }
+
+    private short identifier;
+    @android.support.annotation.IntRange(from=0,to=255)
+    private int points;
+
+    public short getIdentifier() {
+        return identifier;
+    }
+
+    public void setIdentifier(final short identifier) {
+        this.identifier = identifier;
+    }
+
+    @android.support.annotation.IntRange(from=0,to=255)
+    public int getPoints() {
+        return points;
+    }
+
+    public void setPoints(@android.support.annotation.IntRange(from=0,to=255) final int points) {
+        this.points = points;
+    }
+}
+```
+</details>
+
+
+---
+
+
+### Handling enums
+
+Sometimes, an `Int` attribute in the model actually represents an `enum` member in your model. To deal with this case, you can add the following two key/value pairs to this **attribute**:
+
+| Key | Value |
+|-----|-------|
+| `enumType` | `my_type` |
+| `enumValues` | `my_value_1, my_value_2, my_value_3` |
+
+> _Note: If you also add the `JSONKeyPath` User Info key to your attribute in addition to enums, you'll have to add the `JSONValues` to also tell the mapping between the `enumValues` and the matching possible values found in the JSON. See the [JSON Mapping](#json-mapping) below for more details._
+
+__Example__: On the attribute `type` of the `Shop` entity.
+
+![enum](documentation/enum.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+`Shop.java`:
+
+```java
+package com.niji.data;
+
+import io.realm.RealmObject;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public class Shop extends RealmObject {
+    private String name;
+    private Type type;
+	[...]
+}
+```
+
+`Type.java`:
+
+```java
+package com.niji.data;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public enum Type {
+    TYPE_ONE,
+    TYPE_TWO,
+    TYPE_THREE
+}
+```
+</details>
+
+<details>
+<summary>📑 Sample of the generated code in Objective-C (iOS)</summary>
+
+`RLMShop.h`:
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Imports
+
+#import <Realm/Realm.h>
+#import "RLMTypes.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Interface
+
+@interface RLMShop : RLMObject
+
+#pragma mark - Properties
+
+@property NSString *name;
+@property RLMType type;
+
+@end
+```
+
+`RLMTypes.h`:
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Types
+
+typedef NS_ENUM(int, RLMType) {
+    RLMTypeOne = 0,
+    RLMTypeTwo,
+    RLMTypeThree
+};
+```
+</details>
+
+<details>
+<summary>📑 Sample of the generated code in Swift (iOS)</summary>
+
+`Shop.swift`:
+
+```swift
+/* DO NOT EDIT | Generated by gyro */
+
+import RealmSwift
+
+final class Shop: Object {
+
+    enum Attributes: String {
+        case Name = "name"
+        case OptionalValue = "optionalValue"
+        case Type = "type"
+    }
+
+    dynamic var name: String = ""
+    dynamic var optionalValue: String? = nil
+    var optionalValueEnum: OptValue? {
+        get {
+            guard let optionalValue = optionalValue,
+              let enumValue = OptValue(rawValue: optionalValue)
+              else { return nil }
+            return enumValue
+        }
+        set { optionalValue = newValue?.rawValue ?? nil }
+    }
+
+    dynamic var type: String = ""
+    var typeEnum: Type? {
+        get {
+            guard let enumValue = Type(rawValue: type) else { return nil }
+            return enumValue
+        }
+        set { type = newValue?.rawValue ?? "" }
+    }
+}
+```
+
+`Type.swift`:
+
+```swift
+/* DO NOT EDIT | Generated by gyro */
+
+enum Type: String {
+    case TypeOne = "type_one"
+    case TypeTwo = "type_two"
+    case TypeThree = "type_three"
+}
+```
+
+`OptValue.swift`
+
+```swift
+/* DO NOT EDIT | Generated by gyro */
+
+enum OptValue: String {
+    case OptValueOne = "opt_value_one"
+    case OptValueTwo = "opt_value_two"
+    case OptValueThree = "opt_value_three"
+}
+```
+</details>
+
+> **Note**: For Android and Swift, each enum is created in a separate file. For ObjC, all the enums are created in the file RLMTypes.h
+
+
+---
+
+
+### Add comments to the generated classes
+
+To make the generated code more readable, it's possible to add comments on an entity — e.g. to provide a short description of what this entity is supposed to represent.
+
+To do so, simply add the following key/value pair to your **entity** in your `.xcdatamodel`:
+
+| Key | Value |
+|-----|-------|
+| `comment` | `the_comment_text_here` |
+
+A code commend (`/** … */`) will then be generated (in the `.h` (ObjC), `.swift` (Swift) or `.java` (Android)) just before the class declaration, e.g. to help the developer understand what this class is for.
+
+
+---
+
+
+### JSON Mapping
+
+You can also add the json mapping for each **attribute** or **relationship** with the following key/value pair:
+
+| Key | Value |
+|-----|-------|
+| `JSONKeyPath` | `json_field_name` |
+
+This key is only used when using the `--json` flag.
+
+Currently, this will then generate:
+
+ * Code for `ObjectMapper` on iOS (in the future we plan to generate `Sourcery` annotations instead so that people can choose whatever JSON library they prefer).
+ * `GSON` annotations (`@SerializedName(…)`) for Android
+
+__Example__: On the 'name' attribute of the 'Shop' entity:
+
+![JSONKeyPath](documentation/json.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+Sur Android, nous utilisons la librairie GSON
+
+```java
+package com.niji.data;
+
+import com.google.gson.annotations.SerializedName;
+
+import io.realm.RealmList;
+import io.realm.RealmObject;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public class Shop extends RealmObject {
+
+    @SerializedName("json_name")
+    private String name;
+    private RealmList<Product> products;
+	[...]
+}
+```
+</details>
+
+<details>
+<summary>📑 Sample of the generated code in Objective-C (iOS)</summary>
+
+On iOS, we use the Realm-JSON library and generate them in `MyEntity+JSON.m` category files.
+
+`RLMShop+JSON.m`: 
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Imports
+
+#import "RLMShop+JSON.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Implementation
+
+@implementation RLMShop (JSON)
+
++ (NSDictionary *)JSONInboundMappingDictionary
+{
+    return @{
+        @"json_name" : @"name"
+    };
+}
+
++ (NSDictionary *)JSONOutboundMappingDictionary
+{
+    return @{
+        @"name" : @"json_name"
+    };
+}
+
+@end
+```
+</details>
+
+#### Combine JSONKeyPath and enums
+
+Note that you can **combine that `JSONKeyPath` key with enums** (see [Handling enums](#handling-enums) above). If you declared the User Info keys to make your attribute an enum (`enumType` + `enumValues`) in addition to `JSONKeyPath`, you'll have to also add the `JSONValues` key to list the corresponding values in the JSON for those `enumValues`. 
+
+| Key | Value |
+|-----|-------|
+| `JSONValues` | `valeur_json_1,valeur_json_2,valeur_json_3` |
+
+The number of items listed for that `JSONValues` key must be the same as the number of items listed for the `enumValues` keys, obviously.
+
+__Example__:
+
+![enum_json](documentation/enum_json.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Java (Android)</summary>
+
+```java
+package com.niji.data;
+
+import com.google.gson.annotations.SerializedName;
+
+/* DO NOT EDIT | Generated by gyro */
+
+public enum Type {
+
+    @SerializedName("json_type_one")TYPE_ONE,
+    @SerializedName("json_type_two")TYPE_TWO,
+    @SerializedName("json_type_three")TYPE_THREE
+}
+```
+</details>
+
+<details>
+<summary>📑 Sample of the generated code in Objective-C (iOS)</summary>
+
+`RLMShop+JSON.m`:
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Imports
+
+#import "RLMShop+JSON.h"
+#import "RLMTypes.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Implementation
+
+@implementation RLMShop (JSON)
+
++ (NSValueTransformer *)typeJSONTransformer
+{
+    return [MCJSONValueTransformer valueTransformerWithMappingDictionary:@{
+        @"json_type_one" : @(RLMTypeOne),
+        @"json_type_two" : @(RLMTypeTwo),
+        @"json_type_three" : @(RLMTypeThree)
+    }];
+}
+
+@end
+```
+</details>
+
+
+--- 
+
+
+### Custom ValueTransformers
+
+Only available on iOS (as Android uses the GSON library), custom `ValueTransformers` allows you to e.g. convrt a `String` into an `Int` or a `Date` when parsing the JSON. They are only used when using the `--json` flag.
+
+To create a specific `ValueTransformer` for a field:
+
+* Create your `ValueTransformer` custom class inheriting `NSValueTransformer` and add it to your project
+* Select the attribute that will need this transformer, and in the UserInfo field, add a pair for the **transformer** key whose value should be the name of the `ValueTransformer` class to use:
+
+| Key | Value |
+|-----|-------|
+| `transformer` | `NameOfTheTransformerClass` |
+
+__Example__:
+
+![transformer](documentation/transformer.png)
+
+
+<details>
+<summary>📑 Sample of the generated code in Objective-C (iOS)</summary>
+
+`gyro` will produce the following code. (In this example, attributes `attrDouble` and `attrInteger32` don't have a **transformer** key set in their UserInfo).
+
+```objc
+// DO NOT EDIT | Generated by gyro
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Imports
+
+#import "RLMShop+JSON.h"
+#import "MPDecimalTransformer.h"
+#import "MPIntegerTransformer.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+#pragma mark - Implementation
+
+@implementation RLMShop (JSON)
+
++ (NSDictionary *)JSONInboundMappingDictionary
+{
+    return @{
+        @"attrDecimal" : @"attrDecimal",
+        @"attrDouble" : @"attrDouble",
+        @"attrFloat" : @"attrFloat",
+        @"attrInteger16" : @"attrInteger16",
+        @"attrInteger32" : @"attrInteger32",
+        @"attrInteger64" : @"attrInteger64"
+    };
+}
+
++ (NSDictionary *)JSONOutboundMappingDictionary
+{
+    return @{
+        @"attrDecimal" : @"attrDecimal",
+        @"attrDouble" : @"attrDouble",
+        @"attrFloat" : @"attrFloat",
+        @"attrInteger16" : @"attrInteger16",
+        @"attrInteger32" : @"attrInteger32",
+        @"attrInteger64" : @"attrInteger64"
+    };
+}
+
++ (NSValueTransformer *)attrDecimalJSONTransformer
+{
+    return [[MPDecimalTransformer alloc] init];
+}
+
++ (NSValueTransformer *)attrFloatJSONTransformer
+{
+    return [[MPDecimalTransformer alloc] init];
+}
+
++ (NSValueTransformer *)attrInteger16JSONTransformer
+{
+    return [[MPIntegerTransformer alloc] init];
+}
+
++ (NSValueTransformer *)attrInteger64JSONTransformer
+{
+    return [[MPIntegerTransformer alloc] init];
+}
+
+@end
+
+```
+</details>