diff --git a/docs/ReFile.md b/docs/ReFile.md new file mode 100644 index 0000000..85dd295 --- /dev/null +++ b/docs/ReFile.md @@ -0,0 +1,57 @@ +# ReFile Tool Guide + +This is a very simple command that will consume files directories or stdin to resolve +its file types. + +``` +ReFile - Simple Tool demonstrating ReMime + +ReMime Command Line Tool - Determine file Media Type + + refile [-r] file/directory/-... + + file infer a file + directory infer files in directory. Requires -r + - infer from standard input. + -r search files and folders recursively. + -a include hidden files. + -v verbose mode, use full paths. + --list list known mime types. Will ignore files. + --help show this help text. +``` + +### Listing Types +Use `refile --list` to list known media types. + +``` +$ refile --list | head +video/avi +audio/wav +image/vnd.microsoft.icon +image/webp +application/vnd.rar +application/postscript +application/pdf +audio/mp3 +audio/flac +audio/midi +``` + +### Listing Files & Directories +Just pass the path strings into the command line. Use `-r` to recursively +traverse subdirectories. Here is an annotated command output: + +``` +# Lines beginning with # are comments. +# +--- Extension matched. +# |+-- Content matched. +# || +# || File path Media Type +# || ----------------------------- ------------------------ + -- toc.yml application/octet-stream + ec ../../../Downloads/image2.png image/png + e- _site.tar.gz application/gzip + e- index.md text/markdown + e- docfx.json application/json + # Skipping directory docs, set -r to traverse. +``` diff --git a/docs/ReMime.md b/docs/ReMime.md new file mode 100644 index 0000000..77192be --- /dev/null +++ b/docs/ReMime.md @@ -0,0 +1,88 @@ +# ReMime +ReMime is a simple IANA media types detector written in C#. It has it's own +detectors that can be used to detect common files, and it will query the OS +database if it exists. + +## Simplest Usage Example + +The namespace for the library is `ReMime`. + +### Resolving Media Types +```cs +// Will resolve by file extensions. +MediaTypeResolver.TryResolve(pathString, out MediaType type); // returns bool. +MediaTypeResolver.TryResolve(fileInfo, out MediaType type, open: false); // returns MediaTypeResult + +// Will resolve using content. +MediaTypeResolver.TryResolve(stream, out MediaType type); // returns bool. +MediaTypeResolver.TryResolve(byteSpan, out MediaType type); // returns bool. + +// Will resolve using both file extensions and content. +MediaTypeResolver.TryResolve(pathString, stream, out MediaType type); // returns MediaTypeResult. +MediaTypeResolver.TryResolve(pathString, byteSpan, out MediaType type); // returns MediaTypeResult. + +MediaTypeResolver.TryResolve(stream, out MediaType type); // returns bool. +MediaTypeResolver.TryResolve(byteSpan, out MediaType type); // returns bool. +MediaTypeResolver.TryResolve(fileInfo, out MediaType type, open: true); // returns MediaTypeResult +``` + +### `MediaTypeResult` Flags +| Value | Explaination | +|-------------|-----------------------------------------------------------------| +| `None` | Nothing matched if the value returned equals this. | +| `Extension` | Flag indicates the extension matched with the media type. | +| `Content` | Flag indicates the file content matched with the media type. | + +## Adding Custom Resolvers + +You will need to implement the interfaces `IMediaTypeResolver` or `IMediaContentResolver`. +The former will only resolve file extensions, whilst the latter will resolve with both file +extensions and its contents. + +Then call `MediaTypeResolver.AddResolver()` with an instance of your custom resolver. +You can choose a resolution priority, by default the priority is 9999. ReMime resolver +priorities begin with 1000. + +## Adding New Media Types to ReMime Resolvers +ReMime media type resolvers are singletons under `ReMime.ContentResolvers` and `ReMime.Platform`. Currently the following resolvers are extensible: + +* `ReFuel.ContentResolvers.MagicContentResolver` (implements `IMagicValueResolver`) +* `ReFuel.ContentResolvers.RiffResolver` (implements `IMagicValueResolver`) + +Classes that implement `IMagicValueResolver` have `AddMagicValue`/`AddMagicValues` methods +that make it easy to extend. + +### `MagicValue` +A `MagicValue` is a simple class that tries to match a specific string of bytes. It can accept standard FourCC 32-bit integers, or a string with a simple syntax. + +The string syntax expects hexadecimal values by default. The hexadecimal values given +must be byte aligned (no nibbles). Whitespace is ignored. You can start an ASCII sequence +using the single quote `'` character. The ASCII sequence accepts single character C +style escape sequences like `\'`. + +### `MagicValueMediaType` + +This is a simple record that the built-in resolvers use. +```cs +public record MagicValueMediaType(MediaType MediaType, MagicValue[] MagicValues, string[] Extensions); +``` + +Both arrays can be empty, as long as they are a non-null array. (See `Array.Empty()`) + +### Using a JSON File +ReMime includes a JSON serializer that makes it easy to configure the built-in resolvers. +The JSON serializer will ignore comments. + +```jsonc +[ + // List of media type entries. + { + "type": "image/png", // The media type key. + "magic": [ "89'PNG'" ], // List of magic value strings. (optional) + "extensions": [ "png" ] // List of file extensions strings excluding the leading dot. (also optional) + }, +] +``` + +You may wish to include this database file as an embedded resource. Once you have the file +open, you can call `MagicValueDatabaseEntry.GetEntries(str)`. This will return a `List` which can be consumed by the built-in resolvers using their `AddMagicValues` methods. diff --git a/docs/toc.yml b/docs/toc.yml index a250fb3..5c319ce 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,2 +1,6 @@ - name: ReFuel.StbImage Guide - href: ReFuel.StbImage.md \ No newline at end of file + href: ReFuel.StbImage.md +- name: ReMime Guide + href: ReMime.md +- name: ReFile Tool Guide + href: ReFile.md