Serviço ScriptForge.FileSystem

O serviço FileSystem inclui rotinas para manusear arquivos e pastas. A seguir estão alguns exemplos do que pode ser feito com este serviço:

note

Os métodos do serviço FileSystem são baseados principalmente na interface UNO XSimpleFileAccess.


Definições

A tabela abaixo lista os principais parâmetros usados pela maior parte dos métodos do serviço FileSystem service.

Parâmetro

Descrição

FileName

Nome completo do arquivo incluindo o caminho sem o separador de pastas ao final.

FolderName

Nome completo da pasta incluindo o caminho. Pode ou não conter o caractere separador de pastas ao final.

Name

Último componente do Nome da Pasta ou Nome do Arquivo incluindo sua extensão. Este parâmetro é sempre expresso usando a notação nativa do sistema operacional em uso.

BaseName

Último componente do Nome da Pasta ou Nome do Arquivo sem sua extensão.

NamePattern

Qualquer um dos nomes acima contendo caracteres curinga em seu último componente. Os seguintes caracteres curinga são admitidos:

  • "?" representa qualquer caractere único

  • "*" representa zero, um ou múltiplos caracteres


tip

O serviço FileSystem permite executar operações em múltiplos arquivo ao mesmo tempo. Ao usar padrões de nomes, scripts pode copiar, mover ou apagar múltiplos arquivos. Por outro lado, métodos internos da linguagem Basic podem manipular apenas um arquivo de cada vez.


Notação de Nome de Arquivo

A notação usada para expressar nomes de arquivos e pastas, tanto para argumentos como para valores retornados, é definida pela propriedade FileNaming do serviço FileSystem.

Em suma, os possíveis tipos de representação são "URL" (notação de arquivo URL), "SYS" (notação do sistema operacional) e "ANY" (padrão). Veja mais informações abaixo.

tip

Um exemplo de notação URL é file:///C:/Documents/my_file.odt. Sempre que possível considere usar a notação URL por ser uma alternativa mais portável.


Invocação do serviço

Antes de usar o serviço FileSystem a biblioteca ScriptForge precisa ser carregada usando:


        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      

Os trechos de código abaixo invocam o serviço FileSystem. O método BuildPath foi usado como um exemplo.


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

Este serviço é totalmente compatível com as linguagens Basic e Python. Todos os exemplos são descritos usando a linguagem de programação Basic e podem ser facilmente convertidos para Python.


Propriedades

Nome

Somente leitura

Tipo

Descrição

FileNaming

Não

String

Define ou retorna a notação atual para arquivos e pastas, podendo ser "ANY", "URL" ou "SYS":

  • "ANY": (padrão) os métodos do serviço FileSystem aceitam tanto notação URL como a notação do sistema operacional em uso para argumentos de entrada, porém os valores de retorno sempre serão Strings URL.

  • "URL": os métodos do serviço FileSystem assumem que a notação URL será usada para argumentos de entrada e retornarão Strings URL.

  • "SYS": os métodos do serviço FileSystem assumirão que a notação do sistema operacional em uso será usada tanto para os argumentos de entrada como para os valores de retorno.

Uma vez definida, a propriedade FileNaming permanecerá inalterada até o final da sessão LibreOffice ou até que seja definida novamente.

ConfigFolder

Sim

String

Retorna a pasta de configuração do LibreOffice.

ExtensionsFolder

Sim

String

Retorna a pasta onde as extensões estão instaladas.

HomeFolder

Sim

String

Retorna a pasta do usuário.

InstallFolder

Sim

String

Retorna a pasta de instalação do LibreOffice.

TemplatesFolder

Sim

String

Retorna a pasta contendo os arquivos de modelos do sistema.

TemporaryFolder

Sim

String

Retorna a pasta de arquivos temporários definida nas configurações de caminho do LibreOffice.

UserTemplatesFolder

Sim

String

Retorna a pasta contendo os arquivos de modelos definidos pelo usuário.


Lista de Métodos no Serviço 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

Concatena um caminho para uma pasta e o nome de um arquivo e retorna o nome completo do arquivo com um separador de pastas válido. O separador de pastas é adicionado apenas se necessário.

