Obsah
Rejstřík 🔎︎

# Služba ScriptForge.FileSystem

Služba FileSystem obsahuje procedury pro manipulaci se soubory a složkami. Příklady funkcí poskytovaných touto službou jsou:

- Ověření, zda soubor či složka existuje.

- Vytváření a mazání složek a souborů.

- Spouštění dialogových oken pro otevírání a ukládání souborů.

- Přístup k seznamu souborů ve složce apod.

Metody služby FileSystem jsou založeny převážně na rozhraní UNO XSimpleFileAccess.

## Definice

Následující tabulka uvádí hlavní parametry používané většinou metod služby FileSystem.

Parametr | Popis
FileName | Úplný název souboru včetně cesty bez oddělovače cesty na konci.
FolderName | Úplný název složky včetně cesty. Na konci může volitelně obsahovat oddělovač cesty.
Name | Poslední část parametru Folder Name nebo File Name včetně přípony. Tento parametr je vždy zapsán v nativním formátu operačního systému.
BaseName | Poslední část parametru Folder Name nebo File Name bez přípony.
NamePattern | Jakýkoliv z výše uvedených názvu obsahující v poslední části zástupné znaky, kterými jsou: "?" představuje libovolný jediný znak "*" představuje žádný, jeden či více znaků

Služba FileSystem umožňuje provádět operace na více souborech najednou. Pomocí vzorků pro názvy může uživatel více souboru kopírovat, přesouvat nebo mazat. Naproti tomu vestavěné metody Basicu mohou pracovat pouze s jednotlivými soubory.

### Zápis názvu souboru

Zápis použitý pro názvy souborů a složek, a to jak pro argument, tak návratové hodnoty, je definován vlastností FileNaming služby FileSystem.

Název lze reprezentovat typem "URL" (zápis URL), "SYS" (zápis operačního systému) nebo "ANY" (výchozí). Další informace následují níže.

Příkladem zápisu URL je file:///C:/Documents/my_file.odt. Zvažte použití tohoto zápisu, kdykoliv je to možné, jedná se totiž o nejpřenositelnější možnost.

## Volání služby

Před používáním je nutné službu FileSystem knihovny ScriptForge načíst pomocí:

            GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")

V následující části kódu se vytvoří instance služby FileSystem. Jako příklad se zavolá metoda BuildPath.

          Dim FSO As Variant
          FSO = CreateScriptService("FileSystem")
          FSO.BuildPath(...)

Tato služba je plně podporována v jazycích Basic i Python. Všechny příklady jsou uvedeny v programovacím jazyce Basic a lze je snadno převést na Python.

## Vlastnosti

Název | Pouze pro čtení | Typ | Popis
FileNaming | ne | String | Nastaví nebo vrátí aktuální zápis pro soubory a složky jako jednu z možností "ANY", "URL" a "SYS": "ANY": (výchozí). Metodám služby FileSystem lze předávat vstupní argumenty v zápise URL i aktuálního operačního systému, ale vždy vrátí řetězce URL. "URL": metody služby FileSystem používají zápis URL pro vstupní argumenty i návratové hodnoty. "SYS": metody služby FileSystem používají zápis aktuálního operačního systému pro vstupní argumenty i návratové hodnoty. Jakmile je nastavena, zůstává vlastnost FileNaming nezměněna buď do svého opětovného nastavení, nebo do ukončení relace LibreOffice.
ConfigFolder | ano | String | Vrátí konfigurační složku LibreOffice.
ExtensionsFolder | ano | String | Vrátí složku s nainstalovanými rozšířeními.
HomeFolder | ano | String | Vrátí domovskou složku uživatele.
InstallFolder | ano | String | Vrátí instalační složku LibreOffice.
TemplatesFolder | ano | String | Vrátí složku obsahující soubory s nainstalovanými šablonami.
TemporaryFolder | ano | String | Vrátí složku s dočasnými soubory určenou v nastavení cest pro LibreOffice.
UserTemplatesFolder | ano | String | Vrátí složku obsahující soubory s uživatelem definovanými šablonami.

