Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Signed-off-by: Daniil Ermolaev <[email protected]>
  • Loading branch information
0xBLCKLPTN authored Oct 23, 2024
1 parent 598e03e commit d266482
Showing 1 changed file with 79 additions and 135 deletions.
214 changes: 79 additions & 135 deletions Plugins/Alice-Database/README.md
Original file line number Diff line number Diff line change
@@ -1,164 +1,108 @@
<div align="center">
<img src="https://github.com/0xBLCKLPTN/Kingdom-System/blob/alice_database-dev/Docs/illustrations/alice_db_logo.png"/>
<h1> Alice DBMS</h1>
<img src="https://github.com/0xBLCKLPTN/Kingdom-System/blob/alice_database-dev/Docs/illustrations/alice_db_logo.png" alt="Alice DBMS Logo"/>

<!-- Badges with better aesthetics -->
<p>
<a href="https://bazel.build" style="text-decoration: none;">
<img src="https://img.shields.io/badge/Bazel-Supported-brightgreen?style=flat-square" alt="Bazel Supported"/>
</a>
<a href="https://nixos.org/nix/" style="text-decoration: none;">
<img src="https://img.shields.io/badge/Nix-Supported-blue?style=flat-square" alt="Nix Supported"/>
</a>
<a href="https://en.wikipedia.org/wiki/Cross-platform" style="text-decoration: none;">
<img src="https://img.shields.io/badge/Cross%20Platform-Yes-orange?style=flat-square" alt="Cross Platform"/>
</a>
</p>
</div>

# Alice Database
## 🌟 Features

This module implements a simple collection and document management system for storing and manipulating JSON data on the filesystem. It utilizes Serde for JSON serialization/deserialization and logs operations for debugging purposes.
- **JSON Data Handling**: Efficiently store and manipulate JSON documents.
- **Structured Management**: Organize documents into collections for better management.
- **Cross-Platform**: Compatible across multiple operating systems.
- **Extensible**: Easily extend the functionality to meet your specific use cases.
- **ROBUST**: Leveraging Serde for powerful serialization and deserialization.

## Overview
## 📦 Installation

The primary components of this module are `Document`, `Collection`, and `CollectionManager`. The `CollectionManager` handles collections of documents, while `Collection` manages individual documents. Documents are represented as JSON values, allowing for flexible data structures.
To set up Alice DBMS, ensure you have Rust and Cargo installed. You can then add it to your project by including it in your `Cargo.toml`.

## Structures
```toml
[dependencies]
alice_dbms = "0.1" # Replace with the actual version
```

### Document
Then, run:

A struct representing a document in the database.
```bash
cargo build
```

#### Fields
## 🚀 Getting Started

- `name` (String): The name of the document.
- `path` (PathBuf): The file path to the document.
- `json_value` (Option<Value>): The content of the document stored as a JSON `Value`.
Here's a brief example of how to use the Alice DBMS module:

### Collection

A struct representing a collection of documents.

#### Fields

- `name` (String): The name of the collection.
- `documents` (Vec<Document>): A list of associated `Document`s.

### CollectionManager

A struct to manage multiple collections of documents.

#### Fields

- `collections` (Vec<Collection>): A list of collections managed by this manager.

## Methods

### Document Methods

#### `update_rows(key: &str, value: &Value) -> io::Result<()>`

Updates a field in the document.

- **Parameters:**
- `key`: The key of the field to update.
- `value`: The new value for the field.
- **Returns:** Result indicating success or failure.

#### `delete_rows(key: &str) -> io::Result<()>`

Deletes a field in the document.

- **Parameters:**
- `key`: The key of the field to delete.
- **Returns:** Result indicating success or failure.

#### `update_nested_field(parent_key: &str, key: &str, value: &Value) -> io::Result<()>`

Updates a field in a nested JSON object.

- **Parameters:**
- `parent_key`: The parent key of the nested field.
- `key`: The key of the field to update within the parent key.
- `value`: The new value for the nested field.
- **Returns:** Result indicating success or failure.

