Editing Magritte (section)

=== Managing stashes ===

Managing stashes is a fundamental aspect of using Magritte. A stash is a set of root nodes and their components stored under a qualified name, which is the absolute path of the stash relative to the root folder of the stashes store. Effectively managing stashes is essential for structuring and persisting the graph you are working with in Magritte. In this example, we will work with a graph of cars, being the name of the module car. This is important to consider as all the generated code will contain this name "Car".

When using Magritte, you assign a stash qualified name to each root element to organize your graph. There are three primary operations involving stashes: loading the graph from scratch, saving information to the graph, and creating root nodes.

==== Loading the Graph from Scratch ====
When initializing the system, you must decide which stashes to load into memory. This step is crucial as it determines the structure and components available in your graph at the start. Here is a code example to demonstrate how to load specific stashes:

    carGraph = CarGraph.load("car1", "car2", "car3");
    carGraph = CarGraph.load(store).loadStashes("car1", "car2", "car3");


Here we present two different ways to load the stashes of a empty graph. One for an in memory graph with no store and the second providing the store (check Stores subsection) for persisting the information.

==== Saving Information to the Graph ====
Whenever you save a root node, all root nodes associated with the stash of that node are saved as well. You also have the option to save a particular stash or all stashes. This ensures that your graph's data is consistently updated and preserved. Below is a code example for saving stashes:

    Car car1 = carGraph.car(0);
    car1.save$();
    carGraph.core$().save("car1");
    carGraph.core$().saveAll();

First line is retrieving the first car of the graph. This is a wrapped graph (see Wrapping section) in which you can retrieve all the root elements that were declared in the model. In the second line we are saving this node and all the nodes that are in the same stash. The third line is equivalent to the second line but in this case we are making explicit that we want to save the stash "car1". Note we use the "core$" function to access low level functions of the graph. Also under core$ we have the option to save the whole graph by using saveAll as it can be seen in the last line.

==== Creating Root Nodes ====
When you create a root node, you must specify the stash in which it will be saved. This organization helps maintain the structure and integrity of your graph. The following code example illustrates how to create a root node within a specific stash:

    Car car4 = carGraph.create("car4").car("tesla");
    Car car5 = carGraph.create("car4", "tesla").car("tesla");

In this example we are creating a new car in the stash "car4". Take into consideration that is it also possible to define the name of the node as it is seen in the last line. If this is not provided a random UUID will be assigned as the name of the node. The name should not contain $ and . symbols as they are used to split the qualified name to provide an structure.