Funkcje do manipulacji łańcuchami znaków

Ten dokument zgodny jest z NSIS 3.1


1. Wprowadzenie

Plik nagłówkowy funkcji do manipulacji łańcuchami znaków zawiera zbiór przydatnych funkcji, które łatwo dołączyć i użyć w skryptach NSIS.

2. Sposób użycia


2.1 Podstawowa składnia


Parametry mają następującą postać:

  Wymagane (wymagane) (Opcja1 | Opcja2) [opcjonalne lub dodatkowe opcje] [Opcja1 | Opcja2]

Znaki gwiazdek, które znajdują się koło nazw poleceń (*****) są subiektywnym określeniem przydatności danej funkcji. Im więcej gwiazdek, tym bardziej funkcja jest przydatna. Najwyższą ocenę reprezentuje 5 gwiazdek (*****).

W każdym miejscu, gdy napisane jest "Wartość domyślna", oznacza to, że możesz użyć wymienionej wartości lub pozostawić ją pustą - rezultat będzie taki sam.

Jeśli chcesz, aby określona wartość (np. tekst) była zależna od języka, użyj łańcucha znaków języka (polecenie LangString) oraz zdefiniuj wartość $(STRINGNAME).

Jeśli chcesz do łańcucha znaków dodać znak '`', powinieneś zawsze używać znaku modyfikacji '$\`', ponieważ funkcje makra pliku nagłówkowego używają znaku '`' do rozdzielania parametrów.


2.1.1 Dołączanie pliku nagłówkowego


    !include "StrFunc.nsh"

Plik nagłówkowy StrFunc.nsh musi znajdować się w katalogu dołączanych plików (Include), więc nie musisz określać ścieżki dostępu.

Polecenie to musisz umieścić przed każdym innym, które znajdziesz w tym pliku.


2.1.2 Definicje


Plik nagłówkowy zawiera definicje, które automatyzują pewne czynności. Zanim ich użyjesz, przeczytaj poniższe:

  • Każdy element zdefiniowanej wartości rozdzielony jest znakiem "|", a każdy podelement (element podrzędny) rozdzielony jest znakiem " ".
  • Użyj składni ${StrTok} $var "${DefineName}" "|" "$counter" "0", aby pobrać każdy element definicji. Aby pobrać jego podelementy, użyj składni: ${StrTok} $var2 "$var" " " "$counter2" "0", po pobraniu wartości elementu.
  • Lista ${StrFunc_List} jest tworzona automatycznie przez plik nagłówkowy. Reszta dodawana jest ręcznie.

2.1.2.1 Lista definicji

  • StrFunc_List

    Określa nazwy wszystkich funkcji dostępnych w pliku nagłówkowym StrFunc.

  • *_List

    Określa nazwy wszystkich parametrów dostępnych dla funkcji "*". (* = nazwa funkcji, np: StrTok_List).

  • *_TypeList

    Określa typy wszystkich parametrów dla funkcji "*". (* = nazwa funkcji, np: StrTok_List). Możliwe typy dla każdego z parametrów to:

    • Output (wyjście)

      Wymagana jest zmienna, aby przekazać wartość zwracaną przez funkcję.

    • Text (tekst)

      Wymagany jest tekst lub liczba, jako wartość wejściowa.

    • Mixed (mieszane)

      Wymagany jest tekst, liczba lub opcja, jako wartość wejściowa. Każdy podelement poprzedzony słowem "Mixed", jest opcją. Pierwsza opcja jest opcją domyślną. Dwie następujące po sobie spacje (" ") oznaczają, że podelement jest pusty.

    • Option (opcja)

      Wymagana jest opcja, jako wartość wejściowa. Każdy podelement poprzedzony słowem "Option", jest opcją. Pierwsza opcja jest opcją domyślną. Dwie następujące po sobie spacje (" ") oznaczają, że podelement jest pusty.

2.1.3. Polecenia


Niektóre polecenia wymagają specjalnych zabiegów, żeby działały. Sprawdź poniższą sekcję Polecenia.


2.1.3.1 Sposób użycia poleceń w sekcjach i funkcjach instalacji


Każde polecenie używane w sekcjach i funkcjach instalacji muszą być wywołane wpierw poza obszarem sekcji bądź funkcji, bez podawania jakichkolwiek parametrów.