Seznam metod služby FileSystem
BuildPath CompareFiles CopyFile CopyFolder CreateFolder CreateTextFile DeleteFile DeleteFolder FileExists | Files FolderExists GetBaseName GetExtension GetFileLen GetFileModified GetName GetParentFolderName | GetTempName HashFile MoveFile MoveFolder OpenTextFile PickFile PickFolder SubFolders

## BuildPath

Spojí název složky s názvem souboru a vrátí úplný název s platným oddělovačem cesty, který se přidá jen tehdy, je-li to nutné.

### Syntaxe:

            FSO.BuildPath(FolderName As String, Name As String) As String

### Parametry:

FolderName: Cesta, s níž se zkombinuje argument name. Určená cesta nemusí odpovídat existující složce.

Name: Název souboru, který se má připojit k argumentu FolderName. Tento parametr používá zápis aktuálního operačního systému.

### Příklad:

          Dim FSO : FSO = CreateScriptService("FileSystem")
          FSO.FileNaming = "URL"
          MsgBox FSO.BuildPath("file:///home/user", "sample file.odt")
          'file:///home/user/sample%20file.odt

## CompareFiles

Porovná dva soubory a vrátí True, pokud se zdají být totožné.

V závislosti na hodnotě argumentu CompareContents je k porovnání souborů použity buď pouze jejich atributy (například datum poslední změny), nebo obsah souboru.

### Syntaxe:

              FSO.CompareFiles(FileName1 As String, FileName2 As String, [CompareContents As Boolean]) As Boolean

### Parametry:

FileName1, FileName2: Soubory, které se mají porovnat.

CompareContents: Je-li True, porovná se obsah souborů (výchozí = False).

### Příklad:

            FSO.FileNaming = "SYS"
            If FSO.CompareFiles("C:\myFile1.txt", "C:\myFile2.txt", CompareContents := False) Then
                ...
            End If

## CopyFile

Zkopíruje jeden či více souborů z jednoho umístění na jiné. Vrátí True, pokud byl zkopírován alespoň jeden soubor, nebo False, nastane-li chyba.

K chybě dojde i tehdy, jestliže parametr Source používá zástupné znaky, které neodpovídají žádnému souboru.

Při výskytu chyby se metoda okamžitě ukončí. Přitom však nevrátí zpět žádné změny, které do té doby provede.

### Syntaxe:

            FSO.CopyFile(Source As String, Destination As String, [Overwrite As Boolean]) As Boolean

### Parametry:

Source: Jeden či více souborů, které se mají zkopírovat, zadané jako FileName nebo NamePattern.

Destination: Může být FileName určující, kam se má zkopírovat jediný soubor Source, nebo FolderName udávající, kam se má zkopírovat více souborů Source.

- Jestliže FolderName neexistuje, vytvoří se.

- V argumentu Destination nejsou povoleny zástupné znaky.

Overwrite: Je-li True (výchozí), soubory mohou být přepsány. Pokud je složka Destination pouze pro čtení, metoda selže bez ohledu na hodnotu tohoto parametru.

