Updating branch with latest updates from dev

Signed-off-by: Chris Arceneaux <[email protected]>

ChangeLog.md

@@ -2,6 +2,14 @@
 
 ## Versions ##
 
+### Unreleased ###
+
+* Adds bulleted/numbered list support - Example39.ps1 to Example44.ps1 (#105)
+* Adds custom list number formats (Word and Text plugins only)
+  * Adds `NumberStyle` keyword
+* Fixes bug in Text table output breaking Word and Html output (#126)
+* Fixes bug in call stack enumeration with nested functions containing `Section -Orientation` definitions (#121)
+
 ### 0.10.0 ###
 
 * __BREAKING CHANGE__ - XML output to be deprecated in a future release (#102)

Examples/Example17.ps1

@@ -16,6 +16,8 @@ $example17 = Document -Name 'PScribo Example 17' {
         NOTE: You must ensure that the hashtable keys are the same on all hashtables
               in the collection/array as only the first object is enumerated.
 
+        NOTE: If using 'ColumnWidths' parameter in combination with the 'List' and 'Key' parameters, make sure the ColumnWidth accounts for the additional column generated by the Key. For example, looking at the hashtable below, 4 ColumnWidths values would be required.
+
         The following example creates an table with a three rows from an array of
         ordered hashtables.
     #>

Examples/Example39.ps1

@@ -0,0 +1,69 @@
+[CmdletBinding()]
+param (
+    [System.String[]] $Format = 'Html',
+    [System.String] $Path = '~\Desktop',
+    [System.Management.Automation.SwitchParameter] $PassThru
+)
+
+Import-Module PScribo -Force -Verbose:$false
+
+# 'List' single-level bullet lists
+$example39 = Document -Name 'PScribo Example 39' {
+
+    <#
+        A bulleted list is defined by the 'List' keyword and can contain one or more items.
+
+        A simple single-level list can be defined with the '-Item' parameter and passing an
+        array of strings ([string[]]).
+    #>
+    List -Item 'Apples','Oranges','Bananas'
+
+    <#
+        A list can also be created using a script block and nesting one or 'Item' keywords
+        within it.
+    #>
+    List {
+        Item 'Apples'
+        Item 'Bananas'
+        Item 'Oranges'
+    }
+
+    <#
+        Bullet styles can be applied to a list, e.g. 'Dash', 'Circle', 'Disc' and 'Square'. If
+        not specified, the bullet list defaults to the 'Disc' style.
+    #>
+    List -BulletStyle Square {
+        Item 'Apples'
+        Item 'Bananas'
+        Item 'Oranges'
+    }
+
+    <#
+        Formatting styles can be applied to all items in a list.
+    #>
+    List -Style Caption {
+        Item 'Apples'
+        Item 'Bananas'
+        Item 'Oranges'
+    }
+
+    <#
+        Styles can be applied to indiviual items in a list.
+    #>
+    List {
+        Item 'Apples'
+        Item 'Bananas' -Style Caption
+        Item 'Oranges'
+    }
+
+    <#
+        Inline styles can also be applied to indiviual items in a list.
+    #>
+    List {
+        Item 'Apples' -Bold
+        Item 'Bananas' -Italic
+        Item 'Oranges' -Color Firebrick
+    }
+
+}
+$example39 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru

Examples/Example40.ps1

@@ -0,0 +1,36 @@
+[CmdletBinding()]
+param (
+    [System.String[]] $Format = 'Html',
+    [System.String] $Path = '~\Desktop',
+    [System.Management.Automation.SwitchParameter] $PassThru
+)
+
+Import-Module PScribo -Force -Verbose:$false
+
+$example40 = Document -Name 'PScribo Example 40' {
+
+    <#
+        Numbered lists are supported and can be specified with the '-Numbered' parameter.
+    #>
+    List -Item 'Apples','Oranges','Bananas' -Numbered
+
+    <#
+        Multiple number styles are available: 'Number', 'Letter' and 'Roman'. If not specified,
+        a numbered list will default to the 'Number' style. You can specify the required number
+        format with the '-NumberStyle' parameter.
+    #>
+    List -Item 'Apples','Oranges','Bananas' -Numbered -NumberStyle Letter
+
+    <#
+        Multiple number styles are available: 'Number', 'Letter' and 'Roman'. If not specified,
+        a numbered list will default to the 'Number' style. You can specify the required number
+        format with the '-NumberStyle' parameter.
+    #>
+    List -Numbered -NumberStyle Roman {
+        Item 'Apples'
+        Item 'Bananas'
+        Item 'Oranges'
+    }
+
+}
+$example40 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru

Examples/Example41.ps1

@@ -0,0 +1,60 @@
+[CmdletBinding()]
+param (
+    [System.String[]] $Format = 'Html',
+    [System.String] $Path = '~\Desktop',
+    [System.Management.Automation.SwitchParameter] $PassThru
+)
+
+Import-Module PScribo -Force -Verbose:$false
+
+$example41 = Document -Name 'PScribo Example 41' {
+
+    <#
+        Multi-level bullet lists can be created by nesting one or more 'List' keywords.
+
+        NOTE: There must be an 'Item' keyword defined before a nested 'List' can be used.
+    #>
+    List {
+        Item 'Apples'
+        List {
+            Item 'Jazz'
+            Item 'Granny smith'
+            Item 'Pink lady'
+        }
+        Item 'Bananas'
+        Item 'Oranges'
+        List {
+            Item 'Jaffa'
+            Item 'Tangerine'
+            Item 'Clementine'
+        }
+    }
+
+    <#
+        Each 'List' can have its own bullet style defined.
+
+        NOTE: Word does not support a mixture of bullet/number formats at the same level within a
+              list. Therefore, only the first list type will be rendered at each level - in this
+              example the 'Disc' style will be used.
+
+        NOTE: Html output does not support the 'Dash' bullet style. Dashes will be rendered using
+              the the web broswer's defaults.
+    #>
+    List -BulletStyle Square {
+        Item 'Apples'
+        List -BulletStyle Disc {
+            Item 'Jazz'
+            Item 'Granny smith'
+            Item 'Pink lady'
+        }
+        Item 'Bananas'
+        Item 'Oranges'
+        List -BulletStyle Dash {
+            Item 'Jaffa'
+            Item 'Tangerine'
+            Item 'Clementine'
+        }
+    }
+
+}
+$example41 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru

Examples/Example42.ps1

@@ -0,0 +1,59 @@
+[CmdletBinding()]
+param (
+    [System.String[]] $Format = 'Html',
+    [System.String] $Path = '~\Desktop',
+    [System.Management.Automation.SwitchParameter] $PassThru
+)
+
+Import-Module PScribo -Force -Verbose:$false
+
+$example42 = Document -Name 'PScribo Example 42' {
+
+    <#
+        Multi-level numbered lists can be created by nesting one or more 'List' keywords in
+        combination with the '-Numbered' parameter.
+
+        NOTE: A 'List' defaults to a bulleted list by default, so the '-Numbered' switch needs
+              to be specified at each level - where required.
+    #>
+    List -Numbered {
+        Item 'Apples'
+        List -Numbered {
+            Item 'Jazz'
+            Item 'Granny smith'
+            Item 'Pink lady'
+        }
+        Item 'Bananas'
+        Item 'Oranges'
+        List -Numbered {
+            Item 'Jaffa'
+            Item 'Tangerine'
+            Item 'Clementine'
+        }
+    }
+
+    <#
+        Like bullet lists, each 'List' can have its own number style defined.
+
+        NOTE: Word does not support a mixture of bullet/number formats at the same level within a
+              list. Therefore, only the first list type will be rendered at each level - in this
+              example the 'Letter' style will be used for the second nested numbered list.
+    #>
+    List -Numbered {
+        Item 'Apples'
+        List -Numbered -NumberStyle Letter {
+            Item 'Jazz'
+            Item 'Granny smith'
+            Item 'Pink lady'
+        }
+        Item 'Bananas'
+        Item 'Oranges'
+        List -Numbered -NumberStyle Roman {
+            Item 'Jaffa'
+            Item 'Tangerine'
+            Item 'Clementine'
+        }
+    }
+
+}
+$example42 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru

Examples/Example43.ps1

@@ -0,0 +1,83 @@
+[CmdletBinding()]
+param (
+    [System.String[]] $Format = 'Word',
+    [System.String] $Path = '~\Desktop',
+    [System.Management.Automation.SwitchParameter] $PassThru
+)
+
+Import-Module PScribo -Force -Verbose:$false
+
+$example43 = Document -Name 'PScribo Example 43' {
+
+    <#
+        PScribo provides 3 built-in number styles that replicate the standard Html options and
+        the built-in Microsoft Word defaults; 'Number', 'Letter' and 'Roman'. The default number
+        styles display the number in lowercase, right-aligned and terminated with a period '.'.
+
+        It is possible to define your own number styles or override the built-in styles. This
+        provides options to change the casing and/or alignment of the list numbers.
+
+        NOTE: Html numbered lists only support the default '.' number style terminator/suffix. The
+              use of custom number style terminators/suffixes is not supported.
+
+        NOTE: Html numbered/unordered lists do not support alignment.
+
+        For example, to override the built-in number styles ensuring that they are rendered in
+        uppercase and terminated with a parenthesis:
+    #>
+    NumberStyle -Id 'Number' -Format Number -Uppercase -Suffix ')'
+    NumberStyle -Id 'Letter' -Format Letter -Uppercase -Suffix ')'
+    NumberStyle -Id 'Roman' -Format Roman -Uppercase -Suffix ')'
+
+    <#
+        To align the number to the left margin, override or define your own number style with the
+        '-Align' parameter.
+
+        NOTE: The default number style has been changed so we define a 'RightRoman' to mimic the
+              built-in/default settings (without redefining 'Roman' again!).
+    #>
+    NumberStyle -Id 'LeftRoman' -Format Roman -Align Left
+    NumberStyle -Id 'RightRoman' -Format Roman -Align Right
+
+    <#
+        Output right aligned (the default) lists for comparison
+    #>
+    List -Numbered -NumberStyle RightRoman {
+        Item 'Apples'
+        List -Numbered -NumberStyle RightRoman {
+            Item 'Jazz'
+            Item 'Granny smith'
+            Item 'Pink lady'
+        }
+        Item 'Bananas'
+        Item 'Oranges'
+        List -Numbered -NumberStyle RightRoman {
+            Item 'Jaffa'
+            Item 'Tangerine'
+            Item 'Clementine'
+        }
+    }
+
+    <#
+        Output left aligned lists for comparison
+
+        NOTE: Html numbered lists only support the default '.' number style terminator/suffix. The
+              use of custom number style terminators/suffixes is not supported.
+    #>
+    List -Numbered -NumberStyle LeftRoman {
+        Item 'Apples'
+        List -Numbered -NumberStyle LeftRoman {
+            Item 'Jazz'
+            Item 'Granny smith'
+            Item 'Pink lady'
+        }
+        Item 'Bananas'
+        Item 'Oranges'
+        List -Numbered -NumberStyle LeftRoman {
+            Item 'Jaffa'
+            Item 'Tangerine'
+            Item 'Clementine'
+        }
+    }
+}
+$example43 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru

Examples/Example44.ps1

@@ -0,0 +1,34 @@
+[CmdletBinding()]
+param (
+    [System.String[]] $Format = 'Word',
+    [System.String] $Path = '~\Desktop',
+    [System.Management.Automation.SwitchParameter] $PassThru
+)
+
+Import-Module PScribo -Force -Verbose:$false
+
+$example44 = Document -Name 'PScribo Example 44' {
+
+    <#
+        Custom numbered lists are registered with the 'NumberStyle' keyword, but only the Word and
+        Text plugins are supported. All other plugins will render the number as a decimal (using the
+        'Number' format).
+
+        Custom number lists can contain any wording and punctuation you require.
+
+        NOTE: The '-Uppercase' and '-Suffix' parameters are ignored so you need to include any suffix
+              in the number format definition.
+
+        The '%' token is used to denote where the number will be placed. To include leading zeroes,
+        use multiple '%' tokens, e.g. 'ab%%' for ab01, ab02 and 'XYZ-%%%' for XYZ-001, XYZ-002, etc..
+    #>
+    NumberStyle -Id 'CustomNumberStyle' -Custom 'xYz-%%%.' -Indent 1500 -Hanging 200 -Align Left
+
+    <#
+        Output list using the 'Custom' number style
+    #>
+
+    List -Numbered -NumberStyle CustomNumberStyle -Item 'Apples','Bananas','Oranges'
+
+}
+$example44 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru

PScribo.psd1

@@ -15,7 +15,10 @@
                             'Footer',
                             'Header',
                             'Image',
+                            'Item',
                             'LineBreak',
+                            'List',
+                            'NumberStyle',
                             'PageBreak',
                             'Paragraph',
                             'Section',
@@ -25,7 +28,8 @@
                             'TableStyle',
                             'Text',
                             'TOC',
-                            'Write-PScriboMessage'
+                            'Write-PScriboMessage',
+                            'Get-WordListLevel'
                         )
     AliasesToExport   = @(
                             'GlobalOption'