Przykład: ${StrStr}


2.1.3.2 Sposób użycia poleceń w sekcjach i funkcjach deinstalacji


Polecenia w sekcjach i funkcjach deinstalacji muszą mieć przedrostek "Un" przed słowem znajdującym się w nawiasie klamrowym "{}".

Przykład: ${UnStrStr}

Pełny przykład poleceń instalacji oraz deinstalacji:

    !include "StrFunc.nsh"

    ${StrStr} # dla sekcji oraz funkcji instalacji

    ${UnStrStr} # dla sekcji oraz funkcji deinstalacji

    Section

      ${StrStr} $0 "OK! Co teraz?" "wh"

    SectionEnd

    Section Uninstall

      ${UnStrStr} $0 "OK! Co teraz?" "wh"

    SectionEnd

2.1.3.3 Polecenia


** ${StrCase}

    ResultVar String Type(|L|U|T|S|<>)

Konwertuje łańcuch znaków "String" na łańcuch znaków "Type" z określoną wielkością znaków. Używa LogicLib.


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków konwertowany na łańcuch znaków "Type", o określonej wielkości znaków.

Type - Typ wielkości liter:

  • "" = Tak samo jak wejściowy łańcuch znaków (tak jak "String")
  • L = Małe litery (to jest przykład. bardzo prosty.)
  • U = Duże litery (TO JEST PRZYKŁAD. BARDZO PROSTY.)
  • T = Tytułowe litery (To Jest Przykład. Bardzo Prosty.)
  • S = Początek zdania (To jest przykład. Bardzo prosty.)
  • <> = Zamiana wielkości liter (To jest przykład. Bardzo prosty.)

Domyślną wartością jest "" (oryginalna wielkość liter).


Zwracana wartość -> ResultVar:

łańcuch znaków "String" jako łańcuch znaków "Type" z określoną wielkością znaków.


Przykład:

      ${StrCase} $0 '"Vocę" to "TY" po polsku.' "U"
                                [__(_)__()___()__()__(____)_]

      $0 = '"VOCĘ" TO "TY" PO POLSKU.'

* ${StrClb}

    ResultVar String Action(|>|<|<>)    ResultVar String Type(|L|U|T|S|<>)

Wykonuje akcje na schowku, w zależności od wartości parametru "Action". Używa LogicLib.


Parametry:

String - Jeśli parametr "Action" = ">" lub "<>" - łańcuch znaków String umieszczony zostanie w schowku.

Action - Parametr ten może przyjmować następujące wartości:

  • "" = Czyści schowek.
  • ">" = Kopiuje dane do schowka.
  • "<" = Pobiera dane ze schowka.
  • "<>" = Zamienia łańcuch znaków z zawartością schowka.

Zwracana wartość -> ResultVar:

Jeśli parametr "Action" = "<" lub "<>" - łańcuch znaków String został znaleziony w schowku.

*** ${StrIOToNSIS}

    ResultVar String

Konwertuje łańcuch znaków "String" wtyczki Install Options, aby był obsługiwany przez NSIS. Konwertowane są znaki Escape, back-slash, carriage return, line feed oraz tab.


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - Konwertowany łańcuch znaków String.

Type - Typ znaku, w który zostanie skonwertowana wartość wejściowa:


Zwracana wartość -> ResultVar:

łańcuch znaków "String" obsługiwany przez NSIS.


Przykład:

      ${StrIOToNSIS} $0 "\r\n\t\\To jest przykład\\"
                                       [()()()()_____________()]

      $0 = "$\r$\n$\t\To jest przykład\"

* ${StrLoc}

    ResultVar String StrToSearchFor CounterDirection(>|<)

Wyszukuje łańcucha znaków "StrToSearchFor" w łańcucha znaków "String" i zwraca jego położenie, w zależności od kierunku przeszukiwania "CounterDirection".


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków, w którym wyszukiwany jest łańcuch znaków "StrToSearchFor".

StrToSearchFor - łańcuch znaków, który wyszukiwany jest w łańcucha znaków "String".

CounterDirection(>|<) - Kierunek wyszukiwania. Domyślnie ma wartość ">". (> = z lewej do prawej, < = z prawej do lewej)


