Servizio ScriptForge.FileSystem

Il servizio FileSystem comprende routine per gestire i file e le cartelle. Di seguito sono riportati alcuni esempi delle funzionalità fornite da questo servizio:

note

I metodi del servizio FileSystem si basano principalmente sull'interfaccia XSimpleFileAccess di UNO.


Definizioni

La tabella sottostante elenca i principali parametri usati dalla maggior parte dei metodi del servizio FileSystem.

Parametro

Descrizione

FileName

Il nome completo del file, compreso il percorso e senza il carattere di separazione delle cartelle alla fine.

FolderName

Il nome completo della cartella, incluso il percorso. Può terminare con o senza il carattere di separazione delle cartelle.

Name

L'ultimo componente del nome della cartella (Folder Name) o del nome del file (File Name) compresa la sua estensione. Questo parametro viene sempre espresso usando il formato nativo del sistema operativo.

BaseName

L'ultimo componente del nome della cartella (Folder Name) o del nome del file (File Name) esclusa la sua estensione.

NamePattern

Qualsiasi nome di cui sopra contenente dei caratteri jolly come ultimo componente. I caratteri jolly ammessi sono:

  • "?" rappresenta un singolo carattere qualsiasi

  • "*" rappresenta nessuno, uno o più caratteri


tip

Il servizio FileSystem permette di eseguire operazioni su più file contemporaneamente. Usando modelli di nome, gli script dell'utente possono copiare, spostare o eliminare più file. Al contrario, i metodi incorporati in Basic possono gestire solamente singoli file.


Notazione dei nomi dei file

La notazione usata per esprimere i nomi dei file e delle cartelle, sia negli argomenti, sia nei valori restituiti, è definita dalla proprietà FileNaming del servizio FileSystem.

In breve, i possibili tipi di rappresentazione sono: "URL" (notazione dell'URL del file), "SYS" (notazione del sistema operativo) e "ANY" (predefinita). Per maggiori informazioni vedere la tabella seguente.

tip

Un esempio di notazione URL è file:///C:/Documents/my_file.odt. Considerate di utilizzare la notazione URL ogni qualvolta ciò sia possibile, in quanto è un'alternativa più versatile.


Invocare il servizio

Prima di usare il servizio FileSystem è necessario caricare la libreria ScriptForge usando:


        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      

Il seguente frammento di codice invoca il servizio FileSystem. Il metodo BuildPath è stato usato come esempio.


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

Questo servizio è pienamente supportato sia in Basic, sia in Python. Tutti gli esempi sono espressi nel linguaggio di programmazione Basic e possono essere facilmente convertiti in Python.


Proprietà

Nome

Sola lettura

Tipo

Descrizione

FileNaming

No

String

Imposta o restituisce la notazione corrente per i file e le cartelle, che sia "ANY", "URL" o "SYS":

  • "ANY": (predefinita) i metodi del servizio FileSystem accettano per gli argomenti inseriti sia la notazione URL, sia quella del sistema operativo in uso, ma restituiscono sempre stringhe in formato URL.

  • "URL": i metodi del servizio FileSystem si aspettano di ricevere gli argomenti nella notazione URL e restituiscono stringhe nel formato URL.

  • "SYS": i metodi del servizio FileSystem si aspettano la notazione del sistema operativo in uso sia per gli argomenti inseriti, sia per le stringhe che restituiscono.

Una volta impostata, la proprietà FileNaming rimane immutata fino alla fine della sessione di LibreOffice o fino a che viene reimpostata.

ConfigFolder

Sì

String

Restituisce la cartella della configurazione di LibreOffice.

ExtensionsFolder

Sì

String

Restituisce la cartella in cui sono installate le estensioni.

HomeFolder

Sì

String

Restituisce la cartella personale dell'utente.

InstallFolder

Sì

String

Restituisce la cartella in cui è installato LibreOffice.

TemplatesFolder

Sì

String

Restituisce la cartella che contiene i file dei modelli di sistema.

TemporaryFolder

Sì

String

Restituisce la cartella dei file temporanei definita nelle impostazioni dei percorsi di LibreOffice.

UserTemplatesFolder

Sì

String

Restituisce la cartella contenente i file dei modelli definiti dall'utente.


Elenco dei metodi del servizio 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

Unisce il percorso di una cartella al nome di un file e restituisce il nome del file completo usando un carattere di separazione delle cartelle valido. Il carattere di separazione delle cartelle è aggiunto solo se necessario.

Sintassi:


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

Parametri:

FolderName: il percorso con cui verrà combinato il nome del file (Name). Non è necessario che il percorso specificato sia quello di una cartella esistente.

Name: il nome del file da aggiungere al percorso FolderName. Questo parametro usa la notazione del sistema operativo corrente.

Esempio:


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

CompareFiles

Confronta due file e restituisce True se sembrano identici.

A seconda del valore dell'argomento CompareContents, il confronto tra i file può essere basato solo sui rispettivi attributi (come la data dell'ultima modifica), o anche sul loro contenuto.

