Guides pr/dir structure/guide #22
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
git-journey-begin: --- title: Quick intro guide to dir-structure full: true --- This guide is intended to provide a comprehensive overview of the `dir-structure` crate, which simplifies the representation and manipulation of directory structures in Rust. It covers basic usage, advanced features, and practical examples to help you get started quickly. Each step shows an example directory structure that the code will expect to read or write. This guide is mostly adapted from the [introductory blog post][blog post]. The blog post discusses it in more detail, while this guide focuses on the practical aspects of using the crate. [blog post]: https://dnbln.dev/blog/dir-structure <ScrollyCoding>
git-journey-pre:
## !!steps Basics
The `dir-structure` crate provides an easy way to define and manipulate file system directories in a structured way.
In this guide, we will explore all the features of the `dir-structure` crate.
On the right, you can see a quick example of how to use it, in order to read a directory structure, defined in Rust.
<Mermaid
chart={`
mindmap
root((Root))
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps Writing is also possible
You can easily write an instance back to the file system.
<Mermaid
chart={`
mindmap
root((Root))
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps But what about more complex data types, not just Strings?
`dir-structure` allows you to use more complex data types, such as `Vec<u8>` (for binary files),
any type that implements `FromStr` and `Display`, or even custom types that implement `ReadFrom` and `WriteTo`.
<Mermaid
chart={`
mindmap
root((Root))
input.bin
number.txt
`}
/>
git-journey-pre:
## !!steps Or even serde types?
Yes, you can use serde types as well. You need to tell the library what format to use for serialization and deserialization.
This is an example using JSON, but TOML, YAML, and RON are also supported.
<Mermaid
chart={`
mindmap
root((Root))
input.bin
number.txt
f.json
`}
/>
git-journey-pre:
## !!steps Let's go back to the basics
We have a couple of other features to show, so let's go back to the example in the beginning.
<Mermaid
chart={`
mindmap
root((Root))
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps But what if we had more complex structures?
You can easily nest them.
<Mermaid
chart={`
mindmap
root((Root))
subdir
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps Or yet even more complex structures?
Or even more complex structures, with file-names not known at compile time.
<Mermaid
chart={`
mindmap
root((Root))
subdirs
subdir1
input.txt
output.txt
subdir2
input.txt
output.txt
other_random_subdir
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps Or for extension-only filters?
Extension-only filters are very common, so the library provides a convenient macro to create them.
The code to the right is equivalent to the previous example, but uses the `ext_filter!` macro.
<Mermaid
chart={`
mindmap
root((Root))
subdirs
subdir1.d
input.txt
output.txt
subdir2.d
input.txt
output.txt
))ignored.txt((
))ignoreddir((
))will not be read((
))input.txt((
))output.txt((
`}
/>
git-journey-pre:
## !!steps Or even large directories?
When dealing with large directories, you can use deferred (lazy) reading.
This can be achieved with `DeferredRead`.
<Mermaid
chart={`
mindmap
root((Root))
subdirs
subdir1.d
input.txt
output.txt
subdir2.d
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps And if we want to cache the read values?
The library also exposes a `DeferredReadOrOwn` type, which allows you to cache the read values.
<Mermaid
chart={`
mindmap
root((Root))
subdirs
subdir1.d
input.txt
output.txt
subdir2.d
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps Versioning values
The library also provides a way to version the files, so you can keep track of changes you made to
the directory structure, and only write the files that have changed.
This happens through the `Versioned` wrapper.
<Mermaid
chart={`
mindmap
root((Root))
subdirs
subdir1.d
input.txt
output.txt
subdir2.d
input.txt
output.txt
`}
/>
git-journey-pre:
## !!steps Writing changed values
We've created a `Versioned` wrapper around a `String` value, but we are never modifying it.
If we want to write the changed values, we need to modify the `Versioned` values first.
There are 2 ways to do this:
1. By using its `DerefMut` implementation, which allows you to modify the inner value directly.
2. By using the `edit_eq_check` method, which allows you to modify the value and check if it has changed, with the type's `Eq` implementation.
<Mermaid
chart={`
mindmap
root((Root))
subdirs
subdir1.d
input.txt
output.txt
subdir2.d
input.txt
output.txt
`}
/>
## !!doctooltips DirStructure ## !!doctooltips DirStructureItem::read# ## !!doctooltips DirStructureItem::write# ## !!doctooltips FmtWrapper ## !!doctooltips Json ## !!doctooltips DirChildren ## !!doctooltips Filter ## !!doctooltips ext_filter ## !!doctooltips DeferredRead ## !!doctooltips DirChildren::iter-R `DirChildren<T, F>::iter#` ## !!doctooltips DirChildren::iter_mut-R `DirChildren<T, F>::iter_mut#` ## !!doctooltips DeferredRead::perform_read-R `DeferredRead<T>::perform_read#` ## !!doctooltips DeferredReadOrOwn ## !!doctooltips DeferredReadOrOwn::perform_and_store_read-R `DeferredReadOrOwn<T>::perform_and_store_read#` ## !!doctooltips Versioned ## !!doctooltips Versioned::edit_eq_check-R `Versioned<T>::edit_eq_check#` </ScrollyCoding>
dnbln
force-pushed
the
guides-pr/dir-structure/guide
branch
from
b11db76 to
e17dde8
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.