Zwracana wartość -> ResultVar:

Wyszukuje lokalizację łańcucha znaków "StrToSearchFor", w zależności od kierunku "OffsetDirection".


Przykład:

      ${StrLoc} $0 "To jest przykład" "jest" "<"
                                 (__)<<<<<<<<<<<

      $0 = "9"

*** ${StrNSISToIO}

    ResultVar String

Konwertuje łańcuch znaków "String" z formatu NSIS, aby był zgodny z wtyczką Install Options. Konwertowane są znaki: Escape, back-slash, carriage return, line feed oraz tab.


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - Konwertowany łańcuch znaków, aby był zgodny z wtyczką Install Options.


Zwracana wartość -> ResultVar:

łańcuch znaków "String" zgodny z wtyczką Install Options.


Przykład:

      ${StrNSISToIO} $0 "$\r$\n$\t\To jest przykład\"
                                      [(_)(_)(_)^____________^]

      $0 = "\r\n\t\\To jest przykład\\"

***** ${StrRep}

    ResultVar String StrToReplace ReplacementString

Wyszukuje wszystkie wystąpienia łańcucha znaków "StrToReplace" w łańcucha znaków "String", zastępując go łańcuchem znaków "ReplacementString".


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków, w którym wyszukiwany jest łańcuch znaków "StrToReplace".

StrToReplaceFor - Wyszukiwany łańcuch znaków w łańcucha znaków "String".

StringToBeReplacedWith - łańcuch znaków, który zastępuje wyszukany łańcuch znaków "StringToReplace" w łańcucha znaków "String".


Zwracana wartość -> ResultVar:

łańcuch znaków "String" z wszystkimi wystąpieniami łańcucha znaków "StringToReplace", zamienianymi na łańcuch znaków "ReplacementString".


Przykład:

      ${StrRep} $0 "To jest tylko przykład" "tylko" "pierwszy"
                              [______(    )_______]

      $0 = "To jest pierwszy przykład"

*** ${StrSort}

    ResultVar String LeftStr CenterStr RightStr IncludeLeftStr(1|0)
    IncludeCenterStr(1|0) IncludeRightStr(1|0)

Wyszukuje łańcuch znaków "CenterStr" w łańcucha znaków "String" zwracając tylko wartości znajdujące się pomiędzy łańcuchami znaków "LeftStr" oraz "RightStr", łącznie z łańcuchem znaków "CenterStr" (lub nie) używając "IncludeCenterStr" oraz/lub z łańcuchem znaków "LeftStr" używając "IncludeLeftStr" oraz "RightStr" używając "IncludeRightStr".


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków, w którym wyszukiwany jest łańcuch znaków "CenterStr".

LeftStr - Pierwsze wystąpienie łańcucha znaków "LeftStr" na lewo od łańcucha znaków "CenterStr". Jeśli jego wartość jest pusta lub nie został znaleziony, zwrócony zostanie łańcuch znaków po lewej stronie łańcucha znaków "CenterStr".

CenterStr - łańcuch znaków wyszukiwany w łańcucha znaków "String".

RightStr - Pierwsze wystąpienie łańcucha znaków "RightStr" na prawo od łańcucha znaków "CenterStr". Jeśli jego wartość jest pusta lub nie został znaleziony, zwrócony zostanie łańcuch znaków po prawej stronie łańcucha znaków "CenterStr".

IncludeLeftStr(1|0) - Dołącz lub nie łańcuch znaków "LeftStr" w zwracanym łańcucha znaków. Domyślną wartością jest 1 (True). (1 = True, 0 = False)

IncludeCenterStr(1|0) - Dołącz lub nie łańcuch znaków "CenterStr" w zwracanym łańcucha znaków. Domyślną wartością jest 1 (True). (1 = True, 0 = False)

IncludeRightStr(1|0) - Dołącz lub nie łańcuch znaków "RightStr" w zwracanym łańcucha znaków. Domyślną wartością jest 1 (True). (1 = True, 0 = False)


Zwracana wartość -> ResultVar:

