search

AkiraNetwork / VirtualStorageLibrary

VirtualStorageLibrary Project
https://shimodateakira.github.io/VirtualStorageLibrary/
Other
18 stars 0 forks source link
csharp directory hierarchical library node symboliclink tree

readme

burner.png

Language: English

Version: 0.9.0 License: LGPL-3.0-or-later Platform: .NET 8 Documentation: online Maintenance: active

Welcome to VirtualStorageLibrary!

Project Overview and Purpose

VirtualStorageLibrary is a .NET library that operates entirely in-memory and provides a tree-structured collection. This library offers a foundation for managing hierarchical data structures, supporting items, directories, and symbolic links that encapsulate user-defined types \<T>.
This library is not a file system.
Instead, it was redesigned from scratch to create a more flexible and user-friendly tree structure. The library aims to make it intuitive to reference, traverse, and manipulate nodes by specifying paths.

VirtualStorageLibraryLogo

Project Background

The collections provided by .NET are linear, including types like hash sets, arrays, lists, and dictionaries, which inherently have a linear structure. In contrast, common file systems can be viewed as tree-shaped collections, where elements are managed as nodes in a hierarchical structure. While there are existing libraries that support tree-shaped collections, I couldn’t find one that models a file system-like structure. Therefore, I conceptualized a logical interpretation of a file system and asked, "Can we implement a tree collection purely as objects?" The goal was to create a system that can flexibly manage hierarchical and allow intuitive access.

Table of Contents

[▲]

Key Features

Flexible Tree Structure

Provides a hierarchical structure based on parent-child relationships, allowing flexible node management.

Support for Various Nodes

Supports items, directories, and symbolic links, including user-defined types \<T>.

Intuitive Node Operations via Paths

Offers an intuitive API for referencing, searching, adding, deleting, renaming, copying, and moving nodes using paths.

Link Management

Manages symbolic links with a link dictionary, tracking target path changes.

Circular Reference Prevention

Throws an exception when detecting circular references in paths involving symbolic links.

Flexible Node List Retrieval

Retrieves node lists within directories, filtered, grouped, and sorted by specified node types and attributes.

[▲]

Anticipated Use Cases

Natural Language Processing (NLP)

In natural language processing, tree structures are often used to analyze and parse text data. For instance, parsing results can be represented as syntax trees, visualizing the relationships between elements of a sentence. Tree structures are highly effective for managing such structured data.

The Virtual Storage Library supports managing tree-structured data and accessing nodes via paths, enabling efficient data analysis. Specific scenarios where it is useful include:

This facilitates easier management of complex data structures in NLP tasks and enhances analysis efficiency.

Knowledge Base Systems

In knowledge base systems, it is essential to organize large volumes of documents and information hierarchically, providing efficient searchability. The Virtual Storage Library helps manage such hierarchical structures, enabling users to quickly access the information they need.

Specific scenarios include:

This enables knowledge base systems to efficiently organize and access information, maximizing the utility of information.

Game Development

In game development, managing in-game objects and scenes is important. Particularly when managing hierarchical relationships between objects, the Virtual Storage Library supports dynamic scene changes, contributing to efficient development processes.

Specific scenarios include:

This gives the game development process flexibility and speed, maximizing creative elements.

Hierarchical Clustering

Hierarchical clustering involves grouping and classifying data in a hierarchical manner, managing clustering results as a tree structure and supporting data analysis and visualization. The Virtual Storage Library supports this analysis process.

Specific scenarios include:

This allows hierarchical clustering results to be efficiently managed and visual insights to be gained. The Virtual Storage Library supports this process of data visualization and analysis, aiding data-driven decision-making.

Education and Learning

The source code of the Virtual Storage Library can be used in education and learning, particularly for deepening understanding of programming and data structures.

Specific scenarios include:

Thus, the Virtual Storage Library helps students and learners deepen their understanding of practical programming skills and data structures in an educational setting.

[▲]

Technology Stack

Overview

VirtualStorageLibrary is developed on the .NET 8 platform using the C# language.
This library is not a file system.
It operates entirely in-memory and provides a flexible foundation for managing hierarchical data structures.

Programming Language

Frameworks and Libraries

Tools and Services

[▲]

Target Users

Primary User Groups

The Virtual Storage Library is designed for a broad range of users, including:

Use Cases

The Virtual Storage Library can be used for the following purposes:

Target Industries

The Virtual Storage Library is particularly useful in the following industries:

Development Status and Future Plans

As of 2024/08/09, all essential features for version 1.0.0 have been implemented.
However, some bug fixes, around 30 feature improvements, and refactoring tasks remain.
With version 0.8.0, we aim to gather user feedback, including bug reports and feature enhancement suggestions.
Simultaneously, we plan to work through the remaining tasks for version 0.9.0, targeted for release in October 2024.
During this period, class names, method names, property names, and other elements in the library may change, merge, or be deprecated without notice.
Details will be provided in the release notes, so please check them.
For more information, please refer to Current Issues and Improvement Plans (Japanese).

[▲]

Installation Instructions

Installing with Visual Studio 2022

Using the NuGet Package Manager:

Using the Package Manager Console:

Installing with .NET CLI

Verifying the Installation

Once installed, VirtualStorageLibrary will be added to your project's dependencies, and you can begin using it.
After installation, add the necessary using directives to reference the library in your code.

[▲]

Usage

Simple Example

using AkiraNetwork.VirtualStorageLibrary;

namespace VSLSample01
{
    // User-defined class
    public class Person
    {
        public string Name { get; set; } = string.Empty;
        public int Age { get; set; } = 0;
    }

