Sashimi

1.0.0

en-US/Sashimi.dll-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh">
  <command:command>
    <command:details>
      <command:name>ConvertFrom-RawString</command:name>
      <maml:description>
        <maml:para>Converts one or more PowerShell strings into byte arrays using the specified encoding, optionally inserting a delimiter between pipeline inputs.</maml:para>
      </maml:description>
      <command:verb>ConvertFrom</command:verb>
      <command:noun>RawString</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`ConvertFrom-RawString` converts a PowerShell `string` into a `byte[]` using the specified encoding. This cmdlet is the counterpart of `ConvertTo-RawString` and is typically used when preparing text for binary‑level pipelines, such as feeding encoded data into `Invoke-RawCommand`.</maml:para>
      <maml:para>PowerShell normally converts strings to bytes using UTF‑16, but many native tools expect UTF‑8, Shift_JIS, or other encodings. This cmdlet provides explicit control over the encoding used.</maml:para>
      <maml:para>When multiple strings are provided through the pipeline, `ConvertFrom-RawString` concatenates them by inserting the specified delimiter (if any) before encoding. This allows constructing structured byte sequences such as newline‑separated text or custom‑delimited records.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>ConvertFrom-RawString</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Delimiter</maml:name>
          <maml:description>
            <maml:para>Specifies a delimiter string to insert before each input string after the first one.
When multiple strings are provided through the pipeline, the delimiter is encoded using the selected encoding and written before each subsequent string.
This is useful when constructing multi‑line or structured byte sequences, such as inserting newline characters or custom separators between records.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Encoding</maml:name>
          <maml:description>
            <maml:para>Specifies the text encoding used to convert the input string into bytes.
Any encoding name accepted by `[System.Text.Encoding]::GetEncoding()` is valid.
If omitted, UTF‑8 is used.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>InputString</maml:name>
          <maml:description>
            <maml:para>Specifies the string to convert.
This parameter accepts pipeline input.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Delimiter</maml:name>
        <maml:description>
          <maml:para>Specifies a delimiter string to insert before each input string after the first one.
When multiple strings are provided through the pipeline, the delimiter is encoded using the selected encoding and written before each subsequent string.
This is useful when constructing multi‑line or structured byte sequences, such as inserting newline characters or custom separators between records.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Encoding</maml:name>
        <maml:description>
          <maml:para>Specifies the text encoding used to convert the input string into bytes.
Any encoding name accepted by `[System.Text.Encoding]::GetEncoding()` is valid.
If omitted, UTF‑8 is used.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>InputString</maml:name>
        <maml:description>
          <maml:para>Specifies the string to convert.
This parameter accepts pipeline input.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>System.String</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>One or more strings can be piped to this cmdlet.
Each string is encoded and emitted as a byte[], with the delimiter inserted before subsequent strings when specified.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>The cmdlet outputs one or more byte[] objects representing the encoded input strings, with delimiters inserted when applicable.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>This cmdlet is intended for precise control of text‑to‑binary conversion, especially when interacting with native commands that require specific encodings.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Convert a string to Shift_JIS bytes.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
"こんにちは" | ConvertFrom-RawString -Encoding Shift_JIS
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>This example produces a `byte[]` representing the Shift_JIS encoding of the input string.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>Insert a newline delimiter between multiple input strings.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
"line1","line2","line3" | ConvertFrom-RawString -Delimiter "`n"
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>This produces a single `byte[]` containing the three lines separated by LF.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>ConvertTo-RawString</maml:linkText>
        <command:uri>ConvertTo-RawString.md</command:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Invoke-RawCommand</maml:linkText>
        <command:uri>Invoke-RawCommand.md</command:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>ConvertTo-RawString</command:name>
      <maml:description>
        <maml:para>Converts raw byte input into PowerShell strings using the specified encoding, optionally returning the entire decoded text as a single string.</maml:para>
      </maml:description>
      <command:verb>ConvertTo</command:verb>
      <command:noun>RawString</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`ConvertTo-RawString` converts raw `byte[]` input into PowerShell strings using the specified encoding. Unlike simple `[System.Text.Encoding]::GetString()`, this cmdlet is designed for streaming scenarios: it accepts chunked byte arrays and reconstructs text correctly even when multi‑byte characters span chunk boundaries.</maml:para>
      <maml:para>The cmdlet emits output **one line at a time**, matching PowerShell's line‑oriented pipeline model. This makes it suitable for decoding output from `Invoke-RawCommand`, which emits raw byte chunks from native processes.</maml:para>
      <maml:para>By default, `ConvertTo-RawString` emits one string per line, matching PowerShell’s line‑oriented pipeline model. When the `-Raw` switch is used, the cmdlet returns the entire decoded text as a single string, preserving all newline characters.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>ConvertTo-RawString</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Encoding</maml:name>
          <maml:description>
            <maml:para>Specifies the text encoding used to decode the input bytes.
