hit is a Rust library to handle data structured in tree-like documents with these features:
This library was intended to manage, in memory, deeply nested documents with strictly typed data structures and multiple inner links. That could be the representation of a word processor document, a directory and its files and subfolders with symbolic links...
Every document is structured like a document tree, in a similar way to MongoDB documents. That means a document always start with a root object. In hit an object is defined as a key/value list.
The values can be either be
(TODO : link to property types)
Every object is indexed. That implies :
_id, with a rust String valueThe indexation allows hit to provide (TODO LINK) reference and reference_array type fields. They are inspired by foreign keys in relation databases, and hit enforces consistency rules : you cannot delete an object as long as there are references to it in the document.
The index also allows you to easily find all the references to an object. (TODO: link to method)
Every object in a document must have a (TODO: Link) Model. A model is identified by a string id, and is referenced in the type property of the object. To resolve model definitions from the ids, every instance of hit must be initialized with a (TODO: link) Kernel that contains the definitions.
The models :
field types (TODO: link) and - optionally - validators (TODO : link)hit is a rust library. You can add it to your project by adding this line to your Cargo.toml file :
TODO
hit instancehit instanceTo create a hit data instance, you need a (TODO: link) Kernel with model definitions. One of the core kernels, officially supported by me, is the recursively designed (TODO: link) hit_model, which allows you to modelize models for hit.
To make it more simple, let's start with the basic, although completely useless (TODO: link) hit_test_file_model, that represents a directory/file structure, with links.
We will use ( TODO : link ) Hit::new_with_values to create the model. If you do not have initial values, you can instead use the (TODO : link ) Hit::new function.
```rust use hitfilemodel::create_kernel; use hit::{ Hit, ObjectValue, IndexEntryProperty }; use std::collections::HashMap;
// create the kernel let kernel = create_kernel();
// create a string id for the object let id = "my_id".into();
// initiate the name value for our root object let mut values = HashMap::new(); values.insert("name".into(), ObjectValue::String("name".into()));
// we can now create the hit instance let hitinstance = Hit::newwith_values( id, kernel, values, // you must specify the main model name "file/filesystem" ); ```
hit allows the following property types as values. The (TODO: link) ObjectValue enum handles this type system.
These values are set using the (TODO: link) Hit::set value.
string
a string field accepts rust String values.
number
a number field accepts rust f32 values.
boolean
date
a date field accepts timestamps as rust i64 values.
These fields can only be populated using specific methods from the Hit struct.
sub_object
a sub_object field accepts a single hit object as a value. The field will be the only parent of the object that populates it.
subobjectarray
a sub_object_array field accepts several hit objects as a value. It will likewise be the only possible parent of the objects that populate it.
reference
a reference field accepts references to another object within the same root Hit instance. It cannot be set to an invalid ID, and likewise an object cannot be removed from the root instance if there are references to it. See (TODO: link) mandatory validation.
reference_array
likewise, a reference_array field accepts several references.
The following sub-chapters will explain how to use these value types. The examples will use the previously created hit_test_file_model instance.
You can set a simple value using the (TODO : link) Hit::set method.
Example :
rust
hit_instance::set(
"my_id".into(),
"name".into(),
ObjectValue::String("my_instance_name".into())
).expect("This should set the root object name");
The action may return an error :
HitError::IDNotFound if the model id does not existHitError::PropertyNotFound if the model doesn't have the specified propertyHitError::InvalidDataType if the model property doesn't accept that valueYou can add a subobject to an existing object using the Hit::insert method. You will need to provide :
model_type of the object, which is the id it is known as by the Kernel.String id of the newly inserted object.Hashmap<String, ObjectValue>None in the function call), the object will be inserted at the end of the list.Example :
rust
hit_instance::insert(
"file/folder".into(),
"id2".into(),
Hashmap::new(),
IndexEntryProperty {
id: "my_id".into(),
property: "folders".into(),
},
None,
).expect("Insertion has failed");
hit provides validation for your data. There are two level of validation:
There are some basic data integrity rules that hit models will not let you break. When you set a value or do an operation, if what you're doing violates these rules, the operation will return an error. hit is designed to have only a minimal amount of these errors. These errors are :
ObjectValue that is not accepted by its FieldType, your operation will be rejected.(TODO) : be able to add mandatory validation to a model.
The main validation model is non-blocking : that means you can assign invalid values to properties of your objects.
hit dataTODO: write this chapter
hit relies on Models. Similar to SQL table definitions, Models are instances of the Model struct. A Hit instance relies on a Kernel which is a collection of models (and of plugins too as we'll see later). As a Hit instance has a hierarchical, tree-like structure, it must have a root object, which, like all of its sub-objects, is structured by a Model.
In our (TODO: link to github) hit_test_file_model example, the file/filesystem model is the root object, and contains files and folders sub-objects.
In that part of the guide we will introduce how to create your own kernel, models, as well as plugins.
A model has the following properties:
definition
This is a key/value dictionary. The definition is a struct that implements the ModelField trait. You can write your own Model Fields, but hit comes with standard ones, which match pretty obviously the types defined in the previous chapter :
TODO : create the macro ^^
```
```