łańcuch znaków znajdujący się pomiędzy łańcuchem znaków "LeftStr" oraz "RightStr" wyszukanego łańcucha znaków "CenterStr", wraz z dołączonym (lub nie) łańcuchem znaków "LeftStr" oraz "RightStr", jeśli wartość "IncludeLeftRightStr" równa jest 1 oraz/lub z łańcuchem znaków "CenterStr", jeśli wartość "IncludeCenterStr" równa jest 1.


Przykład:

      ${StrSort} $0 "To jest fajny przykład" " jest" "" "ład" "0" "0" "0"
                               [__(__)_________]( )
                                      C                     R
      $0 = "To jest fajny przyk"

***** ${StrStr}

    ResultVar String StrToSearchFor

Wyszukuje łańcucha znaków "StrToSearchFor" w łańcucha znaków "String".


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków, w którym wyszukiwany jest łańcuch znaków "StrToSearchFor".

StrToSearchFor - Wyszukiwany łańcuch znaków w łańcucha znaków "String".


Zwracana wartość -> ResultVar:

łańcuch znaków "StrToSearchFor" plus łańcuch znaków znajdujący się po łańcucha znaków "StrToSearchFor" w łańcucha znaków "String".


Przykład:

      ${StrStr} $0 "To jest tylko przykład" "tylko"
                   >>>>>>>>>{__)_______]

      $0 = "tylko przykład"

***** ${StrStrAdv}

    ResultVar String StrToSearchFor SearchDirection(>|<)
    ResultStrDirection(>|<) DisplayStrToSearch(1|0) Loops CaseSensitive(0|1)

Wyszukuje łańcuch znaków "StrToSearchFor" w łańcucha znaków "String" w kierunku określonym przez "SearchDirection" oraz liczbą powtórzeń "Loops".


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków, w którym wyszukiwany jest łańcuch znaków "StrToSearchFor".

StrToSearchFor - Wyszukiwany łańcuch znaków w łańcucha znaków "String".

SearchDirection (>|<) - Kierunek wyszukiwania. Domyślnie: ">" (w prawo). (< = w lewo, > = w prawo)

ResultStrDirection (>|<) - Miejsce wynikowego łańcucha znaków w zależności od pozycji "StrToSearchFor". Domyślnie: ">" (w prawo). (< = w lewo, > = prawo)

DisplayStrToSearch (1|0) - Wyświetl łańcuch znaków "StrToSearchFor" w wyniku. Domyślnie: "1" (True). (1 = True, 0 = False)

Loops - Liczba powtórzeń wyszukiwania łańcucha znaków "StrToSearchFor" w łańcucha znaków "String", bez oryginalnego wykonania. Domyślnie: "0" (1 powtórzenie).

CaseSensitive(0|1) - Jeśli wartość równa jest "1", w wyszukiwaniu brane pod uwagę będą wielkości liter (różnice). Jeśli wartość równa jest "0" wielkość liter nie ma znaczenia. Domyślnie: "0".


Zwracana wartość -> ResultVar:

łańcuch znaków "StrToSearchFor", jeśli wartość "DisplayStrToSearch" równa jest 1, plus wynikowy łańcuch znaków po lub przed łańcuchem znaków "StrToSearchFor", w zależności od "ResultStrDirection".


Wyniki z błędami:

Jeśli łańcuch znaków "StrToSearchFor" nie został znaleziony, zwrócony zostanie pusty łańcuch znaków.

Jeśli łańcuch znaków "StrToSearchFor" jest pusty, zwrócony zostanie łańcuch znaków "String" i ustawiona zostanie flaga błędu.

Jeśli łańcuch znaków "String" jest pusty, zwrócony zostanie łańcuch znaków i ustawiona zostanie flaga błędu.


Przykład:

      ${StrStrAdv} $0 "To JEST naprawdę tylko przykład" "JEST " ">" ">" "0" "0" "1"
                            >>>>>(   )[___________________]

      $0 = "naprawdę tylko przykład"

**** ${StrTok}

    ResultVar String Separators ResultPart[L] SkipEmptyParts(1|0)

Zwraca część "ResultPart" znajdującą się pomiędzy dwoma separatorami "Separators" wewnątrz łańcucha znaków "String".


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków, w którym wyszukiwane są separatory "Separators".

Separators - Znaki wyszukiwane w łańcucha znaków "String".

