<commit_before>Description
===========

Lidenbrock is an add-on to Core Data. It is a solution to easily synchronize your Core Data application with some external JSON resources.


Features
==============

* Load new models and synchronize existing ones from a JSON string
* Fetch your data with a single line of code
* Sort your result directly from the predicate format (the SQL way)


Installation
=======

1. git clone <EMAIL>:sixdegrees/lidenbrock.git
2. Import Lidenbrock.framework to your XCode project
3. Add -ObjC and -all_load to Other Link Flags in your project
4. You can now import the framework within your code :

#### Code
    #import <Lidenbrock/Lidenbrock.h>


Using Lidenbrock
========

Lidenbrock only uses one Managed Object Context defined (by default when you create a Core Data project) as <code>YourAppDelegate.managedObjectContext</code>, so make sure this is your Context.

Let's assume the following DB Model (as your .xcdatamodel). All Models are generated as NSManagedObject classes in your source code :

    Recipe
    ----------------
        name (NSString)
        details (NSString)
        ------------
        ingredients (NSSet)


    Igredient
    ----------------
        name (NSString)
        ------------
        recipes (NSSet)


And the following <b>jsonString</b> variable :

    {
        "id"          : "REC1",
        "name"        : "pancake",
        "details"     : "In a large bowl, sift together the flour, egg, milk...",
        "ingredients" : [
            {
                "id"   : "INGR1",
                "name" : "flour"
            },
            {
                "id"   : "INGR2",
                "name" : "egg"
            },
            {
                "id"   : "INGR3",
                "name" : "milk"
            }
        ]
    }


### Load from JSON

In order to load a model from a JSON string, you can use the class method <b>entityFromJson</b> on any of your NSManagedObject class.

    Recipe *recipe = [Recipe entityFromJson: jsonString];

You may also use the instance method :
    
    Recipe *recipe = [Recipe newEntity];
    [recipe loadFromJson: jsonString];


You may now access your ingredients through the <b>ingredients</b> attribute :

    NSArray *ingredients = [recipe.ingredients allObjects];


### Sync from JSON

The previous exemple creates a new entity for every single load.

If you want to retrieve and synchronise existing data, you need to add an attribute called <b>syncID</b> (NSString) to your model.
Lidenbrock will then look at any <b>id</b>, <b>_id</b> or <b>syncID</b> attribute in your JSON data and try to retreive an existing entity based on its value.
If no match can be made, a new entity is created.

The new model is as follow :

    Recipe
    ----------------
        syncID (NSString)
        name (NSString)
        details (NSString)
        ------------
        ingredients (NSSet)


    Igredient
    ----------------
        syncID (NSString)
        name (NSString)
        ------------
        recipes (NSSet)


<b>entityFromJson</b> will now sync existing data

    Recipe *recipe = [Recipe entityFromJson: jsonString];



### Save

You may save your data by calling the <b>save</b> method on your NSManagedObject instance. This is in fact a shortcut that performs a save on the context, saving any other unsaved data.

    [recipe save];

You can also perform a save directly on the context.

    [[NSManagedObjectContext defaultContext] saveDefaultContext];



### Fetch

You can fetch an entity directly from its id (matching syncID). 
If no match can be found, a new entity is created and returned with the new id set as syncID.

    Recipe *recipe = [Recipe entityWithId: @"REC1"];



You can also easily fetch entities from a predicate format.    
    
    NSString *ingredientName = @"egg";
    NSArray *recipes = [Recipe fetch: @"ANY ingredients.name == %@", ingredientName];



### Fetch & sort

You can sort your fetched data by adding a "SORT BY" satement at the end of your predicate format.

    NSArray *recipes = [Recipe fetch: @"ANY ingredients.name == %@ ORDER BY name DESC", ingredientName];

<b>IMPORTANT NOTE : </b> You should not use any "%@" variables in your "SORT BY" satement as the fetch method extracts this statment out of the rest of the format and only apply variables to the real predicate format, as defined by Apple.




<commit_msg>Updated doc<commit_after>Description
===========

Lidenbrock is an add-on to Core Data. It is a solution to easily synchronize your Core Data application with some external JSON resources.


Features
==============

* Load new models and synchronize existing ones from a JSON string
* Fetch your data with a single line of code
* Sort your result directly from the predicate format (the SQL way)


Installation
=======

1. git clone <EMAIL>:sixdegrees/lidenbrock.git
2. Import Lidenbrock.framework to your XCode project
3. Add -ObjC and -all_load to Other Link Flags in your project
4. You can now import the framework within your code :