### Collection Methods

#### `get_document(name: &str) -> Option<&Document>`

Retrieves a document by name.

- **Parameters:**
- `name`: The name of the document to retrieve.
- **Returns:** An `Option` containing a reference to the `Document` if found, or `None` if not found.

#### `get_document_mut(name: &str) -> Option<&mut Document>`

Retrieves a mutable reference to a document by its name.

- **Parameters:**
- `name`: The name of the document to retrieve.
- **Returns:** An `Option` containing a mutable reference to the `Document` if found, or `None` if not found.

#### `add_document(name: &str, content: &str) -> io::Result<()>`

Adds a new document to the collection.

- **Parameters:**
- `name`: The name of the document to create.
- `content`: The content of the document to be written.
- **Returns:** A result indicating success or failure.

#### `delete_document(name: &str) -> io::Result<()>`

Deletes a document from the collection.

- **Parameters:**
- `name`: The name of the document to delete.
- **Returns:** A result indicating success or failure.

### CollectionManager Methods

#### `new(root: &Path) -> Self`

Creates a new `CollectionManager`.
```rust
fn main() -> std::io::Result<()> {
// Define the root path for data storage
let root_path = Path::new("path_to_your_database");
let mut manager = CollectionManager::new(&root_path);

// Add a new collection
manager.add_collection("example_collection").unwrap();

- **Parameters:**
- `root`: The path to the root directory for data storage.
- **Returns:** A new instance of `CollectionManager`.
// Prepare document content
let doc_content = json!({"key": "value"}).to_string();

// Add a new document to the collection
manager.get_collection_mut("example_collection").unwrap()
.add_document("example_doc.json", &doc_content).unwrap();

#### `get_collection_mut(name: &str) -> Option<&mut Collection>`
println!("Document added successfully!");
Ok(())
}
```

Retrieves a mutable reference to a collection by its name.
## 🔍 Testing

- **Parameters:**
- `name`: The name of the collection to retrieve.
- **Returns:** An `Option` containing a mutable reference to the `Collection`, if found.
Alice DBMS comes with a suite of tests to ensure functionality. You can run the tests using:

#### `add_collection(name: &str) -> Option<&mut Collection>`
```bash
cargo test
```

Adds a new collection.
### Example Tests

- **Parameters:**
- `name`: The name of the collection to create.
- **Returns:** An `Option` containing a mutable reference to the newly added `Collection`.
These tests cover the creation, updating, and deletion of documents and collections. For example:

#### `get_collection(name: &str) -> Option<&Collection>`
```rust
#[test]
fn test_create_and_add_document() {
// Test implementation here...
}
```

Gets a collection by name.
## 🤝 Contributing

- **Parameters:**
- `name`: The name of the collection to retrieve.
- **Returns:** An `Option` containing a reference to the `Collection`, if found.
Contributions are welcome! Here’s how you can help:

#### `get_document(collection_name: &str, document_name: &str) -> Option<&Document>`
1. Open an issue if you have a bug to report or a suggestion.
2. Fork the repository.
3. Create a new branch for your feature or bug fix.
4. Submit a pull request.

Gets a document from a specific collection.
## 📄 License

- **Parameters:**
- `collection_name`: The name of the collection the document belongs to.
- `document_name`: The name of the document to retrieve.
- **Returns:** An `Option` containing a reference to the `Document`, if found.
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Usage
## 📧 Contact

Here's a brief example of how to use the module:
For questions or feedback, please reach out to [[email protected]](mailto:[email protected]).

```rust
fn main() -> std::io::Result<()> {
let root_path = Path::new("path_to_your_database");
let mut manager = CollectionManager::new(&root_path);

manager.add_collection("example_collection").unwrap();
let doc_content = json!({"key": "value"}).to_string();
manager.get_collection_mut("example_collection").unwrap().add_document("example_doc.json", &doc_content).unwrap();
}
---

<div align="center">
<p>Happy coding with Alice DBMS! 🚀</p>
</div>
```

0 comments on commit d266482

Please sign in to comment.