# 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.