title: Powershell: unexpected return value from function, use of $args to access parameters
body: <p>Ok, I have coded for quite a while in different, but I am not getting Powershells concept of a function return?....</p>
  
  <p>I am very new to Powershell, so I am sure I am missing something very basic.  </p>
  
  <p>I have the function below:</p>
  
  <pre><code>function plGetKeyValue ([string] $FileName, [string] $SectionName, [string] $Key) 
  {
      if ($PSBoundParameters.Count -lt 2 -or $PSBoundParameters.Count -gt 3  )
      {
          "Invalid call to {0} in {1}" -f $MyInvocation.MyCommand.Name, 
                                          $MyInvocation.MyCommand.ModuleName
          return 
      }
  
      # Declaration
      $lFileContents  = ""
      $lSections      = ""
      $lDataStart     = ""
      $lStart         = -1
      $lEnd           = -1
      $lFoundSection  = ""
      $lNextSection   = ""
      $lResults       = ""
      $lRetValue      = ""
  
      # Handle the optional parameter.
      if ( $PSBoundParameters.Count -eq 2  ) {
          $PSBoundParameters.Add('Key', $SectionName)
          $PSBoundParameters.Remove('SectionName')        
          $Key = $SectionName
          $SectionName = $null
      }
  
  
      # Read the file in 
      $lFileContents  = Get-Content $FileName | Select-String -Pattern .* 
  
      # Get the sections.
      $lSections = $lFileContents -match '\[' 
      $lSections = $lSections -notmatch '#' 
  
      # Start of the data.
      $lDataStart = $lFileContents | Select-String -Pattern "^#", "^$" -NotMatch `
                                   | select-object -First 1
  
      # We have a section.
      if ( $PSBoundParameters.ContainsKey( 'SectionName' ) ) {
  
          # Find the section.
          $lFoundSection = $lSections | Select-String -Pattern "$lSectionName\b"
  
          # If none found we are out.
          if ( -Not $lFoundSection) { return $lRetValue }
  
          # Starting point for the key search is the line following 
          # the found section.
          $lStart = $lFoundSection[0].LineNumber
  
          # Loop through the sections and find the one after the found one.
          $lNextSection = $lSections | ForEach-Object { 
              # If we hit it, break.
              if ($_.LineNumber -gt $lStart) {
                  break;
              }
          } 
  
          # Set the ending line for the search to the end of the section
          # or end of file.  Which ever we have.
          if ($lNextSection) {
              $lEnd = $lNextSection[0].LineNumber
          } else {
              $lEnd = $lFileContents[-1]
          }
      } else {
      # No section.
          $lStart = $lDataStart.LineNumber
  
          # Set the ending line for the search to the end of the section
          # or end of file.  Which ever we have.
          if ($lSections) {
              $lEnd = $lSections[0].LineNumber
          } else {
              $lEnd = $lFileContents[-1]
          }
      }
  
      # Extract the lines starting with the key.
      $lResults = $lFileContents[$lStart..$lEnd] -match "$Key\b"     
      # We got results.
  
      # Split the value off.
      return $lRetValue = $lResults[0] | Select -ExpandProperty "Line" 
  }
  </code></pre>
  
  <p>The process of creating this function has sparked several questions that I have researched and become confused with</p>
  
  <p>1) The documentation indicates that $args should be used to determine arguments.  It never seems to populate for me?  I am using version 4?  As a alternative I used $PSBoundParameters.  Is this advisable?</p>
  
  <p>2) Based on a lot of reading and head scratching, I have found that return values from functions rturn all uncaptured output to the pipeline.  Can someone, please clarify uncaptured?  </p>
  
  <p>As an example, I would like the function below to return a string in the variable $lRetValue.  Currently, it is returning True.  Based on that I believe I have something uncaptured?  But everything I am executing is captured in a variable.  What am I missing?</p>
  
  <p>The calling routine is calling the code in the following form:</p>
  
  <pre><code>$FileName = "S:\PS\Home\GlobalConfig\jobs.cfg"
  $key = "Help"
  $section = "Section"
  
  $r = plGetKeyValue $FileName $Key
  write-host "r is:  $r"
  </code></pre>
  
  <p>The output shows as follows:</p>
  
  <p>PS C:> S:\PS\Home\Job\Test.ps1
  r is:  True</p>
  
  <p>Any assistance would be very much appreciated.</p>