PowerToys/doc/devdocs/modules/launcher/plugins/community.valuegenerator.md

# Value Generator Plugin

The Value Generator plugin is used to generate hashes for strings, to calculate base64 encodings and to generate GUIDs versions 1, 3, 4 and 5.

![Image of Value Generator plugin](/doc/images/launcher/plugin/community.valuegenerator.png)

### [`IComputeRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/IComputeRequest.cs)
- Interface for a request for computation
- the `bool Compute()` method must populate the `IsSuccessful` and one of the `Result` and `ErrorMessage` fields
- The result of `string ResultToString()` will be used for the Result's title
- The `Description` field will be used for the Result's subtitle

### [`HashRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Hashing/HashRequest.cs)
- Implements IComputeRequest
- Supports the hashing algorithms from System.Security.Cryptography:
  - MD5
  - SHA1
  - SHA256
  - SHA384
  - SHA512
- If other algorithms are added to System.Security.Cryptography, they can be added to the `_algorithms` dictionary. [`InputParser.ParseInput()`](#inputparser) will need to return a `HashRequest` for the algorithm in the query

### [`Base64Request`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Base64/Base64Request.cs)
- Implements IComputeRequest
- `Compute()` will populate `Result` with the base64 encoding of the byte array passed in the constructor

### [`GUIDRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/GUID/GUIDRequest.cs)
- Implements IComputeRequest
- Uses the [`GUIDGenerator`](#guidgenerator) class to generate or compute the requested GUID

### [`GUIDGenerator`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/GUID/GUIDGenerator.cs)
- Utility class for generating or calculating GUIDs
- Generating GUID versions 1 and 4 is done using builtin APIs. [`UuidCreateSequential`](https://learn.microsoft.com/en-us/windows/win32/api/rpcdce/nf-rpcdce-uuidcreatesequential) for version 1 and `System.Guid.NewGuid()` for version 4
- Versions 3 and 5 take two parameters, a namespace and a name
- The namespace must be a valid GUID or one of the [predefined ones](https://datatracker.ietf.org/doc/html/rfc4122#appendix-C)
- The `PredefinedNamespaces` dictionary contains aliases for the predefined namespaces
- The name can be any string

### [`InputParser`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/InputParser.cs)
- It is responsible only for parsing the query from the user
- Based on the user query, the `ParseInput()` method must return an object that implements the `IComputeRequest` interface or it must throw one of `FormatException` or `ArgumentException`
- Throwing an `ArgumentException` should signal the fact the query contains a mistake that the user can fix (eg. an unsupported hash function, an invalid GUID version, an invalid namespace, etc)
> The error message will be shown to the user and no log message will be created
- Throwing a `FormatException` should signal either:
  - that the query may become valid, and so it does not make sense to show an error just yet (eg. the query does not contain a request yet, a hash request without a string to hash)
  - that the query is completely invalid
> The error message will not be shown to the user but a log message will be created

### Adding a new value generator
1. To add a new value generator, create a folder under `/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/` and inside it add a class that implements `IComputeRequest`.
2. Add any utility classes that are specific to the new generator inside the same folder to keep them separated from the other generators.
3. Modify the `InputParser.ParseInput()` to handle a request for the new generator and return an instance of the class you created in step 1
[PTRun]New plugin: Value generator with hashing functions (#26097) * Add hashing plugin for Run * Cleanup logic for hasher plugin - The IComputeRequest interface should make it easier to implement new generators in the future - The GUID generator can now generate all versions of GUID (a.k.a. UUID) - The input for the hash functions is not quite right. The Wox.Plugin.Query class doesn't actually have a way to ge the raw query as given by the user. The issue is with multiple spaces. An input like "a a a a a" would only be accessible as "a a a a a" using the Query class. So for now, hashing only works correctly if the input doesn't contain multiple consecutive spaces. - Need a way to make clear the usage for generating GUIDv3 and v5, since they take 2 parameters. There are defaults, but they aren't very clear. * Change plugin name to ValueGenerator * Clean up error handling for the input parser * Add result type and description to subtitle * Change the icons * Add Base64 encoding and unit tests This commit adds Base64 encoding as a utility of the value generator plugin. The command is `# base64 *input`. Also added unit tests for the UUID/GUID generator and for the input parser. I don't think tests are necessary for the hashing functions or for the base64 encoder, since those were part of the the system libraries. I'll open a PR for the documentation tomorrow and mark this draft for review. Excluded UUIDv2 * Change icons * Add RawUserQuery to Wox.Plugin.Query Getting the RawUserQuery is necessary to be able to handle queries like `# md5 a a`, where the intent is to get the hash for `a a`. The existing `RawQuery` removes consecutive whitespaces and there was no other way of getting the request as entered by the user. * Add ValueGenerator plugin to installer Also add the unit tests for the plugin to the pipeline. * Small cleanup * Fix spelling * Fix spelling again * Spell check for guiddata * More fixes This commit adds the dev docs explaining the classes in the new plugin. It also fixes the following issues: 1. ValueGenerator was not a dependency for the PowerLauncher project 2. The error message for an invalid SHA variant now displays the supported SHA variants 3. Hash requests now wait for a string to hash (i.e. no longer hash an empty string) 4. GUID v3 and v5 namespace aliases allow lowercase notation 5. Unnecessary debug logs 6. An empty query will now just log "Empty request" 7. An invalid query will also log user query * Spell check fix again * Change error message for unsupported GUID versions * Remove Any CPU from the solution * Add to installer * Remove duplicated ValueGeneratorPluginFolder entry 2023-07-18 17:44:02 +08:00			`# Value Generator Plugin`

			`The Value Generator plugin is used to generate hashes for strings, to calculate base64 encodings and to generate GUIDs versions 1, 3, 4 and 5.`

			`![Image of Value Generator plugin](/doc/images/launcher/plugin/community.valuegenerator.png)`

			### [`IComputeRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/IComputeRequest.cs)
			`- Interface for a request for computation`
			- the `bool Compute()` method must populate the `IsSuccessful` and one of the `Result` and `ErrorMessage` fields
			- The result of `string ResultToString()` will be used for the Result's title
			- The `Description` field will be used for the Result's subtitle

			### [`HashRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Hashing/HashRequest.cs)
			`- Implements IComputeRequest`
			`- Supports the hashing algorithms from System.Security.Cryptography:`
			`- MD5`
			`- SHA1`
			`- SHA256`
			`- SHA384`
			`- SHA512`
			- If other algorithms are added to System.Security.Cryptography, they can be added to the `_algorithms` dictionary. [`InputParser.ParseInput()`](#inputparser) will need to return a `HashRequest` for the algorithm in the query

			### [`Base64Request`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Base64/Base64Request.cs)
			`- Implements IComputeRequest`
			- `Compute()` will populate `Result` with the base64 encoding of the byte array passed in the constructor

			### [`GUIDRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/GUID/GUIDRequest.cs)
			`- Implements IComputeRequest`
			- Uses the [`GUIDGenerator`](#guidgenerator) class to generate or compute the requested GUID

			### [`GUIDGenerator`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/GUID/GUIDGenerator.cs)
			`- Utility class for generating or calculating GUIDs`
			- Generating GUID versions 1 and 4 is done using builtin APIs. [`UuidCreateSequential`](https://learn.microsoft.com/en-us/windows/win32/api/rpcdce/nf-rpcdce-uuidcreatesequential) for version 1 and `System.Guid.NewGuid()` for version 4
			`- Versions 3 and 5 take two parameters, a namespace and a name`
			`- The namespace must be a valid GUID or one of the [predefined ones](https://datatracker.ietf.org/doc/html/rfc4122#appendix-C)`
			- The `PredefinedNamespaces` dictionary contains aliases for the predefined namespaces
			`- The name can be any string`

			### [`InputParser`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/InputParser.cs)
			`- It is responsible only for parsing the query from the user`
			- Based on the user query, the `ParseInput()` method must return an object that implements the `IComputeRequest` interface or it must throw one of `FormatException` or `ArgumentException`
			- Throwing an `ArgumentException` should signal the fact the query contains a mistake that the user can fix (eg. an unsupported hash function, an invalid GUID version, an invalid namespace, etc)
			`> The error message will be shown to the user and no log message will be created`
			- Throwing a `FormatException` should signal either:
			`- that the query may become valid, and so it does not make sense to show an error just yet (eg. the query does not contain a request yet, a hash request without a string to hash)`
			`- that the query is completely invalid`
			`> The error message will not be shown to the user but a log message will be created`

			`### Adding a new value generator`
			1. To add a new value generator, create a folder under `/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/` and inside it add a class that implements `IComputeRequest`.
			`2. Add any utility classes that are specific to the new generator inside the same folder to keep them separated from the other generators.`
			3. Modify the `InputParser.ParseInput()` to handle a request for the new generator and return an instance of the class you created in step 1