Any encoding name accepted by `[System.Text.Encoding]::GetEncoding()` is valid.
If omitted, UTF‑8 is used.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>InputBytes</maml:name>
          <maml:description>
            <maml:para>Specifies the byte array to decode.
This parameter accepts pipeline input and supports chunked streaming.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Byte[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Raw</maml:name>
          <maml:description>
            <maml:para>Outputs the entire decoded text as a single string instead of splitting it into lines.
When this switch is specified, the cmdlet disables line‑oriented processing and returns the full decoded content in one object, preserving all newline characters exactly as they appear in the input stream.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Encoding</maml:name>
        <maml:description>
          <maml:para>Specifies the text encoding used to decode the input bytes.
Any encoding name accepted by `[System.Text.Encoding]::GetEncoding()` is valid.
If omitted, UTF‑8 is used.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>InputBytes</maml:name>
        <maml:description>
          <maml:para>Specifies the byte array to decode.
This parameter accepts pipeline input and supports chunked streaming.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Byte[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Raw</maml:name>
        <maml:description>
          <maml:para>Outputs the entire decoded text as a single string instead of splitting it into lines.
When this switch is specified, the cmdlet disables line‑oriented processing and returns the full decoded content in one object, preserving all newline characters exactly as they appear in the input stream.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A single byte can be piped to this cmdlet and will be buffered as part of the decoding stream.</maml:para>
        </maml:description>
      </command:inputType>
      <command:inputType>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A byte array can be piped to this cmdlet. Each chunk is decoded as part of the continuous stream.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.String</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>By default, one string per line is emitted.
When `-Raw` is specified, a single string containing the entire decoded content is emitted.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>This cmdlet is designed for robust decoding of streamed binary data, including multi‑byte encodings where characters may span chunk boundaries.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Decode Shift_JIS bytes into a PowerShell string.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
$bytes = raw some-command
$bytes | ConvertTo-RawString -Encoding Shift_JIS
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>This example decodes the raw byte output of a native command using Shift_JIS.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>Return the entire decoded text as a single string.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
$bytes | ConvertTo-RawString -Raw
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>This example preserves all newline characters and returns the full decoded content in one object.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>ConvertFrom-RawString</maml:linkText>
        <command:uri>ConvertFrom-RawString.md</command:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Invoke-RawCommand</maml:linkText>
        <command:uri>Invoke-RawCommand.md</command:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Invoke-RawCommand</command:name>
      <maml:description>
        <maml:para>Executes a native command and returns its output as raw bytes or decoded text.</maml:para>
      </maml:description>
      <command:verb>Invoke</command:verb>
      <command:noun>RawCommand</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Invoke-RawCommand` executes an external process and exposes its output streams as raw `byte[]` data. Unlike standard PowerShell external command invocation, no text encoding, newline normalization, or string conversion is applied. The command’s stdout and stderr streams are emitted exactly as produced by the process.</maml:para>
      <maml:para>This cmdlet is the foundation of the Sashimi module and enables precise binary‑level interaction with native tools, including those that output non‑UTF8 data, arbitrary binary payloads, or mixed encodings.</maml:para>
      <maml:para>When a ScriptBlock is provided, only the first statement is analyzed and executed as a native command. This allows natural PowerShell syntax while avoiding unintended ScriptBlock execution semantics.</maml:para>
      <maml:para>`Invoke-RawCommand` normally emits raw `byte[]` data with no text encoding or string conversion. When the `-AsString` switch is used, the cmdlet decodes the output into a PowerShell string for convenience.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Invoke-RawCommand</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
          <maml:name>Arguments</maml:name>
          <maml:description>
            <maml:para>Specifies the argument list passed to the native command.
Arguments are forwarded without quoting or encoding changes.
This parameter accepts remaining arguments, allowing natural PowerShell invocation.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Command</maml:name>
          <maml:description>
            <maml:para>Specifies the native executable to run.
This parameter is required when using the Normal parameter set.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>InputBytes</maml:name>
          <maml:description>
            <maml:para>Provides raw byte input to the process’s standard input stream.
When supplied via the pipeline, each `byte[]` chunk is written directly without buffering or encoding.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Byte[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Output</maml:name>
          <maml:description>
            <maml:para>Specifies which output streams to emit.
Valid values are defined by the `Sashimi.OutputType` enum (e.g., `StdOut`, `StdErr`, `Both`).
The selected streams are emitted as raw `byte[]` chunks.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">Sashimi.OutputType</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Invoke-RawCommand</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>InputBytes</maml:name>
          <maml:description>
            <maml:para>Provides raw byte input to the process’s standard input stream.
When supplied via the pipeline, each `byte[]` chunk is written directly without buffering or encoding.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Byte[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Output</maml:name>
          <maml:description>
            <maml:para>Specifies which output streams to emit.
Valid values are defined by the `Sashimi.OutputType` enum (e.g., `StdOut`, `StdErr`, `Both`).
The selected streams are emitted as raw `byte[]` chunks.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">Sashimi.OutputType</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Script</maml:name>
          <maml:description>
            <maml:para>Specifies a ScriptBlock whose first statement is executed as a native command.
This enables natural syntax such as:</maml:para>
            <maml:para>```powershell
raw { git status }
```</maml:para>
            <maml:para>Only the first statement is used; the ScriptBlock is not executed as PowerShell code.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Management.Automation.ScriptBlock</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Invoke-RawCommand</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
          <maml:name>Arguments</maml:name>
          <maml:description>
            <maml:para>Specifies the argument list passed to the native command.
Arguments are forwarded without quoting or encoding changes.
This parameter accepts remaining arguments, allowing natural PowerShell invocation.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>AsString</maml:name>
          <maml:description>
            <maml:para>Returns the command output as decoded text instead of raw bytes.
When this switch is specified, the cmdlet internally decodes the captured `byte[]` stream using the encoding specified by the external process (or UTF‑8 if no encoding can be detected).
This parameter is intended for convenience when working with commands that reliably produce textual output and do not require byte‑level fidelity.</maml:para>
            <maml:para>`-AsString` cannot be used together with `ConvertTo-RawString`, since decoding is performed inside the cmdlet.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Command</maml:name>
          <maml:description>
            <maml:para>Specifies the native executable to run.
This parameter is required when using the Normal parameter set.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>InputBytes</maml:name>
          <maml:description>
            <maml:para>Provides raw byte input to the process’s standard input stream.
When supplied via the pipeline, each `byte[]` chunk is written directly without buffering or encoding.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Byte[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Output</maml:name>
          <maml:description>
            <maml:para>Specifies which output streams to emit.
Valid values are defined by the `Sashimi.OutputType` enum (e.g., `StdOut`, `StdErr`, `Both`).
The selected streams are emitted as raw `byte[]` chunks.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">Sashimi.OutputType</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Invoke-RawCommand</maml:name>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>AsString</maml:name>
          <maml:description>
            <maml:para>Returns the command output as decoded text instead of raw bytes.
When this switch is specified, the cmdlet internally decodes the captured `byte[]` stream using the encoding specified by the external process (or UTF‑8 if no encoding can be detected).
This parameter is intended for convenience when working with commands that reliably produce textual output and do not require byte‑level fidelity.</maml:para>
            <maml:para>`-AsString` cannot be used together with `ConvertTo-RawString`, since decoding is performed inside the cmdlet.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>InputBytes</maml:name>
          <maml:description>
            <maml:para>Provides raw byte input to the process’s standard input stream.
When supplied via the pipeline, each `byte[]` chunk is written directly without buffering or encoding.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Byte[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Output</maml:name>
          <maml:description>
            <maml:para>Specifies which output streams to emit.
Valid values are defined by the `Sashimi.OutputType` enum (e.g., `StdOut`, `StdErr`, `Both`).
The selected streams are emitted as raw `byte[]` chunks.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">Sashimi.OutputType</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Script</maml:name>
          <maml:description>
            <maml:para>Specifies a ScriptBlock whose first statement is executed as a native command.
This enables natural syntax such as:</maml:para>
            <maml:para>```powershell
raw { git status }
```</maml:para>
            <maml:para>Only the first statement is used; the ScriptBlock is not executed as PowerShell code.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Management.Automation.ScriptBlock</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
        <maml:name>Arguments</maml:name>
        <maml:description>
          <maml:para>Specifies the argument list passed to the native command.
Arguments are forwarded without quoting or encoding changes.
This parameter accepts remaining arguments, allowing natural PowerShell invocation.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>AsString</maml:name>
        <maml:description>
          <maml:para>Returns the command output as decoded text instead of raw bytes.
When this switch is specified, the cmdlet internally decodes the captured `byte[]` stream using the encoding specified by the external process (or UTF‑8 if no encoding can be detected).
This parameter is intended for convenience when working with commands that reliably produce textual output and do not require byte‑level fidelity.</maml:para>
          <maml:para>`-AsString` cannot be used together with `ConvertTo-RawString`, since decoding is performed inside the cmdlet.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Command</maml:name>
        <maml:description>
          <maml:para>Specifies the native executable to run.
This parameter is required when using the Normal parameter set.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>InputBytes</maml:name>
        <maml:description>
          <maml:para>Provides raw byte input to the process’s standard input stream.
When supplied via the pipeline, each `byte[]` chunk is written directly without buffering or encoding.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Byte[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Output</maml:name>
        <maml:description>
          <maml:para>Specifies which output streams to emit.
Valid values are defined by the `Sashimi.OutputType` enum (e.g., `StdOut`, `StdErr`, `Both`).
The selected streams are emitted as raw `byte[]` chunks.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">Sashimi.OutputType</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Script</maml:name>
        <maml:description>
          <maml:para>Specifies a ScriptBlock whose first statement is executed as a native command.
This enables natural syntax such as:</maml:para>
          <maml:para>```powershell
raw { git status }
```</maml:para>
          <maml:para>Only the first statement is used; the ScriptBlock is not executed as PowerShell code.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Management.Automation.ScriptBlock</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A single byte value can be piped to `-InputBytes`, which is written directly to the process’s stdin.</maml:para>
        </maml:description>
      </command:inputType>
      <command:inputType>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A byte array can be piped to `-InputBytes`. Each array is forwarded as-is to the process’s stdin stream.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>The cmdlet outputs raw bytes from the selected output streams (`StdOut`, `StdErr`, or both).
Each emitted object is a `byte[]` chunk representing data read from the process.</maml:para>
        </maml:description>
      </command:returnValue>
      <command:returnValue>
        <dev:type>
          <maml:name>System.String</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>Returned when `-AsString` is specified.
The cmdlet decodes the raw output stream into a PowerShell string using the detected or default encoding.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>This cmdlet bypasses all PowerShell text processing and is intended for scenarios requiring exact byte‑level fidelity, such as binary protocols, non‑UTF8 encodings, or tools that emit mixed binary/text output.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Run a command and decode its UTF-16 output manually.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
$bytes = raw wsl.exe --list
$bytes | ConvertTo-RawString -Encoding UTF-16
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>This example captures the raw byte output from `wsl.exe` and converts it to a string using an explicit encoding.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>Convert Shift_JIS bytes using `iconv` and return the result as a decoded string.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
$bytes = ConvertFrom-RawString テスト -Encoding shift_jis
$string = $bytes | Invoke-RawCommand iconv '-f' shift_jis -AsString
# same as:
# `$bytes | Invoke-RawCommand iconv '-f' shift_jis | ConvertTo-RawString`
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>This example returns the command output as a decoded string without requiring `ConvertTo-RawString`.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>ConvertFrom-RawString</maml:linkText>
        <command:uri>ConvertFrom-RawString.md</command:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>ConvertTo-RawString</maml:linkText>
        <command:uri>ConvertTo-RawString.md</command:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Out-RawFile</command:name>
      <maml:description>
        <maml:para>Writes raw byte input to a file without any text encoding or transformation.</maml:para>
      </maml:description>
      <command:verb>Out</command:verb>
      <command:noun>RawFile</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Out-RawFile` writes raw `byte[]` data directly to a file. No text encoding, newline normalization, or PowerShell string conversion is applied. This cmdlet is the counterpart to `Get-Content -AsByteStream` and is designed for binary‑safe pipelines, especially when used with `Invoke-RawCommand`, `ConvertFrom-RawString`, and `ConvertTo-RawString`.</maml:para>
      <maml:para>When `-Append` is specified, data is added to the end of the file. When `-PassThru` is used, the written bytes are emitted back to the pipeline, enabling tee‑like scenarios.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Out-RawFile</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Append</maml:name>
          <maml:description>
            <maml:para>Appends the incoming bytes to the end of the file instead of overwriting it.
If the file does not exist, it is created.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>InputBytes</maml:name>
          <maml:description>
            <maml:para>Specifies the raw byte array to write to the file.
This parameter accepts pipeline input and supports chunked streaming.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Byte[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Path</maml:name>
          <maml:description>
            <maml:para>Specifies the file path to write to.
Relative paths are resolved using PowerShell’s path resolution rules.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Out-RawFile</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Append</maml:name>
          <maml:description>
            <maml:para>Appends the incoming bytes to the end of the file instead of overwriting it.
If the file does not exist, it is created.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>InputBytes</maml:name>
          <maml:description>
            <maml:para>Specifies the raw byte array to write to the file.
This parameter accepts pipeline input and supports chunked streaming.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Byte[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>PassThru</maml:name>
          <maml:description>
            <maml:para>Outputs the written bytes back to the pipeline.
This is useful for chaining additional processing or for tee‑style workflows.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Path</maml:name>
          <maml:description>
            <maml:para>Specifies the file path to write to.
Relative paths are resolved using PowerShell’s path resolution rules.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Append</maml:name>
        <maml:description>
          <maml:para>Appends the incoming bytes to the end of the file instead of overwriting it.
If the file does not exist, it is created.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>InputBytes</maml:name>
        <maml:description>
          <maml:para>Specifies the raw byte array to write to the file.
This parameter accepts pipeline input and supports chunked streaming.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Byte[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>PassThru</maml:name>
        <maml:description>
          <maml:para>Outputs the written bytes back to the pipeline.
This is useful for chaining additional processing or for tee‑style workflows.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Path</maml:name>
        <maml:description>
          <maml:para>Specifies the file path to write to.
Relative paths are resolved using PowerShell’s path resolution rules.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A single byte can be piped to this cmdlet and will be written to the file.</maml:para>
        </maml:description>
      </command:inputType>
      <command:inputType>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A byte array can be piped to this cmdlet. Each chunk is written directly to the file.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.Void</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>By default, this cmdlet produces no output.</maml:para>
        </maml:description>
      </command:returnValue>
      <command:returnValue>
        <dev:type>
          <maml:name>System.Byte</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>When `-PassThru` is specified, the written bytes are emitted back to the pipeline.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>This cmdlet provides the missing counterpart to `Get-Content -AsByteStream`, enabling fully binary‑safe pipelines in PowerShell.
It is optimized for streaming scenarios and large binary data.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Write raw bytes to a file.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
raw some-command | Out-RawFile output.bin
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>This example captures the raw byte output of a native command and writes it directly to `output.bin`.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Invoke-RawCommand</maml:linkText>
        <command:uri>Invoke-RawCommand.md</command:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>ConvertFrom-RawString</maml:linkText>
        <command:uri>ConvertFrom-RawString.md</command:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>ConvertTo-RawString</maml:linkText>
        <command:uri>ConvertTo-RawString.md</command:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
</helpItems>