feat: added more extension methods, updated documentation

This commit is contained in:
Dylan R. E. Moonfire 2021-12-06 21:19:34 -06:00
parent 7ed8de35c1
commit cca890b061
2 changed files with 217 additions and 2 deletions

View file

@ -2,3 +2,81 @@ MfGames.IO CIL
==============
This a small collection of classes and extensions to make working with System.IO a little bit easier.
## Installation
At the moment, this library is not on [NuGet.org](https://nuget.org/). Instead,
it is hosted at [MyGet](https://www.myget.org/feed/Packages/mfgames).
```
dotnet add package MfGames.IO --source https://www.myget.org/F/mfgames/api/v3/index.json
```
The repository can also be added to a project by setting the `NuGet.Config` file.
```
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="mfgames" value="https://www.myget.org/F/mfgames/api/v3/index.json" protocolVersion="3" />
</packageSources>
</configuration>
```
## Extensions
### DirectoryInfo Extensions
#### `DirectoryInfo? CreateIfMissing(this DirectoryInfo? directory)`
Creates `directory` if it doesn't exist and `directory` is not null. This will
also create any parent directories to duplicate the `mkdir -p directory`
functionality that inspired it.
#### `DirectoryInfo? FindGitRoot(this DirectoryInfo?)`
Finds the Git root from the given directory, using `FindSelfOrParent`.
#### `DirectoryInfo? FindParent(this DirectoryInfo?, Func<DirectoryInfo, bool> match)`
Finds a parent directory that returns true from the given `match`. This does not
check the given `directory`, but only parents. If none are found, this returns
null.
#### `DirectoryInfo? FindSelfOrParent(this DirectoryInfo?, Func<DirectoryInfo, bool> match)`
Finds a parent directory that returns true from the given `match`. This checks
the given `directory` before going to parents. If none are found, this returns
null.
#### `DirectoryInfo GetDirectory(this DirectoryInfo directory, string[] paths)`
The equivalent of `new DirectoryInfo(Path.Combine(directory.FullName, ...paths))`.
#### `FileInfo GetFile(this DirectoryInfo directory, string[] paths)`
The equivalent of `new FileInfo(Path.Combine(directory.FullName, ...paths))`.
#### `bool IsGitRoot(this DirectoryInfo? directory)`
Returns `true` if the given directory is non-null and contains the `.git` folder.
Otherwise, returns false.
### FileInfo Extensions
#### `string ReadAllText(this FileInfo file)`
The same as `File.ReadAllText(file.GetFullPath)`.
#### `string ReadAllText(this FileInfo file, Encoding encoding)`
The same as `File.ReadAllText(file.GetFullPath, encoding)`.
#### `void WriteAllText(this FileInfo file, string text)`
The same as `File.WriteAllText(file.GetFullPath, text)`.
#### `void WriteAllText(this FileInfo file, string text, Encoding encoding)`
The same as `File.WriteAllText(file.GetFullPath, text, encoding)`.

View file

@ -1,4 +1,6 @@
using System;
using System.IO;
using System.Linq;
namespace MfGames.IO.Extensions
{
@ -12,12 +14,14 @@ namespace MfGames.IO.Extensions
/// as needed.
/// </summary>
/// <param name="directory"></param>
public static void CreateIfMissing(this DirectoryInfo? directory)
/// <returns>The directory passed in.</returns>
public static DirectoryInfo? CreateIfMissing(
this DirectoryInfo? directory)
{
// Ignore blanks.
if (directory == null)
{
return;
return directory;
}
// Check the parent first. We don't have to worry about null because
@ -29,6 +33,139 @@ namespace MfGames.IO.Extensions
{
directory.Create();
}
return directory;
}
/// <summary>
/// Searches for the Git root starting at the given directory.
/// </summary>
/// <param name="directory">The directory to start searching.</param>
/// <returns>The directory containing `.git`, otherwise null.</returns>
public static DirectoryInfo? FindGitRoot(this DirectoryInfo? directory)
{
return directory.FindSelfOrParent(IsGitRoot);
}
/// <summary>
/// Searches for a parent that matches the given `match` method. This
/// will not compare the given directory to see if it matches.
/// </summary>
/// <param name="directory">The directory to start searching.</param>
/// <param name="match">The function that takes a directory to determine a match.</param>
/// <returns>A parent directory that matches, otherwise null.</returns>
public static DirectoryInfo? FindParent(
this DirectoryInfo? directory,
Func<DirectoryInfo, bool> match)
{
return directory == null
? null
: FindSelfOrParent(directory.Parent, match);
}
/// <summary>
/// Searches the given directory and parents for the first one that
/// matches (moving up the directory tree). If this does not find
/// anything, then a null will be returned.
/// </summary>
/// <param name="directory">The directory to start searching.</param>
/// <param name="match">The function that takes a directory to determine a match.</param>
/// <returns>A parent directory that matches, otherwise null.</returns>
public static DirectoryInfo? FindSelfOrParent(
this DirectoryInfo? directory,
Func<DirectoryInfo, bool> match)
{
while (true)
{
// Validate our inputs.
if (match == null)
{
throw new ArgumentNullException(nameof(match));
}
// If the directory is null, just return null.
if (directory == null)
{
return null;
}
// Check this directory for a match, otherwise move up.
if (match(directory)) return directory;
directory = directory.Parent;
}
}
/// <summary>
/// Gets a DirectoryInfo by combining the path components with the
/// directory full path.
/// </summary>
/// <param name="directory">The directory to get the root path.</param>
/// <param name="paths">Additional child paths.</param>
/// <returns>A DirectoryInfo of the given path.</returns>
public static DirectoryInfo GetDirectory(
this DirectoryInfo directory,
params string[] paths)
{
if (directory == null)
{
throw new ArgumentNullException(nameof(directory));
}
if (paths == null)
{
throw new ArgumentNullException(nameof(paths));
}
string[] parts = new[] { directory.FullName }
.Union(paths)
.ToArray();
string path = Path.Combine(parts);
var info = new DirectoryInfo(path);
return info;
}
/// <summary>
/// Gets a FileInfo by combining the path components with the directory
/// full path.
/// </summary>
/// <param name="directory">The directory to get the root path.</param>
/// <param name="paths">Additional child paths.</param>
/// <returns>A FileInfo of the given path.</returns>
public static FileInfo GetFile(
this DirectoryInfo directory,
params string[] paths)
{
if (directory == null)
{
throw new ArgumentNullException(nameof(directory));
}
if (paths == null)
{
throw new ArgumentNullException(nameof(paths));
}
string[] parts = new[] { directory.FullName }
.Union(paths)
.ToArray();
string path = Path.Combine(parts);
var info = new FileInfo(path);
return info;
}
/// <summary>
/// Determines if the given directory contains a ".git" folder. If given
/// a null, this will always return false.
/// </summary>
/// <param name="directory">The directory to inspect.</param>
/// <returns>True if the directory contains ".git", otherwise false.</returns>
public static bool IsGitRoot(this DirectoryInfo? directory)
{
return directory != null
&& directory.GetDirectories(".git").Length > 0;
}
}
}