### Příklad:

            FSO.FileNaming = "SYS"
            ' Zkopíruje jediný soubor
            FSO.CopyFile("C:\Documents\my_file.odt", "C:\Temp\copied_file.odt")
            ' Zkopíruje více souborů. Zkopírují se pouze soubory, nikoliv podsložky.
            FSO.CopyFile("C:\Documents\*.*", "C:\Temp\", Overwrite := False)

## CopyFolder

Zkopíruje jednu či více složek z jednoho umístění na jiné. Vrátí True, pokud byla zkopírována alespoň jeden složka, nebo False, nastane-li chyba.

K chybě dojde i tehdy, jestliže parametr Source používá zástupné znaky, které neodpovídají žádné složce.

Při výskytu chyby se metoda okamžitě ukončí. Přitom však nevrátí zpět žádné změny, které do té doby provede.

### Syntaxe:

            FSO.CopyFolder(Source As String, Destination As String, [Overwrite As Boolean]) As Boolean

### Parametry:

Source: Jedna či více složek, které se mají zkopírovat, zadané jako FolderName nebo NamePattern.

Destination: Určuje jako FolderName složku, do níž se má jedna či více složek definovaná argumentem Source zkopírovat.

- Jestliže FolderName neexistuje, vytvoří se.

- V argumentu Destination nejsou povoleny zástupné znaky.

Overwrite: Je-li True (výchozí), soubory mohou být přepsány. Pokud je složka Destination pouze pro čtení, metoda selže bez ohledu na hodnotu tohoto parametru.

### Příklad:

            FSO.FileNaming = "SYS"
            FSO.CopyFolder("C:\Documents\*", "C:\Temp\", Overwrite := False)
            ' Zkopírují se složky včetně jejich souborů a podsložek

## CreateFolder

Vytvoří složku zadanou jako FolderName. V případě úspěšného vytvoření vrátí True.

Pokud pro zadanou složku neexistuje rodičovská složka, vytvoří se.

### Syntaxe:

            FSO.CreateFolder(FolderName As String) As Boolean

### Parametry:

FolderName: Řetězec představující složku, která se má vytvořit. Pokud již složka existuje, nastane výjimka.

### Příklad:

            FSO.FileNaming = "SYS"
            FSO.CreateFolder("C:\NewFolder\")

## CreateTextFile

Vytvoří zadaný soubor a vrátí objekt TextStream, který lze použít k zápisu do tohoto souboru.

Nastane-li chyba, metoda vrátí objekt Null.

### Syntaxe:

            FSO.CreateTextFile(FileName As String, [Overwrite As Boolean], [Encoding As String]) As Object

### Parametry:

FileName: Název souboru, který se má vytvořit.

Overwrite: Booleovská hodnota určující, zda je možné soubor FileName přepsat (výchozí = True).

Encoding: Znaková sada, která se má použít. Výchozím kódováním je "UTF-8".

### Příklad:

            Dim myFile As Object
            FSO.FileNaming = "SYS"
            Set myFile = FSO.CreateTextFile("C:\Temp\ThisFile.txt", Overwrite := True)

Podrobnosti o názvech znakových sad naleznete na stránce znakových sad IANA. Mějte na paměti, že v LibreOffice nemusí být všechny znakové sady implementovány.

## DeleteFile

Smaže jeden či více souborů. Vrátí True, pokud byl smazán alespoň jeden soubor, nebo False, nastane-li chyba.

K chybě dojde i tehdy, jestliže parametr FileName používá zástupné znaky, které neodpovídají žádnému souboru.

Soubory, které se mají smazat, nesmí být pouze pro čtení.

Při výskytu chyby se metoda okamžitě ukončí. Přitom však nevrátí zpět žádné změny, které do té doby provede.

### Syntaxe:

            FSO.DeleteFile(FileName As String) As Boolean

### Parametry:

FileName: Jeden či více souborů, které se mají smazat, zadané jako FileName nebo NamePattern.

### Příklad:

            FSO.FileNaming = "SYS"
            FSO.DeleteFile("C:\Temp\*.docx")
            ' Smažou se pouze soubory, nikoliv podsložky

## DeleteFolder

Smaže jednu či více složek. Vrátí True, pokud byla smazána alespoň jedna složka nebo False, nastane-li chyba.

K chybě dojde i tehdy, jestliže parametr FolderName používá zástupné znaky, které neodpovídají žádné složce.

Složky, které se mají smazat, nesmí být pouze pro čtení.

Při výskytu chyby se metoda okamžitě ukončí. Přitom však nevrátí zpět žádné změny, které do té doby provede.

### Syntaxe:

            FSO.DeleteFolder(FolderName As String) As Boolean

### Parametry:

FolderName: Jedna či více složek, které se mají smazat, zadané jako FolderName nebo NamePattern.

### Příklad:

            FSO.FileNaming = "SYS"
            FSO.DeleteFolder("C:\Temp\*")
            ' Smažou se pouze složky, nikoliv soubory ve složce nejvyšší úrovně (C:\Temp\)

## FileExists

Vrátí True, pokud je zadaný název souboru platný a soubor existuje. V opačném případě metoda vrátí False.

Jestliže je parametr FileName názvem existující složky, metoda vrátí False.

### Syntaxe:

            FSO.FileExists(FileName As String) As Boolean

### Parametry:

FileName: Řetězec představující soubor, který se má otestovat.

### Příklad:

            FSO.FileNaming = "SYS"
            If FSO.FileExists("C:\Documents\my_file.odt") Then
                '...
            End If

## Files

Vrátí pole začínající od 0 se soubory uloženými v zadané složce. Položkami pole jsou řetězce obsahující úplnou cestu a název souboru.

Jestliže FolderName neexistuje, je vyvolána výjimka.

Výsledný seznam může být filtrován pomocí zástupných znaků.

### Syntaxe:

            FSO.Files(FolderName As String, [Filter As String]) As Variant

### Parametry:

FolderName: Řetězec představující složku, která musí existovat. Tento argument nesmí označovat soubor.

Filter: Řetězec obsahující zástupné znaky ("?" nebo "*"), které se použijí na výsledný seznam souborů (výchozí = "").

### Příklad:

            Dim filesList As Variant, file As String
            FSO.FileNaming = "SYS"
            filesList = FSO.Files("/home/user/", "*.txt")
            For Each file In filesList
                ' ...
            Next file

## FolderExists

Vrátí True, pokud je zadaný název složky FolderName platný a složka existuje. V opačném případě metoda vrátí False.

Jestliže je parametr FolderName názvem existujícího souboru, metoda vrátí False.

### Syntaxe:

            FSO.FolderExists(FolderName As String) As Boolean

### Parametry:

FolderName: Řetězec představující složku, která se má otestovat.

### Příklad:

            FSO.FolderNaming = "SYS"
            If FSO.FolderExists("C:\Documents\Thesis") Then
                '...
            End If

## GetBaseName

Vrátí BaseName (poslední část) názvu složky nebo souboru bez přípony.

Metoda nekontroluje, zda zadaný soubor či složka existuje.

### Syntaxe:

            FSO.GetBaseName(FileName As String) As String

### Parametry:

FileName: Řetězec představující název souboru včetně cesty.

### Příklad:

            ' Je-li vstupním parametrem složka, vrátí se poslední část cesty
            MsgBox FSO.GetBaseName("/home/user/Documents") ' "Documents"
            ' Je-li vstupním parametrem soubor, vrátí se název souboru bez přípony a cesta
            MsgBox FSO.GetBaseName("/home/user/Documents/my_file.ods") ' "my_file"

## GetExtension

Vrátí z názvu souboru nebo složky část s příponou bez znaku tečky ".".

Metoda nekontroluje, zda zadaný soubor nebo složka existuje.

Použije-li se tato metoda na název složky nebo název souboru bez přípony, vrátí se prázdný řetězec.

### Syntaxe:

            FSO.GetExtension(FileName As String) As String

### Parametry:

FileName: Řetězec představující název souboru včetně cesty.

### Příklad:

            FSO.FileNaming = "SYS"
            MsgBox FSO.GetExtension("C:\Windows\Notepad.exe")  ' "exe"

## GetFileLen

Vestavěná funkce Basicu FileLen vrátí počet bajtů pro obsah souboru jako hodnotu typu Long, tj. maximálně 2 GB.

Metodou GetFileLen lze zpracovat značně větší soubory díky tomu, že se vrátí hodnoty typu Currency.

### Syntaxe:

            FSO.GetFileLen(FileName As String) As Currency

### Parametry:

FileName: Řetězec představující existující soubor.

### Příklad:

            Dim a As Currency
            FSO.FileNaming = "SYS"
            a = FSO.GetFileLen("C:\pagefile.sys")

## GetFileModified

Vrátí pro zadaný soubor datum poslední změny.

### Syntaxe:

            FSO.GetFileModified(FileName As String) As Date

### Parametry:

FileName: Řetězec představující existující soubor.

### Příklad:

            Dim a As Date
            FSO.FileNaming = "SYS"
            a = FSO.GetFileModified("C:\Documents\my_file.odt")

## GetName

Vrátí poslední část názvu souboru či složky v nativním formátu operačního systému.

Metoda nekontroluje, zda zadaný soubor či složka existuje.

### Syntaxe:

            FSO.GetName(FileName As String) As String

### Parametry:

FileName: Řetězec představující název souboru včetně cesty.

### Příklad:

            Dim a As String
            FSO.FileNaming = "SYS"
            a = FSO.GetName("C:\Windows\Notepad.exe"  ' Notepad.exe

## GetParentFolderName

Vrátí řetězec představující název rodičovské složky zadaného souboru nebo název složky.

Metoda nekontroluje, zda zadaný soubor či složka existuje.

### Syntaxe:

            FSO.GetParentFolderName(FileName As String) As String

### Parametry:

FileName: Řetězec s názvem analyzovaného souboru nebo složky.

### Příklad:

            Dim a As String
            FSO.FileNaming = "SYS"
            a = FSO.GetParentFolderName("C:\Windows\Notepad.exe"  ' C:\Windows\

## GetTempName

Vrátí náhodně generovaný název souboru, použitelný pro operace, které vyžadují dočasný soubor.

Vrácený název souboru neobsahuje příponu. Složka vráceného řetězce odpovídá systémové složce s dočasnými soubory.

Metoda dočasný soubor nevytvoří.

### Syntaxe:

            FSO.GetTempName() As String

### Příklad:

            Dim a As String
            FSO.FolderNaming = "SYS"
            a = FSO.GetTempName() & ".txt"
            ' "/tmp/SF_574068.txt"

## HashFile

Hashovací funkce se používají u některých kryptografických algoritmů, elektronických podpisů, autentizačních kódů, detekování podvodů, otisků (fingerprints), kontrolních součtů (kontrolách integrity zpráv), hashovacích tabulek, ukládání hesel apod.

Metoda HashFile vrátí výsledek hashovací funkce použité s daným algoritmem na zadaný soubor. Návratovou hodnotou je řetězec složený z malých šestnáctkových číslic.

Podporovanými hashovacími algoritmy jsou: MD5, SHA1, SHA224, SHA256, SHA384 a SHA512.

### Syntaxe:

            FSO.HashFile(FileName As String, Algorithm As String) As String

### Parametry:

FileName: Řetězec představující existující soubor.

Algorithm: Některý z podporovaných algoritmů.

### Příklad:

            FSO.FileNaming = "SYS"
            MsgBox FSO.HashFile("C:\pagefile.sys", "MD5")

## MoveFile

Přesune jeden či více souborů z jednoho umístění na jiné. Vrátí True, pokud byl přesunut alespoň jeden soubor, nebo False, nastane-li chyba.

K chybě dojde i tehdy, jestliže parametr Source používá zástupné znaky, které neodpovídají žádnému souboru.

Při výskytu chyby se metoda okamžitě ukončí. Přitom však nevrátí zpět žádné změny, které do té doby provede.

### Syntaxe:

            FSO.MoveFile(Source As String, Destination As String) As Boolean

### Parametry:

source: Jeden či více souborů, které se mají přesunout, zadané jako FileName nebo NamePattern.

Destination: Pokud je argument source zadán jako FileName, potom značí novou cestu a název přesunutého souboru.

Pokud se má přesunout více souborů, musí být argument Destination názvem složky. Jestliže tato složka neexistuje, vytvoří se.

Mají-li Source a Destination stejnou rodičovskou složku, metoda soubor argument Source přejmenuje.

V argumentu Destination nejsou povoleny zástupné znaky.

### Příklad:

            Dim a As String
            FSO.FileNaming = "SYS"
            FSO.MoveFile("C:\Temp1\*.*", "C:\Temp2\")
            ' Přesunou se pouze soubory, nikoliv podsložky

## MoveFolder

Přesune jednu či více složek z jednoho umístění na jiné. Vrátí True, pokud byla přesunuta alespoň jedna složka, nebo False, nastane-li chyba.

K chybě dojde i tehdy, jestliže parametr Source používá zástupné znaky, které neodpovídají žádné složce.

Při výskytu chyby se metoda okamžitě ukončí. Přitom však nevrátí zpět žádné změny, které do té doby provede.

### Syntaxe:

            FSO.MoveFolder(Source As String, Destination As String) As Boolean

### Parametry:

Source: Jedna či více složek, které se mají přesunout, zadané jako FolderName nebo NamePattern.

Destination: Pokud se má přesunout jediná složka, je argument Destination názvem a cestou přesunuté složky. Tato složka nesmí existovat.

Má-li se přesunout více složek, značí argument Destination umístění, na nějž se složky z argumentu Source přesunou. Pokud složka Destination neexistuje, vytvoří se.

V argumentu Destination nejsou povoleny zástupné znaky.

### Příklad:

            Dim a As String
            FSO.FileNaming = "SYS"
            FSO.MoveFolder("C:\Temp1\*", "C:\Temp2\")

## OpenTextFile

Otevře soubor a vrátí objekt TextStream, který lze použít pro čtení ze souboru, zápis do něj nebo zápis do něj v režimu přidávání.

Metoda nekontroluje, zda se jedná o textový soubor.

Nastane-li chyba, metoda vrátí objekt Null.

### Syntaxe:

            FSO.OpenTextFile(FileName As String, [IOMode As Integer], [Create As Boolean], [Encoding As String]) As Object

### Parametry:

FileName: Určuje soubor, který se má otevřít.

IOMode: Značí režim vstupu/výstupu. Může se jednat o některou ze tří konstant: FSO.ForReading (výchozí), FSO.ForWriting a FSO.ForAppending.

Create: Booleovská hodnota určující, zda může být vytvořen nový soubor, pokud zadaný název souboru neexistuje:

- Je-li True, nový soubor a jeho rodičovské složky se vytvoří.

- Je-li False, nové soubory se nevytvoří (výchozí).

Encoding: Znaková sada, která se má použít. Výchozím kódováním je "UTF-8".

### Příklad:

            Dim myFile As Object
            FSO.FileNaming = "SYS"
            Set myFile = FSO.OpenTextFile("C:\Temp\ThisFile.txt", FSO.ForReading)
            If Not IsNull(myFile) Then
                ' ...
            End If

## PickFile

Otevře dialogové okno pro otevření nebo uložení souborů.

Pokud je nastaven režim SAVE a vybraný soubor již existuje, zobrazí se zpráva s upozorněním.

### Syntaxe:

          FSO.PickFile([DefaultFile As String], [Mode As String], [Filter As String]) As String

### Parametry:

DefaultFile: Řetězec složený z názvu složky a souboru:

- Část se složkou určuje složku, která se zobrazí po otevření dialogového okna (výchozí = naposledy vybraná složka).

- Část se souborem značí výchozí soubor, který se má otevřít či uložit.

Mode: OPEN (vstupní soubor) or SAVE (výstupní soubor). Výchozí hodnotou je OPEN.

Filter: Přípona souborů zobrazených po otevření dialogového okna (výchozí = bez filtru).

### Příklad:

            Dim a As Variant
            FSO.FileNaming = "SYS"
            a = FSO.PickFile("C:\", "OPEN", "txt")
            ' Zobrazeny jsou pouze soubory *.txt

## PickFolder

Otevře dialogové okno pro výběr složky.

### Syntaxe:

            FSO.PickFolder([DefaultFolder As String], [FreeText As String]) As String

### Parametry:

DefaultFolder: Řetězec obsahující název složky zobrazené po otevření dialogového okna (výchozí = naposledy vybraná složka).

FreeText: Text zobrazený v okně (výchozí = "").

### Příklad:

            Dim a As Variant
            FSO.FileNaming = "SYS"
            a = FSO.PickFolder("C:\Dokumenty", "Zvolte složku nebo stiskněte Zrušit")

## SubFolders

Vrátí pole začínající od 0 se složkami uloženými na zadaném umístění FolderName.

Seznam může být filtrován pomocí zástupných znaků.

### Syntaxe:

            FSO.SubFolders(FolderName As String, [Filter As String]) As Variant

### Parametry:

FolderName: Řetězec představující složku, která musí existovat. Tento argument nesmí označovat soubor.

Filter: Řetězec obsahující zástupné znaky ("?" nebo "*"), které se použijí na výsledný seznam složek (výchozí = "").

### Příklad:

            Dim folderList As Variant, folder As String
            FSO.FileNaming = "SYS"
            folderList = FSO.SubFolders("/home/user/")
            For Each folder In folderList
                ' ...
            Next folder

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu.

Související témata

Služba ScriptForge.TextStream

Funkce Input

Příkaz Open