diff --git a/Sources/PSWritePDF/Cmdlets/CmdletClosePDF.cs b/Sources/PSWritePDF/Cmdlets/CmdletClosePDF.cs index 3a8914f..efcd303 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletClosePDF.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletClosePDF.cs @@ -3,9 +3,34 @@ namespace PSWritePDF.Cmdlets; +/// Closes an open PDF document. +/// Disposes the PdfDocument instance and releases associated resources. +/// +/// +/// Note +/// After closing, the document cannot be used further. +/// +/// +/// +/// Close a document. +/// +/// PS> Close-PDF -Document $pdf +/// +/// Closes the specified PDF document. +/// +/// +/// Pipe a document. +/// +/// PS> $pdf | Close-PDF +/// +/// Closes the document passed through the pipeline. +/// +/// MS Learn +/// Project documentation [Cmdlet("Close", "PDF")] public class CmdletClosePDF : PSCmdlet { + /// PDF document to close. [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)] public PdfDocument Document { get; set; } = null!; diff --git a/Sources/PSWritePDF/Cmdlets/CmdletConvertHTMLToPDF.cs b/Sources/PSWritePDF/Cmdlets/CmdletConvertHTMLToPDF.cs index 8fab095..a12606f 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletConvertHTMLToPDF.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletConvertHTMLToPDF.cs @@ -8,6 +8,30 @@ namespace PSWritePDF.Cmdlets; +/// Converts HTML content to a PDF file. +/// Accepts HTML from a URI, string content, or file and writes a PDF to disk. +/// +/// +/// Note +/// Existing output files are overwritten when -Force is specified. +/// +/// +/// +/// Convert from URI. +/// +/// PS> Convert-HTMLToPDF -Uri 'https://example.com' -OutputFilePath 'page.pdf' +/// +/// Downloads the page and saves it as PDF. +/// +/// +/// Convert from file with CSS. +/// +/// PS> Convert-HTMLToPDF -FilePath 'index.html' -CssFilePath 'style.css' -OutputFilePath 'out.pdf' +/// +/// Applies the specified CSS and writes the PDF. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsData.Convert, "HTMLToPDF", DefaultParameterSetName = ParameterSetNames.Uri, SupportsShouldProcess = true)] public class CmdletConvertHTMLToPDF : AsyncPSCmdlet { @@ -18,27 +42,35 @@ private static class ParameterSetNames public const string File = "File"; } + /// URI of the HTML page. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.Uri)] public string Uri { get; set; } + /// Raw HTML content. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.Content)] public string Content { get; set; } + /// Path to an HTML file. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.File)] public string FilePath { get; set; } + /// Output PDF path. [Parameter(Mandatory = true)] public string OutputFilePath { get; set; } + /// Open the PDF after creation. [Parameter] public SwitchParameter Open { get; set; } + /// Overwrite existing files. [Parameter] public SwitchParameter Force { get; set; } + /// Base URI for relative links. [Parameter] public string BaseUri { get; set; } + /// Paths to CSS files to include. [Parameter] public string[] CssFilePath { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletConvertPDFToText.cs b/Sources/PSWritePDF/Cmdlets/CmdletConvertPDFToText.cs index 78b2b21..a87b0c2 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletConvertPDFToText.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletConvertPDFToText.cs @@ -9,23 +9,52 @@ namespace PSWritePDF.Cmdlets; +/// Converts PDF pages to plain text. +/// Extracts text from specified pages of a PDF document using iText strategies. +/// +/// +/// Note +/// Protected documents may require the IgnoreProtection switch to extract text. +/// +/// +/// +/// Extract text from a PDF. +/// +/// PS> Convert-PDFToText -FilePath 'file.pdf' +/// +/// Returns text objects for each page. +/// +/// +/// Save extracted text to a file. +/// +/// PS> Convert-PDFToText -FilePath 'file.pdf' -OutFile 'output.txt' +/// +/// Writes combined text to the specified file. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsData.Convert, "PDFToText")] [OutputType(typeof(PSObject))] public class CmdletConvertPDFToText : PSCmdlet { + /// Path to the PDF file. [Parameter(Mandatory = true, ValueFromPipeline = true, ValueFromPipelineByPropertyName = true)] [Alias("FullName")] public string FilePath { get; set; } = string.Empty; + /// Pages to extract. [Parameter] public int[] Page { get; set; } = Array.Empty(); + /// Extraction strategy to use. [Parameter] public PdfExtractionStrategyName ExtractionStrategy { get; set; } = PdfExtractionStrategyName.Simple; + /// Ignore document protection. [Parameter] public SwitchParameter IgnoreProtection { get; set; } + /// Optional output file. [Parameter] public string? OutFile { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletGetPDF.cs b/Sources/PSWritePDF/Cmdlets/CmdletGetPDF.cs index daaf05d..4794d39 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletGetPDF.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletGetPDF.cs @@ -5,13 +5,39 @@ namespace PSWritePDF.Cmdlets; +/// Opens an existing PDF file. +/// Returns an iText PdfDocument for further processing. +/// +/// +/// Note +/// The caller must dispose the returned document. +/// +/// +/// +/// Load a PDF. +/// +/// PS> Get-PDF -FilePath 'doc.pdf' +/// +/// Returns a PdfDocument instance. +/// +/// +/// Ignore protection. +/// +/// PS> Get-PDF -FilePath 'doc.pdf' -IgnoreProtection +/// +/// Opens a protected PDF for reading. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Get, "PDF")] [OutputType(typeof(PdfDocument))] public class CmdletGetPDF : PSCmdlet { + /// Path to the PDF file. [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)] public string FilePath { get; set; } = null!; + /// Ignore document protection. [Parameter] public SwitchParameter IgnoreProtection { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFAction.cs b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFAction.cs index f582504..8e63433 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFAction.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFAction.cs @@ -4,6 +4,30 @@ namespace PSWritePDF.Cmdlets; +/// Gets numeric values of PDF actions. +/// Converts PdfActionName values to their integer representation or lists all names. +/// +/// +/// Note +/// Action names correspond to constants defined in iText. +/// +/// +/// +/// Get integer value for an action. +/// +/// PS> Get-PDFAction -Action Hide +/// +/// Returns the numeric constant for the Hide action. +/// +/// +/// List all action names. +/// +/// PS> Get-PDFAction -All +/// +/// Displays all available action names. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Get, "PDFAction", DefaultParameterSetName = ParameterSetNames.ByName)] [Alias("Get-PDFConstantAction")] [OutputType(typeof(int), ParameterSetName = new[] { ParameterSetNames.ByName })] @@ -16,9 +40,11 @@ private static class ParameterSetNames public const string All = "All"; } + /// Action name to translate. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.ByName)] public PdfActionName Action { get; set; } + /// Return all action names. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.All)] public SwitchParameter All { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFDetails.cs b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFDetails.cs index 6529dc0..8cf948e 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFDetails.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFDetails.cs @@ -4,10 +4,35 @@ namespace PSWritePDF.Cmdlets; +/// Gets descriptive information about a PDF document. +/// Returns metadata, margins, page sizes, and other details. +/// +/// +/// Note +/// The document is inspected but not modified. +/// +/// +/// +/// Retrieve document details. +/// +/// PS> Get-PDFDetails -Document $pdf +/// +/// Outputs a PdfDocumentDetails object. +/// +/// +/// Pipe from New-PDF. +/// +/// PS> New-PDF -FilePath 'out.pdf' | Get-PDFDetails +/// +/// Creates a PDF and immediately inspects it. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Get, "PDFDetails")] [OutputType(typeof(PdfDocumentDetails))] public class CmdletGetPDFDetails : PSCmdlet { + /// PDF document to analyze. [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)] public PdfDocument Document { get; set; } = null!; diff --git a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFFormField.cs b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFFormField.cs index 2e5d1f3..7748a14 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFFormField.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFFormField.cs @@ -5,9 +5,34 @@ namespace PSWritePDF.Cmdlets; +/// Retrieves form fields from a PDF document. +/// Enumerates AcroForm fields and returns their names and objects. +/// +/// +/// Note +/// The cmdlet emits warnings if the document contains no forms. +/// +/// +/// +/// List form fields. +/// +/// PS> Get-PDFFormField -PDF $pdf +/// +/// Outputs form field information. +/// +/// +/// Stop on read errors. +/// +/// PS> Get-PDFFormField -PDF $pdf -ErrorAction Stop +/// +/// Throws a terminating error if forms cannot be read. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Get, "PDFFormField")] public class CmdletGetPDFFormField : PSCmdlet { + /// PDF document to inspect. [Parameter(Mandatory = true)] public PdfDocument PDF { get; set; } = null!; diff --git a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFPageSize.cs b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFPageSize.cs index f33185a..c00c4a1 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFPageSize.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFPageSize.cs @@ -4,6 +4,30 @@ namespace PSWritePDF.Cmdlets; +/// Gets standard PDF page sizes. +/// Returns an iText PageSize or enumerates available page size names. +/// +/// +/// Note +/// Page size names correspond to PdfPageSizeName enumeration values. +/// +/// +/// +/// Get size for A4. +/// +/// PS> Get-PDFPageSize -PageSize A4 +/// +/// Returns the iText page size for A4. +/// +/// +/// List all page sizes. +/// +/// PS> Get-PDFPageSize -All +/// +/// Displays all supported page size names. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Get, "PDFPageSize", DefaultParameterSetName = ParameterSetNames.ByName)] [Alias("Get-PDFConstantPageSize")] [OutputType(typeof(iText.Kernel.Geom.PageSize), ParameterSetName = new[] { ParameterSetNames.ByName })] @@ -16,9 +40,11 @@ private static class ParameterSetNames public const string All = "All"; } + /// Page size name to retrieve. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.ByName)] public PdfPageSizeName PageSize { get; set; } + /// Return all page size names. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.All)] public SwitchParameter All { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFVersion.cs b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFVersion.cs index f3e1f69..bc2313a 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletGetPDFVersion.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletGetPDFVersion.cs @@ -4,6 +4,30 @@ namespace PSWritePDF.Cmdlets; +/// Retrieves PDF version information. +/// Returns a specific PDF version constant or lists all available versions. +/// +/// +/// Note +/// Version names must match those defined by iText. +/// +/// +/// +/// Get a specific version. +/// +/// PS> Get-PDFVersion -Version PDF_2_0 +/// +/// Returns the iText version constant for PDF 2.0. +/// +/// +/// List all versions. +/// +/// PS> Get-PDFVersion -All +/// +/// Displays all supported PDF versions. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Get, "PDFVersion", DefaultParameterSetName = ParameterSetNames.ByName)] [Alias("Get-PDFConstantVersion")] [OutputType(typeof(iText.Kernel.Pdf.PdfVersion), ParameterSetName = new[] { ParameterSetNames.ByName })] @@ -16,9 +40,11 @@ private static class ParameterSetNames public const string All = "All"; } + /// Version name to translate. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.ByName)] public PdfVersionName Version { get; set; } + /// Return all version names. [Parameter(Mandatory = true, ParameterSetName = ParameterSetNames.All)] public SwitchParameter All { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletMergePDF.cs b/Sources/PSWritePDF/Cmdlets/CmdletMergePDF.cs index 405164b..9a88915 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletMergePDF.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletMergePDF.cs @@ -6,15 +6,42 @@ namespace PSWritePDF.Cmdlets; +/// Merges multiple PDF files into one. +/// Combines input PDFs in order and saves the result to a specified file. +/// +/// +/// Note +/// Existing output files are overwritten without prompt. +/// +/// +/// +/// Merge two files. +/// +/// PS> Merge-PDF -InputFile 'a.pdf','b.pdf' -OutputFile 'merged.pdf' +/// +/// Creates a single PDF containing pages from both inputs. +/// +/// +/// Merge ignoring protection. +/// +/// PS> Merge-PDF -InputFile $files -OutputFile 'all.pdf' -IgnoreProtection +/// +/// Processes protected files as well. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsData.Merge, "PDF")] public class CmdletMergePDF : PSCmdlet { + /// Paths to PDF files to merge. [Parameter(Mandatory = true)] public string[] InputFile { get; set; } + /// Path for the merged output. [Parameter(Mandatory = true)] public string OutputFile { get; set; } + /// Ignore protection on input files. [Parameter] public SwitchParameter IgnoreProtection { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDF.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDF.cs index 0fb9314..6724178 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDF.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDF.cs @@ -8,23 +8,57 @@ namespace PSWritePDF.Cmdlets; +/// Creates a new PDF document. +/// Builds a PDF file and optionally executes script block content to populate the document. +/// +/// +/// Note +/// Existing files at the target path are overwritten without confirmation. +/// +/// +/// +/// Create an empty PDF file. +/// +/// PS> New-PDF -FilePath 'out.pdf' +/// +/// Generates a PDF at the specified path. +/// +/// +/// Create and display a PDF. +/// +/// PS> New-PDF -FilePath 'out.pdf' -Show +/// +/// The created PDF opens in the default viewer. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDF")] public class CmdletNewPDF : PSCmdlet { + /// Script block defining PDF content. [Parameter(Position = 0)] public ScriptBlock? PDFContent { get; set; } + /// Output file path. [Parameter(Mandatory = true)] public string FilePath { get; set; } = string.Empty; + /// PDF version to use. [Parameter] public string? Version { get; set; } + /// Left margin in points. [Parameter] public double? MarginLeft { get; set; } + /// Right margin in points. [Parameter] public double? MarginRight { get; set; } + /// Top margin in points. [Parameter] public double? MarginTop { get; set; } + /// Bottom margin in points. [Parameter] public double? MarginBottom { get; set; } + /// Initial page size. [Parameter] public PdfPageSize? PageSize { get; set; } + /// Rotate the page 90 degrees. [Parameter] public SwitchParameter Rotate { get; set; } + /// Show the PDF after creation. [Parameter, Alias("Open")] public SwitchParameter Show { get; set; } protected override void ProcessRecord() { diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFArea.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFArea.cs index 1c79e4f..5f1f533 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFArea.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFArea.cs @@ -4,15 +4,42 @@ namespace PSWritePDF.Cmdlets; +/// Creates a new area break for PDF content. +/// Generates an iText AreaBreak object used to separate sections in a PDF document. +/// +/// +/// Note +/// The returned area break must be added to a PDF document to take effect. +/// +/// +/// +/// Create a default area break. +/// +/// PS> New-PDFArea +/// +/// Creates a break with default settings. +/// +/// +/// Create a rotated A4 area break. +/// +/// PS> New-PDFArea -PageSize A4 -Rotate +/// +/// Produces a break on a landscape A4 page. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFArea")] public class CmdletNewPDFArea : PSCmdlet { + /// Type of area break to insert. [Parameter] public AreaBreakType AreaType { get; set; } = AreaBreakType.NEXT_AREA; + /// Page size for the new area. [Parameter] public PdfPageSizeName? PageSize { get; set; } + /// Rotate the page to landscape. [Parameter] public SwitchParameter Rotate { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFDocument.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFDocument.cs index 279c2fd..039d666 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFDocument.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFDocument.cs @@ -4,9 +4,34 @@ namespace PSWritePDF.Cmdlets; +/// Wraps a PDF document in an iText Document. +/// Creates a layout Document object for further content operations. +/// +/// +/// Note +/// The caller is responsible for closing the document. +/// +/// +/// +/// Create a document object. +/// +/// PS> New-PDFDocument -PDF $pdf +/// +/// Returns an iText layout document. +/// +/// +/// Store document for later use. +/// +/// PS> $doc = New-PDFDocument -PDF $pdf +/// +/// Assigns the document to a variable. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFDocument")] public class CmdletNewPDFDocument : PSCmdlet { + /// Underlying PDF document. [Parameter(Mandatory = true)] public PdfDocument PDF { get; set; } = null!; diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFImage.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFImage.cs index 9a86695..29518fd 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFImage.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFImage.cs @@ -5,13 +5,42 @@ namespace PSWritePDF.Cmdlets; +/// Adds an image to the current PDF document. +/// Loads an image from disk and inserts it with optional size and background color. +/// +/// +/// Note +/// Image files must exist; missing files cause a terminating error. +/// +/// +/// +/// Add an image. +/// +/// PS> New-PDFImage -ImagePath 'logo.png' +/// +/// Inserts the image using its original dimensions. +/// +/// +/// Add image with size. +/// +/// PS> New-PDFImage -ImagePath 'logo.png' -Width 100 -Height 50 +/// +/// Scales the image to the specified size. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFImage")] public class CmdletNewPDFImage : PSCmdlet { + /// Path to the image file. [Parameter(Mandatory = true)] public string ImagePath { get; set; } = string.Empty; + /// Desired image width. [Parameter] public int Width { get; set; } + /// Desired image height. [Parameter] public int Height { get; set; } + /// Background color behind the image. [Parameter] public PdfColor? BackgroundColor { get; set; } + /// Opacity of the background color. [Parameter] public double? BackgroundColorOpacity { get; set; } protected override void ProcessRecord() { diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFInfo.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFInfo.cs index d9f09c0..61d961e 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFInfo.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFInfo.cs @@ -4,18 +4,50 @@ namespace PSWritePDF.Cmdlets; +/// Applies metadata to a PDF document. +/// Sets title, author, keywords, and optional creation/modification dates. +/// +/// +/// Note +/// Changes affect the in-memory document and require saving to persist. +/// +/// +/// +/// Add basic metadata. +/// +/// PS> New-PDFInfo -PDF $pdf -Title 'Report' +/// +/// Sets the document title. +/// +/// +/// Add creation date. +/// +/// PS> New-PDFInfo -PDF $pdf -AddCreationDate +/// +/// Stores the current time as the creation date. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFInfo")] public class CmdletNewPDFInfo : PSCmdlet { + /// PDF document to modify. [Parameter(Mandatory = true)] public PdfDocument PDF { get; set; } = null!; + /// Document title. [Parameter] public string? Title { get; set; } + /// Document author. [Parameter] public string? Author { get; set; } + /// Document creator. [Parameter] public string? Creator { get; set; } + /// Document subject. [Parameter] public string? Subject { get; set; } + /// Keywords to add. [Parameter] public string[]? Keywords { get; set; } + /// Add creation date metadata. [Parameter] public SwitchParameter AddCreationDate { get; set; } + /// Add modification date metadata. [Parameter] public SwitchParameter AddModificationDate { get; set; } protected override void ProcessRecord() diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFList.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFList.cs index 3d6f092..0ea4bf3 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFList.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFList.cs @@ -6,21 +6,57 @@ namespace PSWritePDF.Cmdlets; +/// Adds a list of items to the current PDF document. +/// Creates a bullet or numbered list using provided items or a script block. +/// +/// +/// Note +/// The list is only added if a document is available in the session. +/// +/// +/// +/// Create a list from strings. +/// +/// PS> New-PDFList -Items 'one','two' +/// +/// Adds a simple bullet list. +/// +/// +/// Generate list via script block. +/// +/// PS> New-PDFList -ListItems { 1..3 } +/// +/// Creates a list using numbers returned from the script block. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFList")] public class CmdletNewPDFList : PSCmdlet { + /// Script block producing list items. [Parameter(Position = 0, ParameterSetName = "ScriptBlock")] public ScriptBlock? ListItems { get; set; } + /// Items to include in the list. [Parameter(Position = 0, ParameterSetName = "Items")] public string[]? Items { get; set; } + /// List indentation in points. [Parameter] public double? Indent { get; set; } + /// Symbol style for the list. [Parameter] public ListSymbol Symbol { get; set; } = ListSymbol.Hyphen; + /// Font for list items. [Parameter] public PdfFontName? Font { get; set; } + /// Color of the font. [Parameter] public PdfColor? FontColor { get; set; } + /// Font size. [Parameter] public int? FontSize { get; set; } + /// Text alignment of the list. [Parameter] public TextAlignment? TextAlignment { get; set; } + /// Top margin. [Parameter] public double? MarginTop { get; set; } + /// Bottom margin. [Parameter] public double? MarginBottom { get; set; } + /// Left margin. [Parameter] public double? MarginLeft { get; set; } + /// Right margin. [Parameter] public double? MarginRight { get; set; } protected override void ProcessRecord() { diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFListItem.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFListItem.cs index f4ae5a3..317fe92 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFListItem.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFListItem.cs @@ -2,8 +2,33 @@ namespace PSWritePDF.Cmdlets; +/// Creates a list item string. +/// Outputs the provided text for use with New-PDFList. +/// +/// +/// Note +/// This cmdlet simply echoes the text as a list item. +/// +/// +/// +/// Create an item. +/// +/// PS> New-PDFListItem -Text 'First' +/// +/// Returns the string 'First'. +/// +/// +/// Use with a list. +/// +/// PS> New-PDFList -ListItems { New-PDFListItem -Text 'A' } +/// +/// Creates a list containing one item. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFListItem")] public class CmdletNewPDFListItem : PSCmdlet { + /// Text for the list item. [Parameter(Mandatory = true)] public string Text { get; set; } = string.Empty; diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFOptions.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFOptions.cs index e4133c2..e164fb8 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFOptions.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFOptions.cs @@ -4,13 +4,42 @@ namespace PSWritePDF.Cmdlets; +/// Creates or applies PDF margin options. +/// Modifies margins of the current document or returns an options object. +/// +/// +/// Note +/// No changes are made if no document is open. +/// +/// +/// +/// Set margins on active document. +/// +/// PS> New-PDFOptions -MarginTop 20 -MarginBottom 20 +/// +/// Applies new margins to the current document. +/// +/// +/// Return options object. +/// +/// PS> $opts = New-PDFOptions -MarginLeft 10 -MarginRight 10 -PassThru +/// +/// Creates a PdfDocumentOptions instance for later use. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFOptions")] public class CmdletNewPDFOptions : PSCmdlet { + /// Left margin in points. [Parameter] public double? MarginLeft { get; set; } + /// Right margin in points. [Parameter] public double? MarginRight { get; set; } + /// Top margin in points. [Parameter] public double? MarginTop { get; set; } + /// Bottom margin in points. [Parameter] public double? MarginBottom { get; set; } + /// Return the updated document or options. [Parameter] public SwitchParameter PassThru { get; set; } protected override void ProcessRecord() diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFPage.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFPage.cs index f809b80..ebcfd5f 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFPage.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFPage.cs @@ -5,17 +5,49 @@ namespace PSWritePDF.Cmdlets; +/// Adds a new page to the active PDF document. +/// Creates a page with optional margins and size, executing a script block for content if supplied. +/// +/// +/// Note +/// This cmdlet requires a document created by New-PDF. +/// +/// +/// +/// Add a blank page. +/// +/// PS> New-PDFPage +/// +/// Creates a default page. +/// +/// +/// Add content to a page. +/// +/// PS> New-PDFPage -PageContent { New-PDFText -Text 'Hello' } +/// +/// Inserts a page and writes text on it. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFPage")] public class CmdletNewPDFPage : PSCmdlet { + /// Script block defining page content. [Parameter(Position = 0)] public ScriptBlock? PageContent { get; set; } + /// Left margin in points. [Parameter] public double? MarginLeft { get; set; } + /// Right margin in points. [Parameter] public double? MarginRight { get; set; } + /// Top margin in points. [Parameter] public double? MarginTop { get; set; } + /// Bottom margin in points. [Parameter] public double? MarginBottom { get; set; } + /// Page size to apply. [Parameter] public PdfPageSize? PageSize { get; set; } + /// Rotate the page orientation. [Parameter] public SwitchParameter Rotate { get; set; } + /// Emit the Document object. [Parameter] public SwitchParameter PassThru { get; set; } protected override void ProcessRecord() { diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFTable.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFTable.cs index 4377382..7fecd3b 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFTable.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFTable.cs @@ -7,8 +7,33 @@ namespace PSWritePDF.Cmdlets; +/// Creates a table in the current PDF document. +/// Builds an iText Table from PowerShell objects and adds it to the active document. +/// +/// +/// Note +/// The table is added only when a document is stored in the session. +/// +/// +/// +/// Add a table from objects. +/// +/// PS> New-PDFTable -DataTable $objects +/// +/// Creates a table using property names as columns. +/// +/// +/// Create an empty table. +/// +/// PS> New-PDFTable +/// +/// Outputs a table object without adding rows. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFTable")] public class CmdletNewPDFTable : PSCmdlet { + /// Objects representing table rows. [Parameter] public PSObject[] DataTable { get; set; } = Array.Empty(); diff --git a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFText.cs b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFText.cs index 97e8604..c228fc9 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletNewPDFText.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletNewPDFText.cs @@ -7,19 +7,53 @@ namespace PSWritePDF.Cmdlets; +/// Adds a paragraph of text to the current PDF document. +/// Creates an iText Paragraph with formatting options and writes it to the active document. +/// +/// +/// Note +/// The paragraph is added only if a document is stored in the Document session variable. +/// +/// +/// +/// Add basic text. +/// +/// PS> New-PDFText -Text 'Hello World' +/// +/// Inserts a paragraph with the specified text. +/// +/// +/// Use custom font and size. +/// +/// PS> New-PDFText -Text 'Hello' -FontSize 18 -FontBold $true +/// +/// Creates emphasized text in the document. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.New, "PDFText")] public class CmdletNewPDFText : PSCmdlet { + /// Text lines to add. [Parameter(Mandatory = true)] public string[] Text { get; set; } = Array.Empty(); + /// Fonts for each line. [Parameter] public PdfFontName[]? Font { get; set; } + /// Font colors. [Parameter] public PdfColor[]? FontColor { get; set; } + /// Apply bold style per line. [Parameter] public bool?[]? FontBold { get; set; } + /// Font size in points. [Parameter] public int? FontSize { get; set; } + /// Alignment of the text. [Parameter] public TextAlignment? TextAlignment { get; set; } + /// Top margin in points. [Parameter] public double? MarginTop { get; set; } = 2; + /// Bottom margin in points. [Parameter] public double? MarginBottom { get; set; } = 2; + /// Left margin in points. [Parameter] public double? MarginLeft { get; set; } + /// Right margin in points. [Parameter] public double? MarginRight { get; set; } protected override void ProcessRecord() { diff --git a/Sources/PSWritePDF/Cmdlets/CmdletRegisterPDFFont.cs b/Sources/PSWritePDF/Cmdlets/CmdletRegisterPDFFont.cs index 2d4bf9b..f9defb4 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletRegisterPDFFont.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletRegisterPDFFont.cs @@ -7,24 +7,54 @@ namespace PSWritePDF.Cmdlets; +/// Registers a font for use in PDF generation. +/// Adds a font to the session cache and optionally sets it as default. +/// +/// +/// Note +/// Font files must exist on disk; missing paths trigger warnings. +/// +/// +/// +/// Register a font. +/// +/// PS> Register-PDFFont -FontName MyFont -FontPath 'c:\fonts\my.ttf' +/// +/// Makes the font available for later use. +/// +/// +/// Register and set as default. +/// +/// PS> Register-PDFFont -FontName MyFont -FontPath 'c:\fonts\my.ttf' -Default +/// +/// Subsequent text uses this font automatically. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsLifecycle.Register, "PDFFont")] public class CmdletRegisterPDFFont : PSCmdlet { + /// Name used to reference the font. [Parameter(Mandatory = true)] public string FontName { get; set; } = string.Empty; + /// Path to the font file. [Parameter(Mandatory = true)] public string FontPath { get; set; } = string.Empty; + /// Optional encoding for the font. [Parameter] public PdfFontEncoding Encoding { get; set; } = PdfFontEncoding.None; + /// Embedding strategy for the font. [Parameter] public PdfFontFactory.EmbeddingStrategy EmbeddingStrategy { get; set; } = PdfFontFactory.EmbeddingStrategy.PREFER_EMBEDDED; + /// Cache the font for reuse. [Parameter] public SwitchParameter Cached { get; set; } + /// Set the font as default. [Parameter] public SwitchParameter Default { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletSetPDFForm.cs b/Sources/PSWritePDF/Cmdlets/CmdletSetPDFForm.cs index 812ceef..09a7d4a 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletSetPDFForm.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletSetPDFForm.cs @@ -8,27 +8,57 @@ namespace PSWritePDF.Cmdlets; +/// Sets values of PDF form fields. +/// Copies an existing PDF, populates AcroForm fields, and optionally flattens them. +/// +/// +/// Note +/// Source documents are read entirely and may require removal of protection for editing. +/// +/// +/// +/// Populate form fields. +/// +/// PS> Set-PDFForm -SourceFilePath 'in.pdf' -DestinationFilePath 'out.pdf' -FieldNameAndValueHashTable $hash +/// +/// Copies the source PDF and sets fields as specified. +/// +/// +/// Flatten fields. +/// +/// PS> Set-PDFForm -SourceFilePath 'in.pdf' -DestinationFilePath 'out.pdf' -Flatten +/// +/// Writes a new PDF with non-editable fields. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Set, "PDFForm")] public class CmdletSetPDFForm : PSCmdlet { + /// Path to the source PDF with form fields. [Parameter(Mandatory = true)] [ValidateNotNullOrEmpty] public string SourceFilePath { get; set; } + /// Destination path for the output PDF. [Parameter(Mandatory = true)] [ValidateNotNullOrEmpty] public string DestinationFilePath { get; set; } + /// Hashtable of field names and values. [Parameter(ValueFromPipeline = true)] public IDictionary FieldNameAndValueHashTable { get; set; } + /// Flatten the fields to make them read-only. [Parameter] [Alias("FlattenFields")] public SwitchParameter Flatten { get; set; } + /// Ignore document protection when reading. [Parameter] public SwitchParameter IgnoreProtection { get; set; } + /// Return the destination file path. [Parameter] public SwitchParameter PassThru { get; set; } diff --git a/Sources/PSWritePDF/Cmdlets/CmdletSplitPDF.cs b/Sources/PSWritePDF/Cmdlets/CmdletSplitPDF.cs index 00b919f..c35c9dd 100644 --- a/Sources/PSWritePDF/Cmdlets/CmdletSplitPDF.cs +++ b/Sources/PSWritePDF/Cmdlets/CmdletSplitPDF.cs @@ -6,6 +6,30 @@ namespace PSWritePDF.Cmdlets; +/// Splits a PDF into multiple documents. +/// Supports splitting by page count, page ranges, or bookmarks. +/// +/// +/// Note +/// Existing files in the destination may be overwritten when Force is specified. +/// +/// +/// +/// Split by page count. +/// +/// PS> Split-PDF -FilePath 'in.pdf' -OutputFolder './out' -SplitCount 2 +/// +/// Creates output files containing two pages each. +/// +/// +/// Split by page ranges. +/// +/// PS> Split-PDF -FilePath 'in.pdf' -OutputFolder './out' -PageRange '1-3','4-6' +/// +/// Produces files for the specified ranges. +/// +/// MS Learn +/// Project documentation [Cmdlet(VerbsCommon.Split, "PDF", SupportsShouldProcess = true)] public class CmdletSplitPDF : PSCmdlet { @@ -13,35 +37,43 @@ public class CmdletSplitPDF : PSCmdlet private const string PageRangeParameterSet = "PageRange"; private const string BookmarkParameterSet = "Bookmark"; + /// Path to the source PDF. [Parameter(Mandatory = true, ParameterSetName = SplitCountParameterSet)] [Parameter(Mandatory = true, ParameterSetName = PageRangeParameterSet)] [Parameter(Mandatory = true, ParameterSetName = BookmarkParameterSet)] public string FilePath { get; set; } + /// Destination folder for split files. [Parameter(Mandatory = true, ParameterSetName = SplitCountParameterSet)] [Parameter(Mandatory = true, ParameterSetName = PageRangeParameterSet)] [Parameter(Mandatory = true, ParameterSetName = BookmarkParameterSet)] public string OutputFolder { get; set; } + /// Base name for output files. [Parameter(ParameterSetName = SplitCountParameterSet)] [Parameter(ParameterSetName = PageRangeParameterSet)] [Parameter(ParameterSetName = BookmarkParameterSet)] public string OutputName { get; set; } = "OutputDocument"; + /// Number of pages per output file. [Parameter(ParameterSetName = SplitCountParameterSet)] public int SplitCount { get; set; } = 1; + /// Page ranges to extract. [Parameter(ParameterSetName = PageRangeParameterSet)] public string[] PageRange { get; set; } + /// Bookmark titles that define splits. [Parameter(ParameterSetName = BookmarkParameterSet)] public string[] Bookmark { get; set; } + /// Ignore document protection. [Parameter(ParameterSetName = SplitCountParameterSet)] [Parameter(ParameterSetName = PageRangeParameterSet)] [Parameter(ParameterSetName = BookmarkParameterSet)] public SwitchParameter IgnoreProtection { get; set; } + /// Overwrite existing files without prompting. [Parameter(ParameterSetName = SplitCountParameterSet)] [Parameter(ParameterSetName = PageRangeParameterSet)] [Parameter(ParameterSetName = BookmarkParameterSet)] diff --git a/Sources/PSWritePDF/PSWritePDF.csproj b/Sources/PSWritePDF/PSWritePDF.csproj index d33a258..3db5453 100644 --- a/Sources/PSWritePDF/PSWritePDF.csproj +++ b/Sources/PSWritePDF/PSWritePDF.csproj @@ -44,6 +44,7 @@ true + -strict diff --git a/Sources/PSWritePDF/Support/PdfActionName.cs b/Sources/PSWritePDF/Support/PdfActionName.cs index ba9ca6b..939ae2d 100644 --- a/Sources/PSWritePDF/Support/PdfActionName.cs +++ b/Sources/PSWritePDF/Support/PdfActionName.cs @@ -1,5 +1,6 @@ namespace PSWritePDF; +/// Specifies available PDF form action flags. public enum PdfActionName { RESET_EXCLUDE, diff --git a/Sources/PSWritePDF/Support/PdfDetails.cs b/Sources/PSWritePDF/Support/PdfDetails.cs index 6531207..42db455 100644 --- a/Sources/PSWritePDF/Support/PdfDetails.cs +++ b/Sources/PSWritePDF/Support/PdfDetails.cs @@ -1,5 +1,6 @@ namespace PSWritePDF; +/// Enumerates known PDF page size names. public enum PdfPageSizeName { A0, @@ -31,31 +32,53 @@ public enum PdfPageSizeName Unknown } +/// Represents detailed information about a PDF page. public class PdfPageDetails { + /// Height of the page in points. public int Height { get; set; } + /// Width of the page in points. public int Width { get; set; } + /// Rotation angle. public int Rotation { get; set; } + /// Named page size. public PdfPageSizeName Size { get; set; } = PdfPageSizeName.Unknown; + /// Indicates if the page is rotated. public bool? Rotated { get; set; } } +/// Aggregated details for a PDF document. public class PdfDocumentDetails { + /// Document author. public string? Author { get; set; } + /// Document creator. public string? Creator { get; set; } + /// Internal hash code. public int HashCode { get; set; } + /// Document keywords. public string? Keywords { get; set; } + /// Document producer. public string? Producer { get; set; } + /// Document subject. public string? Subject { get; set; } + /// Document title. public string? Title { get; set; } + /// Trapping information. public string? Trapped { get; set; } + /// PDF version used. public iText.Kernel.Pdf.PdfVersion Version { get; set; } + /// Total number of pages. public int PagesNumber { get; set; } + /// Left margin. public float MarginLeft { get; set; } + /// Right margin. public float MarginRight { get; set; } + /// Bottom margin. public float MarginBottom { get; set; } + /// Top margin. public float MarginTop { get; set; } + /// Information about individual pages. public System.Collections.Generic.Dictionary Pages { get; } = new(); } diff --git a/Sources/PSWritePDF/Support/PdfDocumentOptions.cs b/Sources/PSWritePDF/Support/PdfDocumentOptions.cs index d1b4bf9..f9d936f 100644 --- a/Sources/PSWritePDF/Support/PdfDocumentOptions.cs +++ b/Sources/PSWritePDF/Support/PdfDocumentOptions.cs @@ -2,10 +2,15 @@ namespace PSWritePDF; +/// Defines margin settings for a PDF document. public class PdfDocumentOptions { + /// Left margin in points. public float? MarginLeft { get; set; } + /// Right margin in points. public float? MarginRight { get; set; } + /// Top margin in points. public float? MarginTop { get; set; } + /// Bottom margin in points. public float? MarginBottom { get; set; } } diff --git a/Sources/PSWritePDF/Support/PdfExtractionStrategyName.cs b/Sources/PSWritePDF/Support/PdfExtractionStrategyName.cs index d80ff04..7c9a003 100644 --- a/Sources/PSWritePDF/Support/PdfExtractionStrategyName.cs +++ b/Sources/PSWritePDF/Support/PdfExtractionStrategyName.cs @@ -2,6 +2,7 @@ namespace PSWritePDF; +/// Defines text extraction strategies for PDFs. public enum PdfExtractionStrategyName { Simple, diff --git a/Sources/PSWritePDF/Support/PdfFontEncoding.cs b/Sources/PSWritePDF/Support/PdfFontEncoding.cs index d35fd50..8d85ceb 100644 --- a/Sources/PSWritePDF/Support/PdfFontEncoding.cs +++ b/Sources/PSWritePDF/Support/PdfFontEncoding.cs @@ -1,5 +1,6 @@ namespace PSWritePDF; +/// Represents encoding options for PDF fonts. public enum PdfFontEncoding { None, diff --git a/Sources/PSWritePDF/Support/PdfFormFieldInfo.cs b/Sources/PSWritePDF/Support/PdfFormFieldInfo.cs index c125956..c96b77f 100644 --- a/Sources/PSWritePDF/Support/PdfFormFieldInfo.cs +++ b/Sources/PSWritePDF/Support/PdfFormFieldInfo.cs @@ -1,7 +1,11 @@ namespace PSWritePDF; +/// Represents a PDF form field and its name. public class PdfFormFieldInfo { + /// Name of the field. public string Name { get; set; } = string.Empty; + + /// The underlying form field object. public iText.Forms.Fields.PdfFormField Field { get; set; } = null!; } diff --git a/Sources/PSWritePDF/Support/PdfVersionName.cs b/Sources/PSWritePDF/Support/PdfVersionName.cs index 59d680d..165aac6 100644 --- a/Sources/PSWritePDF/Support/PdfVersionName.cs +++ b/Sources/PSWritePDF/Support/PdfVersionName.cs @@ -1,5 +1,6 @@ namespace PSWritePDF; +/// Lists supported PDF specification versions. public enum PdfVersionName { PDF_1_0,