ResultPart[L] - Część, która ma być wyszukana "StrToTokenize", pomiędzy dwoma separatorami "Separators". Może być to dowolna liczba, poczynając od 0, oraz kończąc na "L". Domyślnie jest to L (ostatnia część).

SkipEmptyParts(1|0) - Pomija puste części łańcucha znaków pomiędzy dwoma separatorami "Separators". Domyślnie ma wartość 1 (True). (1 = True, 0 = False)


Zwracana wartość -> ResultVar:

łańcuch znaków "String" z liczbą "Part" pomiędzy separatorami "Separators".


Przykład:

      1) ${StrTok} $0 "This is, or is not, just an example" " ," "4" "1"
                                   (  )  ()  () () [_]   (  )  ()   (      )
                                   0     1   2  3  4     5     6    7
         $0 = "not"

      2) ${StrTok} $0 "This is, or is not, just an example" " ," "4" "0"
                                   (  ) () ^() [] ( ) ^(  )   ()  (      )
                                   0    1  23  4  5   67      8    9
         $0 = "is"

* ${StrTrimNewLines}

    ResultVar String

Usuwa niepotrzebne nowe linie na końcu łańcucha znaków "String".


Parametry:

ResultVar - Miejsce docelowe zwracanej wartości.

String - łańcuch znaków, w którym wyszukiwane są zbędne nowe linie na końcu "String".


Zwracana wartość -> ResultVar:

łańcuch znaków "String" bez usuniętych nowych linii na końcu.


Przykład:

      ${StrTrimNewLines} $0 "$\r$\nTo jest przykład$\r$\n$\r$\n"
                                            [__________________(_)(_)(_)(_)]

      $0 = "$\r$\nTo jest przykład"

Funkcje, które zostały dołączone oraz funkcje pominięte


11 funkcji zostało dołączonych - Nie są dostępne w archiwum. Są w formacie LogicLib.

15 funkcji zostało pominiętych

12 z nich zostało pominiętych, ponieważ były lepsze od nich

6 z nich zostało pominiętych z uwagi na obecność polecenia AdvStrTok (tutaj: StrTok)

  • Funkcje operujące na początkowej części łańcucha znaków
  • Funkcje zapisu zmiennych
  • Funkcje sortujące łańcuchy znaków (1, 2 i 3)
  • Funkcja StrTok

2 z nich zostało pominiętych z uwagi na obecność polecenia StrCase

  • Funckja StrLower
  • Funkcja StrUpper

2 z nich zostało pominiętych z uwagi na obecność polecenia StrClb

  • Funckja StrClbSet
  • Funckja StrClbGet

1 z nich została pominięta z uwagi na obecność poleceń NSISToIO oraz IOToNSIS

  • Funkcja konwersji znaku / na // w ścieżkach

1 z nich została pominięta z uwagi na oryginalną implementację funkcji String Replace (tutaj: StrRep)

  • Funkcja String Replace (zamiana znaków łańcucha znaków)

2 z nich zostało pominiętych z uwagi na ich nieprzydatność

  • Funkcja konwersji znaku Slash <-> Backslash
  • Funkcja Trim (ucinanie)

1 z nich została pominięta z uwagi na błędy

  • Funkcja konwertująca liczbę w łańcuch znaków

3. Autorzy

Autor: Diego Pedroso (aka deguix).

Wszystkie funkcje w formacie LogicLib: Diego Pedroso. Oparte są one na funkcjach napisanych przez: Amir Szekely, Dave Laundon, Hendri Adriaens, Nik Medved, Joost Verburg, Stuart Welch, Ximon Eighteen, "bigmac666" oraz "bluenet". Dołączone zostały funkcje w formacie LogicLib - StrIOToNSIS, StrNSISToIO autorstwa "bluenet".

4. Licencja

This header file is provided 'as-is', without any express or implied warranty. In no event will the
author be held liable for any damages arising from the use of this header file.

Permission is granted to anyone to use this header file for any purpose, including commercial
applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this header file must not be misrepresented; you must not claim that you wrote
   the original header file. If you use this header file in a product, an acknowledgment in the
   product documentation would be appreciated but is not required.
2. Altered versions must be plainly marked as such, and must not be misrepresented as being the
    original header file.
3. This notice may not be removed or altered from any distribution.