Add single-document selection for YAML streams

[MariusStorhaug]

Context

YAML streams may contain multiple documents. PowerShell pipeline consumers often need exactly one document from a stream without manually enumerating and indexing output records.

Official YAML 1.2.2 references:

• YAML streams and documents: https://yaml.org/spec/1.2.2/#32-information-models
• Loading process: https://yaml.org/spec/1.2.2/#412-load
• Normative module spec: spec/Single-Document-Selection.md

Current State

The module supports multi-document streams and emits one pipeline record per document. There is no dedicated document-selection parameter to request a single document by index.

Objective

Provide idiomatic single-document selection for conversion and file import while preserving default multi-document pipeline behavior.

PowerShell Design Considerations

• Use a clear parameter such as -DocumentIndex rather than requiring users to pipe to Select-Object after parsing.
• Consider parameter-set interactions with -AllDocuments style options in representation-preserving commands.
• Keep zero-based or one-based indexing explicit in help and errors; PowerShell arrays are zero-based, but user-facing document numbers need clarity.
• Validation should still parse enough of the stream to reject invalid later documents if the spec requires whole-stream validation.

Tasks

• Add explicit document-index selection for multi-document streams.
• Define out-of-range behavior with a stable error identifier.
• Preserve default behavior of emitting every document.
• Compose document selection with projection options and file import.
• Document pipeline examples for selecting a document from a stream.

Benefits

• Makes multi-document usage easier in scripts.
• Avoids ambiguous post-processing of pipeline output.
• Provides a foundation for representation-preserving commands that address document roots.

Acceptance Criteria

• A caller can request one document by index and receive only that document.
• Out-of-range indexes fail predictably with a classified error.
• Default multi-document output remains unchanged.
• Document selection composes with mapping projection options.
• Help examples clarify index base and behavior.

Related

• Spec folder: spec/Single-Document-Selection.md
• Related closed groundwork: Support multi-document YAML streams #21