    internal class Program
    {
        static void Main()
        {
            // Initialize the VirtualStorageSettings
            VirtualStorageSettings.Initialize();

            // Create a VirtualStorage instance
            VirtualStorage<Person> vs = new();

            // Create a Person object
            Person person1 = new() { Name = "John", Age = 20 };

            // Create a VirtualItem instance
            VirtualItem<Person> item1 = new("item1", person1);

            // Add the directory and item to the VirtualStorage instance
            vs.AddDirectory("/home1");
            vs.AddItem("/home1", item1);

            // Retrieve the Person object from the VirtualStorage instance
            Person result = vs.GetItem("/home1/item1").ItemData!;

            // Display the retrieved Person object
            Console.WriteLine($"Name: {result.Name}, Age: {result.Age}");
        }
    }
}

Setting up using

using AkiraNetwork.VirtualStorageLibrary;

This directive is needed to reference the VirtualStorageLibrary namespace. For most features, this is sufficient, but depending on the functionality you want to use, you may also need to include the following namespaces:

using AkiraNetwork.VirtualStorageLibrary.Utilities;
using AkiraNetwork.VirtualStorageLibrary.WildcardMatchers;

Library Initialization

VirtualStorageSettings.Initialize();

This initializes VirtualStorageLibrary. It should be called once at the start of your application code. This initialization configures various settings, such as characters used in paths (delimiters, root, dot, dot-dot), prohibited characters for paths and node names, wildcard matchers, node list display conditions, prefixes for node name generation, etc. Without this initialization, subsequent operations may not function correctly.

Defining a User-Defined Class

public class Person
{
    public string Name { get; set; } = string.Empty;
    public int Age { get; set; } = 0;
}

This defines the user-defined class to be used with VirtualStorageLibrary. VirtualStorageLibrary is a generic collection that can manage instances of user-defined classes in a tree structure. Therefore, in your application, you need to define the class you want to manage. In this simple example, a Person class with name and age properties is defined.

Creating an Instance of the VirtualStorage Class

VirtualStorage<Person> vs = new();

This creates an instance of the VirtualStorage class. Upon creation, only the root directory exists.

Creating an Instance of the User-Defined Class

Person person1 = new() { Name = "John", Age = 20 };

This creates an instance of the user-defined class.

Creating an Instance of the VirtualItem Class

VirtualItem<Person> item1 = new("item1", person1);

This creates an instance of the VirtualItem class. The first parameter of the constructor specifies the node name, and the second parameter specifies the instance of the user-defined class.

Adding a Directory

vs.AddDirectory("/home1");

This adds a directory named "home1" to the root directory. To add subdirectories at once, specify the second parameter (createSubdirectories) as true. The default value of createSubdirectories is false.

vs.AddDirectory("/home1/subdir1/subdir2", true);

Adding an Item

vs.AddItem("/home1", item1);

This adds an instance of the VirtualItem class to the "/home1" directory. The node name for this item will be the name specified when the VirtualItem instance was created. As a result, a node named "/home1/item1" will be created. If a node with the same name already exists in the same directory, an exception will be thrown. However, if the third parameter (overwrite) is set to true, the existing item will be overwritten. The default value of overwrite is false.

vs.AddItem("/home1", item1, true);

Retrieving an Item

Person result = vs.GetItem("/home1/item1").ItemData!;

The GetItem() method retrieves an instance of VirtualItem corresponding to the specified path. The ItemData property of VirtualItem exposes the instance of the user-defined class. As a result, the result will be set to the Person class instance stored at "/home1/item1".

Displaying the Person

Console.WriteLine($"Name: {result.Name}, Age: {result.Age}");

This displays the retrieved Person. The result will be displayed as follows:

Name: John, Age: 20

[▲]

Documentation

For detailed usage instructions and reference information on this library, please refer to the following documentation:

[▲]

Configuration and Customization

The initial settings of this library are automatically configured by calling the VirtualStorageSettings.Initialize() method. This applies all default settings such as path delimiters, root directory names, and prohibited characters. While manual configuration is not required, you can modify settings during application runtime through the VirtualStorageState.State property. For more details, refer to the API Reference.

[▲]

License

This project is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later).

Copyright (C) 2024 Akira Shimodate

VirtualStorageLibrary is free software. This software is distributed under the terms of the GNU Lesser General Public License, version 3, or (at your option) any later version. VirtualStorageLibrary is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. A copy of the GNU Lesser General Public License is saved in the LICENSE file at the root of the repository. If not provided, you can check it here.

Future Commercial License

We are considering offering a commercial license for VirtualStorageLibrary in the future. For more details or to inquire about the commercial license, please contact us at akiranetwork211@gmail.com.

[▲]

Contribution Guidelines

Thank you for your interest in contributing to VirtualStorageLibrary. As it is currently in the pre-release stage, we encourage you to try it out. Your feedback and suggestions are invaluable in helping us improve the library.

Here are some ways you can contribute:

For technical questions and feature suggestions, please use our Discussions forum. Choose the appropriate category:

We are currently not accepting pull requests as the multi-person development system is not yet in place. We look forward to your feedback and suggestions.

We welcome your feedback and look forward to hearing from you!

[▲]

Author and Acknowledgments

Author

This project was developed by Akira Shimodate. It started as a personal project to realize the idea of a virtual storage library, with Akira responsible for the design and implementation of VirtualStorageLibrary.

Acknowledgments

This project heavily relies on the following tools and resources, and we are deeply grateful to their contributors.