#### Code
    #import <Lidenbrock/Lidenbrock.h>


Using Lidenbrock
========

Lidenbrock only uses one Managed Object Context defined (by default when you create a Core Data project) as <code>YourAppDelegate.managedObjectContext</code>, so make sure this is your Context.

Let's assume the following DB Model (as your .xcdatamodel). All Models are generated as NSManagedObject classes in your source code :

    Recipe
    ----------------
        name (NSString)
        details (NSString)
        ------------
        ingredients (NSSet)


    Igredient
    ----------------
        name (NSString)
        ------------
        recipes (NSSet)


The following <b>jsonObject</b> variable :

    {
        "id"          : "REC1",
        "name"        : "pancake",
        "details"     : "In a large bowl, sift together the flour, egg, milk...",
        "ingredients" : [
            {
                "id"   : "INGR1",
                "name" : "flour"
            },
            {
                "id"   : "INGR2",
                "name" : "egg"
            },
            {
                "id"   : "INGR3",
                "name" : "milk"
            }
        ]
    }

And the following <b>jsonArray</b> variable :

    [
        {"name" : "flour"},
        {"name" : "egg"},
        {"name" : "milk"}
    ]



### Load from JSON

In order to load a model from a JSON string, you can use the class method <b>entityFromJson</b> on any of your NSManagedObject class.

    Recipe *recipe = [Recipe entityFromJson: jsonObject];

You may also use the instance method :
    
    Recipe *recipe = [Recipe newEntity];
    [recipe loadFromJson: jsonObject];

Loading is recursive so you can now access your ingredients through the <b>ingredients</b> attribute :

    NSArray *ingredients = [recipe.ingredients allObjects];


You can also load an array of objects :

    NSArray *ingredients = [Ingredient entitiesFromJson: jsonArray];


### Sync from JSON

The previous exemple creates a new entity for every single load.

If you want to retrieve and synchronise existing data, you need to add an attribute called <b>syncID</b> (NSString) to your model.
Lidenbrock will then look at any <b>id</b>, <b>_id</b> or <b>syncID</b> attribute in your JSON data and try to retreive an existing entity based on its value.
If no match can be made, a new entity is created.

The new model is as follow :

    Recipe
    ----------------
        syncID (NSString)
        name (NSString)
        details (NSString)
        ------------
        ingredients (NSSet)


    Igredient
    ----------------
        syncID (NSString)
        name (NSString)
        ------------
        recipes (NSSet)


<b>entityFromJson</b> will now sync existing data

    Recipe *recipe = [Recipe entityFromJson: jsonObject];



### Save

You may save your data by calling the <b>save</b> method on your NSManagedObject instance. This is in fact a shortcut that performs a save on the context, saving any other unsaved data.

    [recipe save];

You can also perform a save directly on the context.

    [[NSManagedObjectContext defaultContext] saveDefaultContext];



### Fetch

You can fetch an entity directly from its id (matching syncID). 
If no match can be found, a new entity is created and returned with the new id set as syncID.

    Recipe *recipe = [Recipe entityWithId: @"REC1"];



You can also easily fetch entities from a predicate format.    
    
    NSString *ingredientName = @"egg";
    NSArray *recipes = [Recipe fetch: @"ANY ingredients.name == %@", ingredientName];



### Fetch & sort

You can sort your fetched data by adding a "SORT BY" satement at the end of your predicate format.

    NSArray *recipes = [Recipe fetch: @"ANY ingredients.name == %@ ORDER BY name DESC", ingredientName];

<b>IMPORTANT NOTE : </b> You should not use any "%@" variables in your "SORT BY" satement as the fetch method extracts this statment out of the rest of the format and only apply variables to the real predicate format, as defined by Apple.


What's coming next ?
==============

Lidenbrock is at an early stage of development so a lot of important features are still missing. They should be available in future releases.

* Ability to use more than one Context
* Add a "Limit" statmament to the fetch method
* Delete data
* Load from URL
* Send to URL

Stay tuned!


{'fraction_non_alphanumeric': 0.109191725314566, 'fraction_numerical': 0.0019193857965451055, 'mean_word_length': 2.4788575667655786, 'pattern_counts': {'":': 0, '<': 53, '<?xml version=': 0, '>': 53, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6009218', 'n_tokens_mistral': 2714, 'n_tokens_neox': 2560, 'n_words': 1136}