Merge pull request #19 from rameel/readme

Update README

README.md

@@ -1,16 +1,21 @@
 <!-- TOC -->
 * [Ramstack.FileProviders](#ramstackfileproviders)
   * [Projects](#projects)
+    * [Ramstack.FileProviders.Extensions](#ramstackfileprovidersextensions)
     * [Ramstack.FileProviders](#ramstackfileproviders-1)
     * [Ramstack.FileProviders.Globbing](#ramstackfileprovidersglobbing)
-    * [Ramstack.FileProviders.Extensions](#ramstackfileprovidersextensions)
+    * [Ramstack.FileProviders.Composition](#ramstackfileproviderscomposition)
   * [Overview](#overview)
     * [Ramstack.FileProviders](#ramstackfileproviders-2)
       * [PrefixedFileProvider](#prefixedfileprovider)
       * [SubFileProvider](#subfileprovider)
       * [ZipFileProvider](#zipfileprovider)
     * [Ramstack.FileProviders.Globbing](#ramstackfileprovidersglobbing-1)
     * [Ramstack.FileProviders.Extensions](#ramstackfileprovidersextensions-1)
+    * [Ramstack.FileProviders.Composition](#ramstackfileproviderscomposition-1)
+      * [Flattening Providers](#flattening-providers)
+      * [Composing Providers](#composing-providers)
+  * [NuGet Packages](#nuget-packages)
   * [Supported versions](#supported-versions)
   * [Contributions](#contributions)
   * [License](#license)
@@ -23,30 +28,44 @@ building upon `Microsoft.Extensions.FileProviders`.
 
 ## Projects
 
-This repository contains three main projects:
+This repository contains projects:
+
+### Ramstack.FileProviders.Extensions
+Offers useful and convenient extensions for `IFileProviders`, bringing its capabilities and experience
+closer to what's provided by the `DirectoryInfo` and `FileInfo` standard classes.
+
+To install the `Ramstack.FileProviders.Extensions` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) in your project,
+run the following command:
+```console
+dotnet add package Ramstack.FileProviders.Extensions
+```
 
 ### Ramstack.FileProviders
 Provides additional implementations of `IFileProvider` including `PrefixedFileProvider`, `SubFileProvider`, and `ZipFileProvider`.
 
-To install the `Ramstack.FileProviders` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders) in your project, run the following command:
+To install the `Ramstack.FileProviders` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders) in your project,
+run the following command:
 ```console
 dotnet add package Ramstack.FileProviders
 ```
 
 ### Ramstack.FileProviders.Globbing
-Represents a .NET library implementing an `IFileProvider` that applies glob-based filtering rules to determine which files to include or exclude.
+Provides an implementation of the `IFileProvider` that filters files using include and/or exclude glob patterns
+for flexible file visibility control.
 
-To install the `Ramstack.FileProviders.Globbing` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) in your project, run the following command:
+To install the `Ramstack.FileProviders.Globbing` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) in your project,
+run the following command:
 ```console
 dotnet add package Ramstack.FileProviders.Globbing
 ```
 
-### Ramstack.FileProviders.Extensions
-Offers useful and convenient extensions for `Microsoft.Extensions.FileProviders`.
+### Ramstack.FileProviders.Composition
+Provides a helper class for flattening and composing `IFileProvider` instances.
 
-To install the `Ramstack.FileProviders.Extensions` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) in your project, run the following command:
+To install the `Ramstack.FileProviders.Composition` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Composition) in your project,
+run the following command:
 ```console
-dotnet add package Ramstack.FileProviders.Extensions
+dotnet add package Ramstack.FileProviders.Composition
 ```
 
 ## Overview
@@ -117,6 +136,7 @@ as if they were originally defined within your project.
 ```
 
 #### SubFileProvider
+
 `SubFileProvider` lets you limit the view of the file system to a specific subdirectory, effectively creating a sandbox.
 
 Example:
@@ -127,6 +147,7 @@ Console.WriteLine(file.Exists);
 ```
 
 #### ZipFileProvider
+
 `ZipFileProvider` enables access to files within ZIP archives as if they were part of the file system.
 
 Example:
@@ -138,8 +159,8 @@ foreach (IFileInfo file in provider.GetDirectoryContents("/"))
 
 ### Ramstack.FileProviders.Globbing
 
-`GlobbingFileProvider` class supports glob pattern matching for file paths, allowing for flexible file selection. You can specify patterns
-for both including and excluding files.
+`GlobbingFileProvider` class filters files using include and/or exclude glob patterns. Include patterns make only matching files visible,
+while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
 
 It relies on the [Ramstack.Globbing](https://www.nuget.org/packages/Ramstack.Globbing) package for its globbing capabilities.
 
@@ -152,7 +173,7 @@ foreach (IFileInfo file in provider.GetDirectoryContents("/"))
 
 ### Ramstack.FileProviders.Extensions
 
-The library provides useful extensions for `IFileProvider`, bringing its capabilities and experience closer to what's being
+Provides useful extensions for `IFileProvider`, bringing its capabilities and experience closer to what's being
 provided by `DirectoryInfo` and `FileInfo` classes.
 
 Simply stated, a `FileNode` knows which directory it is located in, and a directory represented by the `DirectoryNode` class can access
@@ -205,6 +226,60 @@ foreach (FileNode file in provider.EnumerateFiles("/project", pattern: "**/*.md"
     RenderMarkdown(file);
 ```
 
+### Ramstack.FileProviders.Composition
+
+Provides a helper class `FileProviderComposer` for flattening and composing `IFileProvider` instances.
+
+#### Flattening Providers
+
+The `FlattenProvider` method attempts to flatten a given `IFileProvider` into a single list of file providers.
+
+This is especially useful when dealing with nested `CompositeFileProvider` instances, which might have been created during
+different stages of a pipeline or configuration. Flattening helps in removing unnecessary indirectness and improving efficiency
+by consolidating all file providers into a single level.
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Application pipeline configuration
+...
+
+builder.Environment.ContentRootFileProvider = FileProviderComposer.FlattenProvider(
+    builder.Environment.ContentRootFileProvider);
+```
+
+#### Composing Providers
+
+The `ComposeProviders` method combines a list of `IFileProvider` instances into a single `IFileProvider`.
+During this process, all encountered `CompositeFileProvider` instances recursively flattened and merged into a single level.
+This eliminates unnecessary indirectness and streamline the file provider hierarchy.
+
+```csharp
+string packagesPath = Path.Combine(environment.ContentRootPath, "../Packages");
+string themesPath   = Path.Combine(environment.ContentRootPath, "../Themes");
+
+environment.ContentRootFileProvider = FileProviderComposer.ComposeProviders(
+    // Inject external Modules directory
+    new PrefixedFileProvider("/Packages", new PhysicalFileProvider(packagesPath)),
+
+    // Inject external Themes directory
+    new PrefixedFileProvider("/Themes", new PhysicalFileProvider(themesPath)),
+
+    // Current provider
+    environment.ContentRootFileProvider);
+```
+
+In this example, the `ComposeProviders` method handles any unnecessary nesting that might occur, including when the current
+`environment.ContentRootFileProvider` is a `CompositeFileProvider`. This ensures that all file providers merged into a single
+flat structure, avoiding unnecessary indirectness.
+
+
+## NuGet Packages
+- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`, bringing its capabilities and experience closer to what's provided by the `DirectoryInfo` and `FileInfo` classes.
+- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers, including `ZipFileProvider`, `PrefixedFileProvider`, and `SubFileProvider`.
+- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) — A file provider that filters files using include and/or exclude glob patterns. Include patterns make only matching files visible, while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
+- [Ramstack.FileProviders.Composition](https://www.nuget.org/packages/Ramstack.FileProviders.Composition) — Provides a helper class for flattening and composing `IFileProvider`.
+
 ## Supported versions
 
 |      | Version |

src/Ramstack.FileProviders.Composition/README.md

@@ -52,9 +52,9 @@ In this example, the `ComposeProviders` method handles any unnecessary nesting t
 flat structure, avoiding unnecessary indirectness.
 
 ## Related Packages
-- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers.
-- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) — Wraps the file provider, filtering files using glob patterns.
-- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`.
+- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`, bringing its capabilities and experience closer to what's provided by the `DirectoryInfo` and `FileInfo` classes.
+- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers, including `ZipFileProvider`, `PrefixedFileProvider`, and `SubFileProvider`.
+- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) — A file provider that filters files using include and/or exclude glob patterns. Include patterns make only matching files visible, while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
 
 ## Supported versions
 

src/Ramstack.FileProviders.Extensions/README.md

@@ -66,8 +66,8 @@ foreach (FileNode file in provider.EnumerateFiles("/project", pattern: "**/*.md"
 ```
 
 ## Related Packages
-- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers.
-- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) — Wraps the file provider, filtering files and directories using glob patterns.
+- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers, including `ZipFileProvider`, `PrefixedFileProvider`, and `SubFileProvider`.
+- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) — A file provider that filters files using include and/or exclude glob patterns. Include patterns make only matching files visible, while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
 - [Ramstack.FileProviders.Composition](https://www.nuget.org/packages/Ramstack.FileProviders.Composition) — Provides a helper class for flattening and composing `IFileProvider`.
 
 

src/Ramstack.FileProviders.Globbing/README.md

@@ -1,6 +1,7 @@
 # Ramstack.FileProviders.Globbing
 
-Represents a .NET library implementing an `IFileProvider` that applies glob-based filtering rules to determine which files to include or exclude.
+Represents a .NET library implementing an `IFileProvider` that filters files using include and/or exclude glob patterns
+for flexible file visibility control.
 
 ## Getting Started
 
@@ -11,8 +12,8 @@ dotnet add package Ramstack.FileProviders.Globbing
 ```
 
 ## GlobbingFileProvider
-`GlobbingFileProvider` class supports glob pattern matching for file paths, allowing for flexible file selection.
-You can specify patterns for both including and excluding files.
+`GlobbingFileProvider` class filters files using include and/or exclude glob patterns. Include patterns make only matching files visible,
+while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
 
 It relies on the [Ramstack.Globbing](https://www.nuget.org/packages/Ramstack.Globbing) package for its globbing capabilities.
 
@@ -24,8 +25,8 @@ foreach (IFileInfo file in provider.GetDirectoryContents("/"))
 ```
 
 ## Related Packages
-- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers.
-- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`.
+- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`, bringing its capabilities and experience closer to what's provided by the `DirectoryInfo` and `FileInfo` classes.
+- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers, including `ZipFileProvider`, `PrefixedFileProvider`, and `SubFileProvider`.
 - [Ramstack.FileProviders.Composition](https://www.nuget.org/packages/Ramstack.FileProviders.Composition) — Provides a helper class for flattening and composing `IFileProvider`.
 
 

src/Ramstack.FileProviders.Globbing/Ramstack.FileProviders.Globbing.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFramework>net6.0</TargetFramework>
-    <Description>A .NET library implementing a Microsoft.Extensions.FileProviders that filters files based on glob patterns.</Description>
+    <Description>A .NET library implementing a IFileProvider that filters files using include and/or exclude glob patterns.</Description>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <LangVersion>preview</LangVersion>

src/Ramstack.FileProviders/README.md

@@ -92,8 +92,8 @@ foreach (IFileInfo file in provider.GetDirectoryContents("/"))
 ```
 
 ## Related Packages
-- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`.
-- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) — Wraps the file provider, filtering files and directories using glob patterns.
+- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`, bringing its capabilities and experience closer to what's provided by the `DirectoryInfo` and `FileInfo` classes.
+- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) — A file provider that filters files using include and/or exclude glob patterns. Include patterns make only matching files visible, while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
 - [Ramstack.FileProviders.Composition](https://www.nuget.org/packages/Ramstack.FileProviders.Composition) — Provides a helper class for flattening and composing `IFileProvider`.
 
 ## Supported versions

tests/Ramstack.FileProviders.Composition.Tests/FileProviderComposerTests.cs

@@ -1,6 +1,5 @@
 using Microsoft.Extensions.FileProviders;
-
-using Ramstack.FileProviders.Composition.Utilities;
+using Microsoft.Extensions.Primitives;
 
 namespace Ramstack.FileProviders.Composition;
 
@@ -211,4 +210,16 @@ public void FlattenFileProvider_MaintainOrder_WhenComposite()
         Assert.That(provider, Is.InstanceOf<CompositeFileProvider>());
         Assert.That(composite.FileProviders, Is.EquivalentTo(providers));
     }
+
+    private sealed class TestFileProvider : IFileProvider
+    {
+        public IFileInfo GetFileInfo(string subpath) =>
+            new NotFoundFileInfo(subpath);
+
+        public IDirectoryContents GetDirectoryContents(string subpath) =>
+            NotFoundDirectoryContents.Singleton;
+
+        public IChangeToken Watch(string? filter) =>
+            NullChangeToken.Singleton;
+    }
 }