Sintaxe:


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

Parâmetros:

FolderName: Caminho com o qual o parâmetro Name será combinado. O caminho específico não precisa ser uma pasta existente.

Name: Nome do arquivo a ser concatenado com o parâmetro FolderName. Este parâmetro usa a notação do sistema operacional em uso.

Exemplo:


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

CompareFiles

Compara dois arquivos e retorna True quando eles parecerem idênticos.

Dependendo do valor do parâmetro CompareContents, a comparação entre os dois arquivos pode ser baseada apenas nos atributos dos arquivos (tais como a última data de modificação), ou baseada nos conteúdos dos arquivos.

Sintaxe:


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

Parâmetros:

FileName1, FileName2: Arquivos a serem comparados.

CompareContents: Se True, os conteúdos dos arquivos são comparados (Padrão = False).

Exemplo:


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

CopyFile

Copia um ou mais arquivos de uma localização para outra. Retorna True se pelo menos um arquivo foi copiado, ou retorna False se um erro ocorreu.

Um erro também ocorrerá se o parâmetro Source usar caracteres curinga e não corresponder a arquivo algum.

O método é interrompido imediatamente se encontrar um erro. O método não é capaz de voltar atrás ou desfazer mudanças feitas antes da ocorrência do erro.

Sintaxe:


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

Parâmetros:

Source: Pode ser um nome de arquivo (FileName) ou um padrão de nomes (NamePattern) indicando um ou mais arquivos a serem copiados.

Destination: Pode ser um nome de arquivo (FileName) especificando onde o arquivo único especificado em Source deverá ser copiado, ou um nome de pasta (FolderName) dentro do qual os múltiplos arquivos definidos em Source serão copiados.

Overwrite: Se True (padrão), arquivos podem ser sobrescritos. O método falhará se Destination for somente leitura, independente do valor especificado para Overwrite.

