Súgó készítése

Ha készítünk függvényeket és szkripteket, akkor nem árt magyarázatokkal ellátni a „forráskódot”, hogy ha a függvényünket, szkriptünket akár mi, akár mások is megérthessék, ha használni, megérteni vagy továbbfejleszteni szeretnék. Ha pedig nem PowerShellhez értők kezébe adjuk, akkor őket is jó lenne ellátni valamilyen útmutatással a használatot illetően. Nem biztos, hogy ők értenek annyira a forráskód elemzéséhez, hogy abból mindent megértsenek, viszont nagy valószínűséggel rávehetők, hogy a PowerShell beépített súgóját kezelő Get-Help cmdletet használják. A két szempontot a PowerShell fejlesztői egyesítették, hogy ne kelljen a kettővel nekünk külön-külön, más helyen és más technológiával bajlódnunk. A megoldás az un. „comment based help”, azaz a megjegyzések formájában beágyazott súgó.

Ez azt jelenti, hogy speciális megjegyzéseket helyezhetünk el a függvényünkbe vagy szkriptünkbe, amelyeket a Get-Help  ugyanúgy jelenít meg, mint a „gyári” súgótémákat. Nézzünk erre egy példát a Pithagoras függvény segítségével:

function Pithagoras

{

<#

    .SYNOPSIS

    Kiszámolja a derégszögű háromszög átfogóját a befogókból.

 

    .DESCRIPTION

    Ez a függvény Pithagoras a^2+b^2=c^2 tétele alapján kiszámolja a

     derékszögű háromszög átfogóját a befogókból.

 

    .NOTES

    Version: 0.1.0

    Version history:

    0.1.0 26-Oct-2011 - Tibor Soos <soostibor@citromail.hu>

            First version

 

    .INPUTS

    Nincs, csővezetéken nem fogad paramétereket.

 

    .OUTPUTS

    System.Double. Kimenet a c átfogó hossza.

 

    .EXAMPLE

    C:\PS> Pithagoras 3 4

    5

           

    .EXAMPLE

    C:\PS> Pithagoras 4

    5,65685424949238

    Ebben a példában az egyenlő oldalú derékszögű háromszög átfogóját

     számolta ki.

 

    .LINK

    További információ Pithagorasz tételéről:

     http://hu.wikipedia.org/wiki/Pitagorasz-t%C3%A9tel

 

    .LINK

    about_Arithmetic_Operators

       

    #>

 

    param

    (

        [Parameter(

        Mandatory = $true,

        Position = 0,

        HelpMessage = "Ez kötelezően kitöltendő"

        )]

        [double]

        # A derékszögű háromszög egyik befogója

        $a,

 

        [Parameter(

        Mandatory = $false,

        Position = 1

        )]

        [double]

        # A derékszögű háromszög másik befogója

        $b = $a

    )           

 

    [math]::Sqrt($a*$a+$b*$b)          

}

