Bookmark and Share

 

Microsoft Scripting Guy Ed Wilson here. If you have been following us on Twitter, you know that I have been out for nearly a week due to ear surgery. While I have been recuperating, I have had a lot of time to think about the module we started last Saturday, and that we continued last Sunday. The Scripting wife took me to South Carolina coast to a little village called Murrells Inlet for a long weekend to help me rest, relax, and recover. As it turned out, it was a wonderful weekend, and I was able to walk along the beach and take some pretty cool pictures such as this one.

Image of seagulls and waves


As I was walking along the beach taking pictures, I was thinking of the capabilities our conversion function has, and I realized it did not have the ability to convert weights. To keep with our ConvertTo verb, I decided to create a function named ConvertTo-Pounds. Because you may wish to convert multiple values to pounds, I decided to add multiple input parameters. The complete ConvertTo-Pounds function is seen here.

ConvertTo-Pounds

Function ConvertTo-Pounds
{
 <#
  .Synopsis
    Converts tons, ounces, kilograms, or metric tons into pounds
   .Description
    The ConvertTo-Pounds function will accept an input in
    tons, ounces, kilograms, or metric tons and convert the result into pounds.
   .Example
    ConvertTo-Pounds -ton 1
    Converts 1 ton into pounds
   .Example
    ConvertTo-Pounds -ounce 1000
    Converts 1000 ounces into pounds
   .Example
    ConvertTo-Pounds -kilogram 1
    Converts 1 kilograms into pounds
   .Example
    ConvertTo-Pounds -metricTon 1
    Converts 1 metric ton into pounds
   .Parameter ton
    The number of tons to be converted
   .Parameter ounce
    The number of ounces to be converted
   .Parameter kilogram
    The number of kilograms to be converted
   .Parameter metricTon
    The number of metric tons to be converted
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Pounds
    AUTHOR: Ed Wilson
    AUTHOR BOOK: Windows PowerShell 2.0 Best Practices, Microsoft Press 2010
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
     Http://www.bit.ly/HSGBlog
 #>
 #Requires -Version 2.0
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $Ton,
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $Ounce,
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $KiloGram,
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $MetricTon    
) #end param
  If($ton)
    { "$ton tons equals $($ton * 2000) pounds" }
  If($ounce)
    { "$ounce ounces equals $($ounce * 0.0625) pounds" }
  If($kilogram)
    { "$kilogram kilograms equals $($kilogram * 2.205) pounds" }
  If($metricTon)
    { "$metricTon metric tons equals $($metricTon * 2205) pounds" }} #end ConvertTo-Pounds

I begin the ConvertTo-Pounds function by adding the help section. I use the Synopsis, Description, Example, Parameter, inputs, outputs, notes, and link tags. It is a best practice to include an example of using each of the parameters for your function. In addition, you should describe each of the parameters. For this function, I decided to move the #Requires tag outside of the help section. This keeps it from showing up inside the notes section of the help.

To allow for multiple conversions, I declare a parameter for each different type of value: ton, ounce, kilogram, and metric ton. None of these parameters are mandatory, and all will accept input from the pipeline. These will be named parameters; therefore, none of them have a default position assigned.

The parameter that is used determines what type of conversion will be performed. This is seen when you use the Get-Help cmdlet to display the examples, as shown here:

PS C:\> get-help ConvertTo-Pounds -Examples

NAME
    ConvertTo-Pounds

SYNOPSIS
    Converts tons, ounces, or kilograms into pounds

    -------------------------- EXAMPLE 1 --------------------------

    C:\PS>ConvertTo-Pounds -ton 1


    Converts 1 ton into pounds




    -------------------------- EXAMPLE 2 --------------------------

    C:\PS>ConvertTo-Pounds -ounce 1000


    Converts 1000 ounces into pounds




    -------------------------- EXAMPLE 3 --------------------------

    C:\PS>ConvertTo-Pounds -kilogram 1


    Converts 1 kilogram into pounds




    -------------------------- EXAMPLE 4 --------------------------

    C:\PS>ConvertTo-Pounds -metricTon 1


    Converts 1 metric ton into pounds

PS C:\>


The use of the new ConvertTo-Pounds function is seen in the following image:

Image of ConvertTo-Pounds function

 

The complete conversion module as it currently stands is seen here.

ConversionModuleV3.psm1

Function ConvertTo-Pounds
{
 <#
  .Synopsis
    Converts tons, ounces, kilograms, or metric tons into pounds
   .Description
    The ConvertTo-Pounds function will accept an input in
    tons, ounces, kilograms, or metric tons and convert the result into pounds.
   .Example
    ConvertTo-Pounds -ton 1
    Converts 1 ton into pounds
   .Example
    ConvertTo-Pounds -ounce 1000
    Converts 1000 ounces into pounds
   .Example
    ConvertTo-Pounds -kilogram 1
    Converts 1 kilograms into pounds
   .Example
    ConvertTo-Pounds -metricTon 1
    Converts 1 metricTon into pounds
   .Parameter ton
    The number of tons to be converted
   .Parameter ounce
    The number of ounces to be converted
   .Parameter kilogram
    The number of kilograms to be converted
   .Parameter metricTon
    The number of metricTons to be converted
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Pounds
    AUTHOR: Ed Wilson
    AUTHOR BOOK: Windows PowerShell 2.0 Best Practices, Microsoft Press 2010
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
     Http://www.bit.ly/HSGBlog
 #>
 #Requires -Version 2.0
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $Ton,
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $Ounce,
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $KiloGram,
      [Parameter(Mandatory = $false,valueFromPipeline=$true)]
      [Double]
      $MetricTon    
) #end param
  If($ton)
    { "$ton tons equals $($ton * 2000) pounds" }
  If($ounce)
    { "$ounce ounces equals $($ounce * 0.0625) pounds" }
  If($kilogram)
    { "$kilogram kilograms equals $($kilogram * 2.205) pounds" }
  If($metricTon)
    { "$metricTon metric tons equals $($metricTon * 2205) pounds" }
} #end ConvertTo-Pounds

