/cc Ilya (@iSazonov)

PR Summary

Refactoring & Streamed Input Support

• Handles continuous data stream input as a single input stream, and will display it in the same manner for both Format-Hex -InputObject $byteArray and $byteArray | Format-Hex
  • This includes arrays / streams of all basic value types.
• Handles jagged streams of input by clumping input objects according to their type. This is not expected to handle a jagged array passed directly to the -InputObject parameter by name.
• Adds ByteCollection properties:
  • Label — stores the type name and a random hexadecimal ID. Used to group objects in output formatting. This can be utilised by, for example, Group-Object, in order to enable downstream cmdlets to handle each group of ByteCollection objects separately, if needed.
  • Ascii — stores the ASCII representation of the bytes in the ByteCollection
  • HexBytes — stores the hexadecimal representation of the bytes in the ByteCollection
• Filters ASCII display to replace control characters with the <?> unicode glyph

Additional tests have been added to cover this behaviour. Details below.

Behaviour of Piped Input

A Primitive Value

1. Each item is converted to bytes and collected into an input buffer.
2. The type of the last InputObject is stored in a private field.
3. If a new InputObject is received of the same type, it is converted to bytes and added to the buffer.
4. If a new InputObject is received of a different type, the buffer is divided into 16-byte segments and each segment is sent to the success output stream as a ByteCollection. Then, the process restarts from the beginning.

System.IO.FileInfo

1. If any data is in the primitives buffer, it is output as described above, the buffer is cleared, as well as the information on what the last type was (resetting the grouping logic).
2. One ByteCollection object is emitted per 16 bytes of the file.
3. All ByteCollection objects are tagged with the input file's path as their Label, which will group their output into a single table.
4. Offset and Count are interpreted as applying to each file, the same way as they would be for -Path inputs.

String

1. If any data is in the primitives buffer, it is output as described above, the buffer is cleared, as well as the information on what the last type was (resetting the grouping logic).
2. All strings are handled on an individual basis (no grouping), and are converted into bytes according to the -Encoding parameter's value.
3. One ByteCollection object is emitted per 16 bytes of the string, and each is tagged with the System.String type name and a shared random hexadecimal ID to ensure that each string is assigned a separate Label group.
4. Offset and Count are interpreted as applying to each input string.

Array of Primitives

1. If any data is in the primitives buffer, it is output as described above, the buffer is cleared, as well as the information on what the last type was (resetting the grouping logic).
2. Each array is treated as a single "group", and will not be grouped with other items in the output.
3. All items in the array are converted into a single chunk of bytes, which then is sliced according to Offset and Count.
4. One ByteCollection object is emitted per 16 bytes, and each is tagged with the array's type and a shared random hexadecimal ID to ensure that each array is assigned a single Label group.

Examples

PR Context

Format-Hex needs a bit more versatility and to be able to handle piped input in a more effective manner.

PR Checklist

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• Change is not breaking
• Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• This PR is ready to merge and is not Work in Progress.
  • If the PR is work in progress, please add the prefix WIP: or [ WIP ] to the beginning of the title (the WIP bot will keep its status check at Pending while the prefix is present) and remove the prefix when the PR is ready.
• User-facing changes
  • Not Applicable
  • OR
  • [Documentation needed]
    • Issue filed: Format-Hex Updates MicrosoftDocs/PowerShell-Docs#4532
• Testing - New and feature
  • N/A or can only be tested interactively
  • OR
  • Make sure you've added a new test if existing tests do not effectively test the code changed
    • Add [feature] to your commit messages if the change is significant or affects feature tests