Merge pull request #43 from PowerShellGuides/PowerShell-Guide-Init

Initial Version of PowerShell Guide

Formatting/PowerShell.Guide.Topic.File.format.ps1

@@ -0,0 +1,57 @@
+Write-FormatView -TypeName 'PowerShell Guide Topic File','PowerShell.Guide.Topic.File' -Property "TopicName"
+
+Write-FormatView -TypeName 'PowerShell Guide Topic File','PowerShell.Guide.Topic.File' -Action {
+    Write-FormatViewExpression -ScriptBlock {
+        @("---"
+        Format-Yaml -InputObject $_.Metadata
+        if ($_.FrontMatter) {
+            Format-Yaml -InputObject $_.FrontMatter
+        }
+        "---") -join [Environment]::Newline
+    }
+
+    Write-FormatViewExpression -Newline
+    Write-FormatViewExpression -Newline
+
+    Write-FormatViewExpression -ScriptBlock {        
+        $guideTopic = $_
+
+        $codeFenceRegex = [Regex]::new(@'
+(?>
+    (?<FenceChar>[`\~]){3}    # Code fences start with tildas or backticks, repeated at least 3 times
+(?<Language>                  # Match a specific language
+PowerShell
+)
+[\s-[\r\n]]{0,}               # Match but do not capture initial whitespace.
+(?<Code>                      # Capture the <Code> block
+    (?:.|\s){0,}?             # This is anything until
+    (?=\z|\k<FenceChar>{3})   # the end of the string or the same matching fence chars
+)
+(?>\z|\k<FenceChar>{3})
+)
+'@, 'IgnoreCase,IgnorePatternWhitespace,Singleline')
+
+        $topicContent = $guideTopic.ToMarkdown()
+        $hostSupportedHTML = $host.UI.SupportsHTML
+        $host.UI | Add-Member NoteProperty SupportsHTML $true -Force
+        $codeFenceRegex.Replace($topicContent, {
+            param($match)
+
+            $colorizedParts = $guideTopic.ColorizeCode($match.Groups["Code"].Value)
+            return ("<pre>" + 
+            $(@(foreach ($colorizedPart in $colorizedParts) {
+                if ($colorizedPart.InputObject -eq [Environment]::NewLine) {
+                    "<br/>"
+                }
+                elseif ($colorizedPart.InputObject -match '^\s+$') {
+                    $colorizedPart.InputObject -replace '\s', "&nbsp;"
+                }
+                else {
+                    Format-RichText @colorizedPart
+                }
+            }) -join '') + 
+            "</pre>")
+        })
+        $host.UI | Add-Member NoteProperty SupportsHTML $hostSupportedHTML -Force                
+    }
+} -Name 'Markdown'

Get-PowerShellGuide.ps.ps1

@@ -0,0 +1,42 @@
+function Get-PowerShellGuide
+{
+    [CmdletBinding(DefaultParameterSetName='NoTopic')]
+    [Alias('Get-PSGuide')]
+    param(
+    [Parameter(Mandatory,ParameterSetName='Topic',ValueFromPipelineByPropertyName)]
+    [Alias('TopicName')]
+    [string]
+    $Topic
+    )
+
+    process {
+        if ($PSCmdlet.ParameterSetName -eq 'NoTopic') {
+            if (-not $script:CachedPowerShellGuide) {
+                $guideTopics = 
+                    Get-ChildItem -Path $PSScriptRoot -Filter Guide |
+                        Get-ChildItem -Recurse |
+                        Where-Object Extension -in '.md' |
+                        Where-Object FullName -notlike '*_site*'
+
+                $guideTopics = @(all in $guideTopics are 'PowerShell Guide Topic File')
+
+                $myModuleVersion = $MyInvocation.MyCommand.ScriptBlock.Module.Version
+
+                $script:CachedPowerShellGuide = [PSCustomObject]@{
+                    PSTypeName = 'PowerShell.Guide'
+                    Version    = $myModuleVersion
+                    AllTopics  = $guideTopics
+                    AllDemos   = $guideDemos
+                }
+            }
+
+            $script:CachedPowerShellGuide
+        }
+
+        if ($PSCmdlet.ParameterSetName -eq 'Topic') {
+            $psGuide = Get-PowerShellGuide
+            $psGuide.AllTopics | 
+                Where-Object Aliases -like $Topic
+        }
+    }
+}

Get-PowerShellGuide.ps1

@@ -0,0 +1,62 @@
+function Get-PowerShellGuide {
+    [CmdletBinding(DefaultParameterSetName='NoTopic')]
+    [Alias('Get-PSGuide')]
+    param(
+    [Parameter(Mandatory,ParameterSetName='Topic',ValueFromPipelineByPropertyName)]
+    [Alias('TopicName')]
+    [string]
+    $Topic
+    )
+    process {
+        if ($PSCmdlet.ParameterSetName -eq 'NoTopic') {
+            if (-not $script:CachedPowerShellGuide) {
+                $guideTopics = 
+                    Get-ChildItem -Path $PSScriptRoot -Filter Guide |
+                        Get-ChildItem -Recurse |
+                        Where-Object Extension -in '.md' |
+                        Where-Object FullName -notlike '*_site*'
+
+                $guideTopics = @($(
+                                 # Collect all items into an input collection
+                                 $inputCollection =$($guideTopics)
+                                 # 'unroll' the collection by iterating over it once.
+                                 $filteredCollection = $inputCollection =
+                                     @(foreach ($in in $inputCollection) {
+                                         $in
+                                     })
+                                 # Walk over each item in the filtered collection
+                                 foreach ($item in $filteredCollection) {
+                                     # we set $this, $psItem, and $_ for ease-of-use.
+                                     $this = $_ = $psItem = $item
+                                 if ($item.value -and $item.value.pstypenames.insert) {
+                                     if ($item.value.pstypenames -notcontains 'PowerShell Guide Topic File') {
+                                         $item.value.pstypenames.insert(0, 'PowerShell Guide Topic File')
+                                     }
+                                 }
+                                 elseif ($item.pstypenames.insert -and $item.pstypenames -notcontains 'PowerShell Guide Topic File') {
+                                     $item.pstypenames.insert(0, 'PowerShell Guide Topic File')
+                                 }
+                                 $item
+
+                                 }   
+                                 ))
+                $myModuleVersion = $MyInvocation.MyCommand.ScriptBlock.Module.Version
+
+                $script:CachedPowerShellGuide = [PSCustomObject]@{
+                    PSTypeName = 'PowerShell.Guide'
+                    Version    = $myModuleVersion
+                    AllTopics  = $guideTopics
+                    AllDemos   = $guideDemos
+                }
+            }
+
+            $script:CachedPowerShellGuide
+        }
+        if ($PSCmdlet.ParameterSetName -eq 'Topic') {
+            $psGuide = Get-PowerShellGuide
+            $psGuide.AllTopics | 
+                Where-Object Aliases -like $Topic
+        }
+    }
+}
+

GitHub/Jobs/BuildPowerShellGuide.psd1

@@ -0,0 +1,18 @@
+@{
+    "runs-on" = "ubuntu-latest"    
+    if = '${{ success() }}'
+    steps = @(
+        @{
+            name = 'Check out repository'
+            uses = 'actions/checkout@v2'
+        }, 
+        @{    
+            name = 'Use PSSVG Action'
+            uses = 'StartAutomating/PSSVG@main'
+            id = 'PSSVG'
+        },
+        'RunEZOut',
+        'RunPipeScript',        
+        'RunHelpOut'
+    )
+}

Guide/Languages/High-Level-Languages.md

@@ -0,0 +1,11 @@
+High level languages are programming languages that at least try to be understandable.
+
+Unfortunately, there's quite a bit of variation on how much they succeed.
+
+The most common example of a high level language is [BASIC](https://en.wikipedia.org/wiki/BASIC).
+
+Some say the lack of features in this language is the reason that basic became an insult.
+
+We say that BASIC is a basic attempt by programmers of the 60s to be understandable.
+
+We also say that PowerShell is a much higher level language than you're every likely to see, due to it's verb-noun convention.

Guide/Languages/High-Level-Languages.md.psd1

@@ -0,0 +1,3 @@
+@{
+    Alias = 'High Level Language'
+}

Guide/Languages/Low-Level-Languages.md

@@ -0,0 +1,16 @@
+Low Level Languages are programming languages that do not try to be friendly.
+
+They try to be fast.  Not all succeed.
+
+Some posit that low level languages are so named for their proximity to machine code.
+
+We tend to believe that low level languages are so named for their proximity to hell.
+
+The lowest of the low-level languages is Assembly.
+
+If you find yourself dealing with assembly for more than four hours, consult your doctor.
+
+A much more common and prevalant low-level language is C.  Another quite common one in C++.
+
+In most of your experiences with PowerShell and other scripting languages,
+you need not concern yourself with the workings of low-level languages.

Guide/Languages/Low-Level-Languages.md.psd1

@@ -0,0 +1,4 @@
+@{
+    Alias = 'Low Level Language'
+}
+

Guide/Languages/Programming-Languages.md

@@ -0,0 +1,21 @@
+Programming languages are the languages we use to communicate with computers.
+
+As a general rule, programming languages are not as artful as natural languages.
+
+In fact, they can often seem a little bit scary or arcane.  We remind you:  Don't panic.
+
+If a programming language looks like something vaguely like a natural language, it's called a high level language.
+
+If a programming language looks like something truly arcane, it's called a low level language.
+
+PowerShell is quite a nice programming language, once you get the hang of it.
+
+If it's the only one you know, you may potentially die happpy (not that we have much control over that, or your opinions).
+
+Here are a few of the reasons we believe that PowerShell is quite a programming language:
+
+* It's a Scripting Language with a Shell, which makes it easy to try
+* It has things other languages lack (like the object pipeline)
+* It talks to many other languages easily
+* You can use PowerShell as a very high level language
+* You can write low level code in PowerShell when you need to.

Guide/Languages/Programming-Languages.md.psd1

@@ -0,0 +1,3 @@
+@{
+    Alias = 'Programming Language'
+}

Guide/Languages/Scripting-Languages.md

@@ -0,0 +1,17 @@
+Scripting languages are programming languages that are interpreted when they run.
+
+This is unlike a compiled programming language, which is turned into machine code and run.
+
+Nobody ever wants to deal with machine code.
+
+Scripting Languages offer some distinct advantages to their compiled kin, such as:
+
+* Generally being easier to read
+* Requiring fewer references
+* Being more flexible
+* Tolerating more problems 
+
+However, compiled programmers have threatened to beat us with a wet noodle if we do not state the two major advantages of compilation:
+
+* Machine code is faster
+* (some) problems can be discovered while compiling.

Guide/Languages/Scripting-Languages.md.psd1

@@ -0,0 +1,3 @@
+@{
+    Alias = 'Scripting_Language'
+}

Guide/PowerShell/Attributes/Attributes.md

@@ -0,0 +1,46 @@
+Attributes are, well, attributes of an object.
+
+Attributes allow us to add additional information to something in a somewhat standard way.
+
+In PowerShell, there are several places you can provide attributes:
+
+## Attributes on Script Blocks
+
+All Script Blocks in PowerShell can have attributes.
+
+They can be placed above the param block, though there has to actually _be_ a parameter block.
+
+~~~PowerShell
+{
+    [Reflection.AssemblyMetadata("SomeKey","SomeValue")]
+    param()
+}.Attributes
+~~~
+
+## Attributes on Functions
+
+Since PowerShell functions are script blocks with names, we can add an attribute to a function in the same way.
+
+~~~PowerShell
+function ACommandWithAttributes {
+    [Reflection.AssemblyMetadata("SomeKey","SomeValue")]
+    param()
+}
+
+(Get-Command ACommandWithAttributes).ScriptBlock.Attributes
+~~~
+
+## Attributes on Parameters
+
+PowerShell Parameters use attributes quite a bit.
+
+In fact, the thing that separates a simple parameter from a smart one is the presence of a `[Parameter]` attribute.
+
+~~~PowerShell
+function AFunctionWithMandatoryParameters {
+    param(
+    [Parameter(Mandatory)]
+    $ThisParameterIsMandatory
+    )
+}
+~~~

Guide/PowerShell/Attributes/Attributes.md.psd1

@@ -0,0 +1 @@
+

Guide/PowerShell/Commands/Commands.md

@@ -0,0 +1,31 @@
+Commands are a concept that far predates PowerShell, and a concept PowerShell embraces wholeheartedly and does wonderful things with.
+
+Commands, put simply, are what you use to tell a computer to do something.
+
+## Commands in PowerShell
+
+When you're talking about something like an operating system, a command is often called an Executable or an Application.
+
+One way you can think of PowerShell is like an operating system on top of the operating system.
+
+Every executable or file in an operating system is a command to PowerShell,
+and PowerShell has a lot more commands you can use on top of that.
+
+PowerShell has a few types of commands:
+
+|Command Type|Description|
+|-|-|
+|Alias|Another name for a command|
+|Function|A PowerShell function|
+|Cmdlet|A Compiled PowerShell Command|
+|ExternalScript|A PowerShell Script File|
+|Application|A operating system application or file|
+
+Sometimes you'll hear people refer to Applications as Native Commands and the other command types as PowerShell commands.
+
+In addition to having more command types than your operating system does, PowerShell's commands are a bit more capable.
+
+* Every command that runs can produce one or more objects, which can flow into the object pipeline.
+* Commands have rich command metadata.
+* PowerShell Commands have rich parameters and parameter metadata.
+* Commands in PowerShell can be stopped (often without summarilly executing the process).

Guide/PowerShell/Commands/Commands.md.psd1

@@ -0,0 +1,3 @@
+@{
+    Alias = 'Command', 'PowerShell Command', 'Commands in PowerShell'
+}

Guide/PowerShell/Commands/Get-Command.md

@@ -0,0 +1,5 @@
+Get-Command gives you all of the loaded commands in PowerShell.
+
+It is truly an indispensible cmdlet.
+
+Get-Command is part of the trinity of discoverability.

Guide/PowerShell/Commands/Get-Command.md.psd1

@@ -0,0 +1,3 @@
+@{
+    Title = "Get-Command"
+}