Látható, hogy a függvény definíciójának elejére egy speciális megjegyzésblokk (<#...#>) került. Ezen belül ponttal kezdődő címkék a súgón belüli részek kulcsszavai, utánuk meg az adott részhez tartozó leírás van. Vannak olyan részek, amelyek csak egyszer fordulhatnak elő, mint például a .SYNOPSIS vagy a .DESCRIPTION, de vannak olyanok is, amelyekből több is lehet, mint például az .EXAMPLE.

Nézzük meg, hogy mit ad a függvény definiálása után a teljes változatú Get-Help:

[55] PS C:\> get-help Pithagoras -full

 

NAME

    Pithagoras

 

SYNOPSIS

    Kiszámolja a derégszögű háromszög átfogóját a befogókból.

 

SYNTAX

    Pithagoras [-a] <Double> [[-b] <Double>] [<CommonParameters>]

 

 

DESCRIPTION

    Ez a függvény Pithagoras a^2+b^2=c^2 tétele alapján kiszámolja a

    derékszögű háromszög átfogóját a befogókból.

 

 

PARAMETERS

    -a <Double>

        A derékszögű háromszög egyik befogója

 

        Required?                    true

        Position?                    1

        Default value

        Accept pipeline input?       false

        Accept wildcard characters?

 

    -b <Double>

        A derékszögű háromszög másik befogója

 

        Required?                    false

        Position?                    2

        Default value

        Accept pipeline input?       false

        Accept wildcard characters?

 

    <CommonParameters>

        This cmdlet supports the common parameters: Verbose, Debug,

        ErrorAction, ErrorVariable, WarningAction, WarningVariable,

        OutBuffer and OutVariable. For more information, type,

        "get-help about_commonparameters".

 

INPUTS

    Nincs, csővezetéken nem fogad paramétereket.

 

 

OUTPUTS

    System.Double. Kimenet a c átfogó hossza.

 

 

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

 

    C:\PS>Pithagoras 3 4

 

 

    5

 

 

 

 

 

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

 

    C:\PS>Pithagoras 4

 

 

    5,65685424949238

    Ebben a példában az egyenlő oldalú derékszögű háromszög átfogóját

    számolta ki.

 

 

 

 

 

 

RELATED LINKS

    További információ Pithagorasz tételéről:

    http://hu.wikipedia.org/wiki/Pitagorasz-t%C3%A9tel

    about_Arithmetic_Operators

Látszik, hogy vannak olyan részek, amelyeket nem én definiáltam, hanem a PowerShell automatikusan rakja össze a függvénydefiníció alapján. Ilyenek például a NAME, SYNTAX, PARAMETERS, REMARKS. Apropó PARAMETERS! A függvénydefinícióban látható, hogy a paraméterdefiníciós részbe elhelyezett megjegyzéseket is kiemeli a Get-Help, és ennél a szekciónál megjeleníti.

Erre a súgót tartalmazó megjegyzésblokkra van néhány szigorú szabály és alternatív lehetőség. Ez a blokk függvények esetében három különböző helyen lehet, de egy függvény esetében el kell döntenünk, hogy melyiket választjuk. Lehet a súgóblokk a függvény definíciós részének elején, közvetlenül a function kulcsszót követő sorban, lehet a függvénydefiníciós rész végén, a lezáró kapcsos zárójel előtt, vagy a függvénydefiníció előtt, azaz a function kulcsszót közvetlenül megelőző részben. Szerintem a legjobb az a hely, amit én használtam, azaz a függvény eleje, de végül is ez ízlés dolga.

Megjegyzés

Ha bármelyik súgórészt szimbolizáló kulcsszót elírjuk, vagy nem létező kulcsszót használunk, akkor az egész súgónk érvénytelen lesz és ilyenkor a Get-Help csak az automatikusan generálódó súgórészeket adja vissza.

Súgót lehet készíteni XML formátumban is, erre példát találhatunk a „gyári” súgótémák között a PowerShell telepítési könyvtárában. Ezt itt nem ismertetem, ezt hagyjuk meg a profi fejlesztőknek.

A szkripteket ugyanilyen módon láthatjuk el súgóval. Tegyük fel, hogy az előbb látott Pithagoras függvényt sok más matematikával kapcsolatos függvénnyel együtt egy szkriptfájlba mentjük el matek.ps1 néven, és ennek is generálok egy megjegyzés-alapú súgót:

<#

    .SYNOPSIS

    Ebben a szkriptben a matematikai függvényeim vannak.

 

    .DESCRIPTION

    Függvények:

    Pithagoras

   

    #>

 

 

function Pithagoras

{

<#

    .SYNOPSIS

    Kiszámolja a derégszögű háromszög átfogóját a befogókból.

Itt is lehet a fájl elejére vagy végére tenni a súgóblokkot. Az elejénél vigyázni kell, mert ha a szkriptem egy függvénydefinícióval kezdődik, mint a fenti példában is, akkor a PowerShell értelmezője ezt a blokkot a függvényhez sorolja. Ezt meg tudjuk akadályozni, ha a súgóblokk és a function kulcsszó sora közé legalább két üres sort teszünk.

Nézzük, hogyan kapjuk meg a szkript súgóját:

[56] PS C:\> Get-Help .\munka\matek.ps1

 

NAME

    C:\munka\matek.ps1

 

SYNOPSIS

    Ebben a szkriptben a matematikai függvényeim vannak.

 

 

SYNTAX

    C:\munka\matek.ps1 [<CommonParameters>]

 

 

DESCRIPTION

    Függvények:

    Pithagoras

 

 

RELATED LINKS

 

REMARKS

    To see the examples, type: "get-help C:\munka\matek.ps1 -examples".

    For more information, type: "get-help C:\munka\matek.ps1 -detailed".

    For technical information, type: "get-help C:\munka\matek.ps1 -full".

Természetesen ez nem egy „igazi” szkript, így a helpnek is csak elég jelképes értelme van.



Word To HTML Converter