Sintassi:


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

Parametri:

FileName1, FileName2: i file da confrontare.

CompareContents: se è True, viene confrontato il contenuto dei file (predefinito = False).

Esempio:


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

CopyFile

Copia uno o più file da una posizione a un'altra. Restituisce True se almeno un file è stato copiato o False se si è verificato un errore.

Un errore si verifica anche quando il parametro Source fa uso di caratteri jolly e non individua alcun file.

Il metodo si interrompe immediatamente dopo aver incontrato un errore. Il metodo non ritorna al punto di partenza e non annulla le modifiche fatte prima di incontrare l'errore.

Sintassi:


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

Parametri:

Source: può essere un FileName o un NamePattern che indica uno o più file da copiare.

Destination: può essere sia un FileName che specifica dove il singolo file Source deve essere copiato, sia il nome di una cartella (FolderName) in cui copiare i diversi file indicati in Source.

Overwrite: se è True (predefinito), i file possono essere sovrascritti. Il metodo fallisce se la destinazione (Destination) è di sola lettura, indipendentemente dal valore specificato in Overwrite.

Esempio:


        FSO.FileNaming = "SYS"
        'Copia un singolo file
        FSO.CopyFile("C:\Documents\my_file.odt", "C:\Temp\copied_file.odt")
        'Copia più file. Solo i file vengono copiati, non le sottocartelle.
        FSO.CopyFile("C:\Documents\*.*", "C:\Temp\", Overwrite := False)
    

CopyFolder

Copia una o più cartelle da una posizione a un'altra. Restituisce True se almeno una cartella è stata copiata o False se si è verificato un errore.

Un errore si verifica anche se il parametro Source usa dei caratteri jolly e non individua alcuna cartella.

Il metodo si interrompe immediatamente dopo aver incontrato un errore. Il metodo non ritorna al punto di partenza e non annulla le modifiche effettuate prima di incontrare l'errore.

Sintassi:


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

Parametri:

Source: può essere il nome di una cartella (FolderName) o un NamePattern che individua una o più cartelle da copiare.

Destination: specifica il nome della cartella (FolderName) in cui copiare la singola cartella o le varie cartelle definite in Source.

Overwrite: Se è True (predefinito), i file possono essere sovrascritti. Il metodo fallisce se la destinazione (Destination) è di sola lettura, indipendentemente dal valore specificato in Overwrite.

Esempio:


        FSO.FileNaming = "SYS"
        FSO.CopyFolder("C:\Documents\*", "C:\Temp\", Overwrite := False)
        'Vengono copiate le cartelle, i file e le sottocartelle in esse contenuti
    

CreateFolder

Crea la cartella specificata in FolderName. Restituisce True se la cartella può essere creata correttamente.

Se la cartella specificata ha una cartella genitore che non esiste, questa viene creata.

Sintassi:


        FSO.CreateFolder(FolderName As String) As Boolean
    

Parametri:

FolderName: una stringa che rappresenta la cartella da creare. Se la cartella esiste già, viene sollevata un'eccezione.

Esempio:


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

CreateTextFile

Crea il file specificato e restituisce un oggetto TextStream che può essere usato per scrivere nel file.

Il metodo restituisce un oggetto Null se si verifica un errore.

Sintassi:


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

Parametri:

FileName: il nome del file da creare.

Overwrite: un valore booleano che determina se il file FileName può essere sovrascritto (predefinito = True).

Encoding: la codifica caratteri da usare. La codifica predefinita è "UTF-8".

Esempio:


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

Per saperne di più in merito ai nomi delle codifiche dei caratteri, visitate la pagina Codifiche dei caratteri IANA. Fate attenzione che LibreOffice non implementa tutte le codifiche dei caratteri esistenti.


DeleteFile

Elimina uno o più file. Restituisce True se almeno un file è stato eliminato o False se si verifica un errore.

Un errore si verifica anche quando il parametro FileName fa uso di caratteri jolly e non corrisponde ad alcun file.

I file da eliminare non devono essere di sola lettura.

Il metodo si interrompe immediatamente dopo aver rilevato un errore. Il metodo non ritorna al punto di partenza e non annulla le modifiche effettuate prima della comparsa dell'errore.

Sintassi:


        FSO.DeleteFile(FileName As String) As Boolean
    

Parametri:

FileName: può essere il nome di un file (FileName) o un NamePattern che indica uno o più file da eliminare.

Esempio:


        FSO.FileNaming = "SYS"
        FSO.DeleteFile("C:\Temp\*.docx")
        'Vengono cancellati solo i file, non le sottocartelle
    

DeleteFolder

Elimina una o più cartelle. Restituisce True se almeno una cartella è stata eliminata o False se si verifica un errore.

Un errore si verifica anche quando il parametro FolderName fa uso di caratteri jolly e non individua ad alcuna cartella.

Le cartelle da eliminare non devono essere di sola lettura.

Il metodo si interrompe immediatamente dopo aver rilevato un errore. Il metodo non ritorna al punto di partenza e non annulla le modifiche effettuate prima della comparsa dell'errore.

Sintassi:


        FSO.DeleteFolder(FolderName As String) As Boolean
    

Parametri:

FolderName: può essere il nome di una cartella (FolderName) o un NamePattern che indica una o più cartelle da eliminare.

Esempio:


        FSO.FileNaming = "SYS"
        FSO.DeleteFolder("C:\Temp\*")
        'Solo le cartelle vengono eliminate, non i file nella cartella superiore (C:\Temp\)
    

FileExists

Restituisce True se un determinato nome di file è valido ed esistente, altrimenti il metodo restituisce False.

Se il parametro FileName è in realtà il nome di una cartella, il metodo restituisce False.

Sintassi:


        FSO.FileExists(FileName As String) As Boolean
    

Parametri:

FileName: una stringa che rappresenta il file da verificare.

Esempio:


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

Files

Restituisce una matrice, con indice a partire da zero, dei file memorizzati in una determinata cartella. Ogni voce della matrice è una stringa che comprende l'intero percorso e il nome del file.

Se la cartella (FolderName) non esiste, viene sollevata un'eccezione.

L'elenco risultante può essere filtrato usando dei caratteri jolly.

Sintassi:


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

Parametri:

FolderName: una stringa che rappresenta una cartella. La cartella deve esistere. FolderName non deve indicare un file.

Filter: una stringa contenente caratteri jolly ("?" e "*") da applicare all'elenco di file risultante (predefinito = "").

Esempio:


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

FolderExists

Restituisce True se la cartella specificata in FolderName è valida ed esistente, altrimenti il metodo restituisce False.

Se il parametro FolderName corrisponde effettivamente al nome di un file esistente, il metodo restituisce False.

Sintassi:


        FSO.FolderExists(FolderName As String) As Boolean
    

Parametri:

FolderName: una stringa che rappresenta la cartella da verificare.

Esempio:


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

GetBaseName

Restituisce il parametro BaseName (corrispondente all'ultimo componente) del nome di una cartella o di un file, senza estensione.

Il metodo non controlla se il file o la cartella specificata esiste.

Sintassi:


        FSO.GetBaseName(FileName As String) As String
    

Parametri:

FileName: una stringa che rappresenta il nome del file ed il suo percorso.

Esempio:


        'Se il parametro inserito è una cartella, restituisce l'ultimo componente del percorso
        MsgBox FSO.GetBaseName("/home/user/Documents") ' "Documents"
        'Se il parametro inserito è un file, il metodo restituisce il nome del file senza l'estensione e il percorso
        MsgBox FSO.GetBaseName("/home/user/Documents/my_file.ods") ' "my_file"
    

GetExtension

Restituisce la parte relativa all'estensione dal nome di un file o di una cartella, senza il carattere del punto ".".

Il metodo non controlla l'esistenza del file o della cartella indicata.

Se questo metodo viene applicato al nome di una cartella o ad un file privo di estensione verrà restituita una stringa vuota.

Sintassi:


        FSO.GetExtension(FileName As String) As String
    

Parametri:

FileName: una stringa che rappresenta il nome del file e il suo percorso.

Esempio:


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

GetFileLen

La funzione FileLen incorporata in Basic restituisce il numero di byte contenuti in un file come valore di tipo Long, cioè fino a 2GB.

Il metodo GetFileLen può gestire file di dimensioni molto più grandi restituendo un valore di tipo Currency.

Sintassi:


        FSO.GetFileLen(FileName As String) As Currency
    

Parametri:

FileName: una stringa che rappresenta un file esistente.

Esempio:


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

GetFileModified

Restituisce la data dell'ultima modifica ad un determinato file.

Sintassi:


        FSO.GetFileModified(FileName As String) As Date
    

Parametri:

FileName: una stringa che rappresenta un file esistente.

Esempio:


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

GetName

Restituisce l'ultimo componente del nome di un file o di una cartella nel formato nativo del sistema operativo.

Il metodo non controlla se il file o la cartella specificata esiste.

Sintassi:


        FSO.GetName(FileName As String) As String
    

Parametri:

FileName: una stringa che rappresenta il nome del file e il suo percorso.

Esempio:


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

GetParentFolderName

Restituisce una stringa contenente il nome della cartella padre di un file o di una cartella specificata.

Il metodo non controlla se il file o la cartella specificata esiste.

Sintassi:


        FSO.GetParentFolderName(FileName As String) As String
    

Parametri:

FileName: una stringa con il nome del file o della cartella da analizzare.

Esempio:


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

GetTempName

Restituisce un nome di file temporaneo generato in modo casuale e utile per eseguire operazioni che richiedono un file temporaneo.

Il nome di file restituito non ha alcun suffisso. Nella stringa restituita, la parte relativa al percorso è la cartella di sistema dei file temporanei.

Il metodo non crea il file temporaneo.

Sintassi:


        FSO.GetTempName() As String
    

Esempio:


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

HashFile

Le funzioni di hash sono usate da alcuni algoritmi crittografici, nelle firme digitali, nei codici di autenticazione dei messaggi, nel rilevamento delle frodi, nelle impronte digitali, nei checksum (controllo di integrità dei messaggi), nelle tabelle di hash, nell'archiviazione delle password e molto altro.

Il metodo HashFile restituisce il risultato di una funzione di hash applicata ad un determinato file usando un algoritmo specificato. Il valore restituito è una stringa di cifre esadecimali con le lettere in minuscolo.

Gli algoritmi di hash supportati sono: MD5, SHA1, SHA224, SHA256, SHA384 e SHA512.

Sintassi:


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

Parametri:

FileName: una stringa che rappresenta un file esistente.

Algorithm: uno degli algoritmi supportati.

Esempio:


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

MoveFile

Sposta uno o più file da una posizione ad un'altra. Restituisce True se almeno un file è stato spostato o False se si verifica un errore.

Si verifica un errore anche quando il parametro Source fa uso di caratteri jolly e non corrisponde ad alcun file.

Il metodo si interrompe immediatamente dopo aver rilevato un errore. Il metodo non ritorna al punto di partenza e non annulla le modifiche effettuate prima della comparsa dell'errore.

Sintassi:


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

Parametri:

Source: può essere un nome di file (FileName) o o un NamePattern che individua uno o più file da spostare.

Destination: Se Source è un nome di file (FileName) allora questo parametro indica il nuovo percorso ed il nome del file spostato.

Se l'operazione di spostamento coinvolge più file, allora Destination deve essere un nome di cartella. Se non esiste, viene creata.

Se Source e Destination condividono la stessa cartella di origine, il metodo rinominerà Source.

I caratteri jolly non sono permessi nella destinazione (Destination).

Esempio:


        Dim a As String
        FSO.FileNaming = "SYS"
        FSO.MoveFile("C:\Temp1\*.*", "C:\Temp2\")
        'Vengono spostati solo i file, non le sottocartelle
    

MoveFolder

Sposta una o più cartelle da una posizione ad un'altra. Restituisce True se almeno una cartella è stata spostata o False se si verifica un errore.

Si verifica un errore anche se il parametro Source usa dei caratteri jolly e non trova corrispondenze con alcuna cartella.

Il metodo si interrompe immediatamente dopo aver rilevato un errore. Il metodo non ritorna al punto di partenza e non annulla le modifiche effettuate prima della comparsa dell'errore.

Sintassi:


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

Parametri:

Source: può essere il nome di una cartella (FolderName) o un NamePattern che individua una o più cartelle da spostare.

Destination: se l'operazione di spostamento riguarda una singola cartella, allora Destination è il nome e il percorso del file spostato e non deve essere già esistente.

Se si spostano più cartelle, allora Destination indica dove saranno spostate le cartelle presenti in Source. Se la cartella Destination non esiste, viene creata.

I caratteri jolly non sono permessi nella destinazione (Destination).

Esempio:


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

OpenTextFile

Apre un file e restituisce un oggetto TextStream che può essere usato per leggere, scrivere o apportare aggiunte al file.

Fate attenzione che il metodo non controlla se il file indicato è effettivamente un file di testo.

Il metodo restituisce un oggetto Null se si verifica un errore.

Sintassi:


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

Parametri:

FileName: identifica il file da aprire.

IOMode: indica la modalità di input/output. Può essere una delle tre costanti: FSO.ForReading (predefinita), FSO.ForWriting o FSO.ForAppending.

Create: valore logico (booleano) che indica se può essere creato un nuovo file nel caso in cui il nome del file specificato non esista:

Encoding: la codifica caratteri da usare. La codifica predefinita è "UTF-8".

Esempio:


        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

Apre una finestra di dialogo per aprire o salvare file.

Se è impostata la modalità SAVE e il file selezionato esiste, sarà visualizzato un messaggio di avvertimento.

Sintassi:


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

Parametri:

DefaultFile: questo argomento è una stringa composta dal nome di una cartella e di un file:

Mode: OPEN (file da aprire) o SAVE (file da salvare). Il valore predefinito è OPEN.

Filter: l'estensione dei file visualizzati nella finestra di dialogo quando è aperta (predefinito = nessun filtro).

Esempio:


        Dim a As Variant
        FSO.FileNaming = "SYS"
        a = FSO.PickFile("C:\", "OPEN", "txt")
        'Vengono visualizzati solo i file *.txt
    

PickFolder

Apre una finestra di dialogo per selezionare una cartella.

Sintassi:


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

Parametri:

DefaultFolder: una stringa che contiene il nome della cartella che sarà visualizzata all'apertura della finestra di dialogo (predefinita = l'ultima cartella selezionata).

FreeText: il testo da visualizzare nella finestra di dialogo (predefinito = "").

Esempio:


        Dim a As Variant
        FSO.FileNaming = "SYS"
        a = FSO.PickFolder("C:\", "Seleziona una cartella o premi Annulla")
    

SubFolders

Restituisce una matrice con indice a partire da zero delle cartelle memorizzate in una determinata cartella (FolderName).

L'elenco può essere filtrato con i caratteri jolly.

Sintassi:


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

Parametri:

FolderName: una stringa che rappresenta una cartella. È necessario che la cartella esista. FolderName non deve indicare un file.

Filter: una stringa contenente i caratteri jolly ("?" e "*") che sarà applicata all'elenco di cartelle risultante (predefinito = "").

Esempio:


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

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic.


Sosteneteci!