Add new pages.

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.
+```

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<T>()`)
+
+### 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<MagicValueMediaType>` which can be consumed by the built-in resolvers using their `AddMagicValues` methods.

docs/toc.yml

@@ -1,2 +1,6 @@
 - name: ReFuel.StbImage Guide
   href: ReFuel.StbImage.md
+- name: ReMime Guide
+  href: ReMime.md
+- name: ReFile Tool Guide
+  href: ReFile.md