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:

note

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ů


tip

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.

tip

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(...)
    
note

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.

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.

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)
    
note

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:

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:

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
    
warning

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.