Exemplo:


        FSO.FileNaming = "SYS"
        ' Copia um arquivo único
        FSO.CopyFile("C:\Documents\my_file.odt", "C:\Temp\copied_file.odt")
        ' Copia múltiplos arquivos. Apenas arquivos são copiados, subpastas não são copiadas.
        FSO.CopyFile("C:\Documents\*.*", "C:\Temp\", Overwrite := False)
    

CopyFolder

Copia uma ou mais pastas de uma localização para outra. Retorna True se pelo menos uma pasta foi copiada, ou retorna False se um erro ocorreu.

Um erro também ocorrerá se o parâmetro Source usar caracteres curinga e não corresponder a pasta alguma.

O método é interrompido imediatamente se encontrar um erro. O método não é capaz de voltar atrás ou desfazer mudanças feitas antes da ocorrência do erro.

Sintaxe:


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

Parâmetros:

Source: Pode ser um nome de pasta (FolderName) ou um padrão de nomes (NamePattern) indicando um ou mais pastas a serem copiadas.

Destination: Especifica o nome da pasta (FolderName) dentro da qual a pasta única ou múltiplas pastas definidas no parâmetro Source serão copiadas.

Overwrite: Se True (padrão), arquivos podem ser sobrescritos. O método falhará se Destination for somente leitura, independente do valor especificado para Overwrite.

Exemplo:


        FSO.FileNaming = "SYS"
        FSO.CopyFolder("C:\Documents\*", "C:\Temp\", Overwrite := False)
        ' Pastas, seus arquivos e subpastas são copiados
    

CreateFolder

Cria a pasta especificada em FolderName. Retorna True se a pasta pode ser criada com sucesso.

Se a pasta especificada tem uma pasta pai que não existe, então ela é criada.

Sintaxe:


        FSO.CreateFolder(FolderName As String) As Boolean
    

Parâmetros:

FolderName: String representando a pasta a ser criada. Se a pasta já existe, então uma exceção é lançada.

Exemplo:


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

CreateTextFile

Cria o arquivo especificado e retorna um objeto TextStream que pode ser usado para escrever no arquivo.

O método retorna um objeto Null se um erro ocorreu.

Sintaxe:


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

Parâmetros:

FileName: Nome do arquivo a ser criado.

Overwrite: Valor booleano que determina se FileName pode ser sobrescrito (padrão = True).

Encoding: Codificação de caracteres a ser usado. O padrão é "UTF-8".

Exemplo:


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

Para saber mais sobre os nomes dos conjuntos de codificação de caracteres, visite a página IANA's Character Set. Note que o LibreOffice não implementa todas as codificações existentes.


DeleteFile

Apaga um ou mais arquivos. Retorna True se ao menos um arquivo pode ser apagado ou False se um erro ocorreu.

Um erro também ocorrerá se o parâmetro FileName usar caracteres curinga e não corresponder a arquivo algum.

Os arquivos a serem apagados não podem ser somente leitura.

O método é interrompido imediatamente se encontrar um erro. O método não é capaz de voltar atrás ou desfazer mudanças feitas antes da ocorrência do erro.

Sintaxe:


        FSO.DeleteFile(FileName As String) As Boolean
    

Parâmetros:

FileName: Pode ser um nome de arquivo (FileName) ou um padrão de nomes (NamePattern) indicando um ou mais arquivos a serem apagados.

Exemplo:


        FSO.FileNaming = "SYS"
        FSO.DeleteFile("C:\Temp\*.docx")
        ' Apenas arquivos são apagados, subpastas não são apagadas
    

DeleteFolder

Apaga uma ou mais pastas. Retorna True se ao menos uma pasta foi apagada ou False se um erro ocorreu.

Um erro também ocorrerá se o parâmetro FolderName usar caracteres curinga e não corresponder a pasta alguma.

As pastas a serem apagadas não podem ser somente leitura.

O método é interrompido imediatamente se encontrar um erro. O método não é capaz de voltar atrás ou desfazer mudanças feitas antes da ocorrência do erro.

Sintaxe:


        FSO.DeleteFolder(FolderName As String) As Boolean
    

Parâmetros:

FolderName: Pode ser um nome de pasta (FolderName) ou um padrão de nomes (NamePattern) indicando uma ou mais pastas a serem apagadas.

Exemplo:


        FSO.FileNaming = "SYS"
        FSO.DeleteFolder("C:\Temp\*")
        ' Apenas pastas são apagadas; arquivos na pasta C:\Temp não são apagados
    

FileExists

Retorna True se um dado nome de arquivo é válido e existe, caso contrário o método retorna False.

Se o parâmetro FileName for na verdade um nome de pasta existente, o método retorna False.

Sintaxe:


        FSO.FileExists(FileName As String) As Boolean
    

Parâmetros:

FileName: String representando o arquivo a ser testado.

Exemplo:


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

Files

Retorna um Array indexado em zero com os arquivos armazenados em uma pasta. Cada entrada no Array é uma String contendo o caminho completo e o nome do arquivo.

Se FolderName não existir, uma exceção é lançada.

A lista resultante pode ser filtrada com caracteres curinga.

Sintaxe:


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

Parâmetros:

FolderName: String representando uma pasta. A pasta deve existir. FolderName não pode designar um arquivo.

Filter: String contendo caracteres curinga ("?" e "*") que serão aplicados à lista de arquivos resultante (Padrão = "").

Exemplo:


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

FolderExists

Retorna True se o nome de pasta especificado em FolderName é válido e existe, caso contrário o método retorna False.

Se o parâmetro FolderName for na verdade um nome de arquivo existente, o método retorna False.

Sintaxe:


        FSO.FolderExists(FolderName As String) As Boolean
    

Parâmetros:

FolderName: String representando a pasta a ser testada.

Exemplo:


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

GetBaseName

Retorna o BaseName (igual ao último componente) de uma pasta ou nome de arquivo, seu sua extensão.

O método não verifica se a pasta ou arquivo especificado existe.

Sintaxe:


        FSO.GetBaseName(FileName As String) As String
    

Parâmetros:

FileName: String representando o nome do arquivo e seu caminho.

Exemplo:


        ' Se o parâmetro de entrada é uma pasta, retorna o último componente do caminho
        MsgBox FSO.GetBaseName("/home/user/Documents") ' "Documents"
        ' Se o parâmetro de entrada é um arquivo, o método retorna o nome do arquivo sem a extensão e o caminho
        MsgBox FSO.GetBaseName("/home/user/Documents/my_file.ods") ' "my_file"
    

GetExtension

Retorna a extensão de um nome de arquivo ou pasta sem o caractere "." ponto.

O método não verifica a existência da pasta ou arquivo especificado.

Se o método for aplicado a uma pasta ou arquivo que não possui extensão, então uma String vazia é retornada.

Sintaxe:


        FSO.GetExtension(FileName As String) As String
    

Parâmetros:

FileName: String representando o nome do arquivo e seu caminho.

Exemplo:


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

GetFileLen

A função interna Basic FileLen retorna o número de bytes contidos em um arquivo como um valor do tipo Long, ou seja, com até 2GB.

O método GetFileLen consegue manipular arquivos com tamanhos maiores pois retorna um valor do tipo Currency.

Sintaxe:


        FSO.GetFileLen(FileName As String) As Currency
    

Parâmetros:

FileName: String representando um arquivo existente.

Exemplo:


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

GetFileModified

Retorna a última data de modificação de um dado arquivo.

Sintaxe:


        FSO.GetFileModified(FileName As String) As Date
    

Parâmetros:

FileName: String representando um arquivo existente.

Exemplo:


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

GetName

Retorna o último componente de um arquivo ou pasta usando o formato nativo do sistema operacional em uso.

O método não verifica se a pasta ou arquivo especificado existe.

Sintaxe:


        FSO.GetName(FileName As String) As String
    

Parâmetros:

FileName: String representando o nome do arquivo e seu caminho.

Exemplo:


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

GetParentFolderName

Retorna uma String contendo o nome da pasta pai de um dado nome de arquivo ou pasta.

O método não verifica se a pasta ou arquivo especificado existe.

Sintaxe:


        FSO.GetParentFolderName(FileName As String) As String
    

Parâmetros:

FileName: String com o nome do arquivo ou pasta a ser analisado.

Exemplo:


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

GetTempName

Retorna um nome de arquivo temporário gerado aleatoriamente que pode ser útil para executar operações que requerem arquivos temporários.

O nome do arquivo retornado não possui sufixo. A parte contendo o nome da pasta corresponde à pasta temporária do sistema.

O método não cria o arquivo temporário.

Sintaxe:


        FSO.GetTempName() As String
    

Exemplo:


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

HashFile

Funções hash são usadas por alguns algoritmos criptográficos, em assinaturas digitais, códigos de autenticação de mensagens, detecção de fraudes, impressões digitais, verificação de integridade de mensagens, tabelas hash, armazenamento de senhas e muito mais.

O método HashFile retorna o resultado da função hash aplicada em um dado arquivo usando o algoritmo escolhido. O valor retornado é uma String com caracteres hexadecimais minúsculos.

Os algoritmos hash suportados são: MD5, SHA1, SHA224, SHA256, SHA384 e SHA512.

Sintaxe:


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

Parâmetros:

FileName: String representando um arquivo existente.

Algorithm: Um dos algoritmos suportados.

Exemplo:


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

MoveFile

Move um ou mais arquivos de uma localização para outra. Retorna True se pelo menos um arquivo foi movido, ou retorna False se um erro ocorreu.

Um erro também ocorrerá se o parâmetro Source usar caracteres curinga e não corresponder a arquivo algum.

O método é interrompido imediatamente se encontrar um erro. O método não é capaz de voltar atrás ou desfazer mudanças feitas antes da ocorrência do erro.

Sintaxe:


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

Parâmetros:

Source: Pode ser um nome de arquivo (FileName) ou um padrão de nomes (NamePattern) indicando um ou mais arquivos a serem movidas.

Destination: Se Source for um nome de arquivo (FileName) então este parâmetro indica o novo caminho e nome do arquivo que foi movido.

Se a operação de movimentação envolver múltiplos arquivos, então o parâmetro Destination deve ser um nome de pasta. Se a pasta não existir, ela será criada.

Se Source e Destination possuírem a mesma pasta pai, o método renomeará Source.

Caracteres curinga não são permitidos no parâmetro Destination.

Exemplo:


        Dim a As String
        FSO.FileNaming = "SYS"
        FSO.MoveFile("C:\Temp1\*.*", "C:\Temp2\")
        ' Apenas arquivos são movidos, subpastas não são movidas
    

MoveFolder

Move uma ou mais pastas de uma localização para outra. Retorna True se pelo menos uma pasta foi movida, ou retorna False se um erro ocorreu.

Um erro também ocorrerá se o parâmetro Source usar caracteres curinga e não corresponder a pasta alguma.

O método é interrompido imediatamente se encontrar um erro. O método não é capaz de voltar atrás ou desfazer mudanças feitas antes da ocorrência do erro.

Sintaxe:


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

Parâmetros:

Source: Pode ser um nome de pasta (FolderName) ou um padrão de nomes (NamePattern) indicando uma ou mais pastas a serem movidas.

Destination: Se a operação de movimentação envolver uma pasta única, então o parâmetro Destination será considerado como o nome e caminho da pasta movida, portanto não deve existir.

Se múltiplas pastas estão sendo movidas, então Destination define para onde as pastas em Source serão movidas. Se a pasta Destination não existir, ela é criada.

Caracteres curinga não são permitidos no parâmetro Destination.

Exemplo:


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

OpenTextFile

Abre um arquivo e retorna um objeto TextStream que pode ser usado para ler, escrever ou acrescentar valores a um arquivo de texto.

Note que o método não verifica se um dado arquivo é realmente um arquivo texto.

O método retorna um objeto Null se um erro ocorreu.

Sintaxe:


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

Parâmetros:

FileName: Especifica o arquivo a ser aberto.

IOMode: Indica o modo de entrada e saída. Pode ser uma de três constantes: FSO.ForReading (padrão), FSO.ForWriting, ou FSO.ForAppending.

Create: Valor booleano que indica se um novo arquivo pode ser criado se o nome de arquivo especificado não existir:

Encoding: Codificação de caracteres a ser usado. O padrão é "UTF-8".

Exemplo:


        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

Mostra uma caixa de diálogo para abrir ou salvar arquivos.

Se o modo SAVE estiver definido e o arquivo escolhido existir, um alerta será apresentado.

Sintaxe:


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

Parâmetros:

DefaultFile: Este argumento é uma String composta por um nome de pasta e arquivo:

Mode: OPEN (arquivo de entrada) ou SAVE (arquivo de saída). O valor padrão é OPEN.

Filter: Usado para definir a extensão dos arquivos mostrados quando o diálogo é aberto (padrão = sem filtro).

Exemplo:


        Dim a As Variant
        FSO.FileNaming = "SYS"
        a = FSO.PickFile("C:\", "OPEN", "txt")
        ' Apenas arquivos *.txt são mostrados
    

PickFolder

Abre uma caixa de diálogo para escolher uma pasta

Sintaxe:


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

Parâmetros:

DefaultFolder: String contendo o nome da pasta que será apresentada quando a caixa de diálogo for aberta (padrão = última pasta selecionada).

FreeText: Texto a ser mostrado na caixa de diálogo (Padrão = "").

Exemplo:


        Dim a As Variant
        FSO.FileNaming = "SYS"
        a = FSO.PickFolder("C:\", "Escolha uma pasta ou clique em Cancelar")
    

SubFolders

Retorna um Array indexado em zero com as pastas armazenadas em um dado FolderName.

A lista pode ser filtrada usando caracteres curinga.

Sintaxe:


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

Parâmetros:

FolderName: String representando uma pasta. A pasta deve existir. FolderName não pode designar um arquivo.

Filter: String contendo caracteres curinga ("?" e "*") que serão aplicados à lista de pastas resultante (Padrão = "").

Exemplo:


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

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.


♥ Doe para nosso projeto! ♥