Function ConvertTo-Meters
{
 <#
  .Synopsis
    Converts feet into meters
   .Description
    The ConvertTo-Meters function accepts a value in feet and
    returns a string indicating the number of meters.
   .Example
    ConvertTo-Meters 1
    Converts 1 foot into meters
   .Parameter feet
    The number of feet to be converted
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Meters
    AUTHOR: Ed Wilson
    AUTHOR BOOK: Windows PowerShell 2.0 Best Practices, Microsoft Press 2010
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
     Http://www.bit.ly/HSGBlog
 #Requires -Version 2.0
 #>
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      [Double]
      $feet
) #end param
  "$feet feet equals $($feet*.31) meters"
} #end ConvertTo-Meters

Function ConvertTo-Feet
{
 <#
  .Synopsis
    Converts meters into feet
  .Description
    The ConvertTo-Feet function accepts a value in meters and
    returns a string indicating the number of feet.
   .Example
    ConvertTo-Feet 1
    Converts 1 meter into feet
   .Parameter meters
    The number of meters to be converted into feet
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Feet
    AUTHOR: Ed Wilson
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
 #Requires -Version 2.0
 #>
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      [Double]
      $meters
) #end param
 "$meters meters equals $($meters * 3.28) feet"
} #end ConvertTo-Feet

Function ConvertTo-Fahrenheit
{
 <#
  .Synopsis
    Converts Celsius into Fahrenheit
  .Description
    The ConvertTo-Fahrenheit function accepts a value in Celsius and
    returns a string indicating the temperature in Fahrenheit.
   .Example
    ConvertTo-Fahrenheit 1
    Converts 1 degree Celsius into Fahrenheit
   .Parameter celsius
    The  temperature to be converted into Fahrenheit
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Fahrenheit
    AUTHOR: Ed Wilson
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
 #Requires -Version 2.0
 #>
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      [Double]
      $celsius
) #end param
 "$celsius celsius equals $((1.8 * $celsius) + 32 ) fahrenheit"
} #end ConvertTo-Fahrenheit

Function ConvertTo-Celsius
{
 <#
  .Synopsis
    Converts Fahrenheit into Celsius
  .Description
    The ConvertTo-Celsius function accepts a value in Fahrenheit and
    returns a string indicating the temperature in Celsius.
   .Example
    ConvertTo-Celsius 1
    Converts 1 degree Fahrenheit into Celsius
   .Parameter fahrenheit
    The  temperature to be converted
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Celsius
    AUTHOR: Ed Wilson
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
 #Requires -Version 2.0
 #>
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      [Double]
      $fahrenheit
) #end param
 "$fahrenheit fahrenheit equals $( (($fahrenheit - 32)/9)*5 ) celsius"
} #end ConvertT-Celsius

Function ConvertTo-Miles
{
 <#
  .Synopsis
    Converts kilometers into miles
  .Description
    The ConvertTo-Miles function accepts a value in kilometers and
    returns a string indicating the distance in miles.
   .Example
    ConvertTo-Miles
    Converts 1 kilometer into miles
   .Parameter kilometer
    The distance to be converted
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Miles
    AUTHOR: Ed Wilson
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
 #Requires -Version 2.0
 #>
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      [Double]
      $kilometer
) #end param
  "$kilometer kilometers equals $( ($kilometer *.6211) ) miles"
} #end ConvertTo-Miles

Function ConvertTo-Kilometers
{
 <#
  .Synopsis
    Converts miles into Kilometers
  .Description
    The ConvertTo-Kilometers function accepts a value in miles and
    returns a string indicating the distance in kilometers.
   .Example
    ConvertTo-Kilometers 1
    Converts 1 mile into kilometers
   .Parameter miles
    The distance to be converted
   .Inputs
    [double]
   .Outputs
    [string]
   .Notes
    NAME:  ConvertTo-Kilometers
    AUTHOR: Ed Wilson
    LASTEDIT: 1/31/2010
    KEYWORDS: WeekEnd Scripter, modules, getting started
   .Link
     Http://www.ScriptingGuys.com
 #Requires -Version 2.0
 #>
 [CmdletBinding()]
 param(
      [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      [Double]
      $miles
) #end param
  "$miles miles equals $( ($miles * 1.61) ) kilometers"
} #end convertTo-Kilometers

If you want to know exactly what we will be looking at tomorrow, follow us on Twitter or Facebook. If you have any questions, send e-mail to us at scripter@microsoft.com or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
 

Ed Wilson and Craig Liebendorfer, Scripting Guys