Serviço ScriptForge.FileSystem

Conteúdo

# ScriptForge.FileSystem serviço

O serviço FileSystem inclui rotinas para gerir ficheiros e pastas. Seguem-se alguns exemplos das funcionalidades disponibilizadas por este serviço:

- Verificar se um ficheiro ou pasta existe.

- Criar e eliminar pastas e ficheiros.

- Abrir caixas de diálogo para abrir/guardar ficheiros.

- Aceder à lista de ficheiros numa pasta, etc.

Os métodos do serviço FileSystem baseiam-se, na sua maioria, na interface UNO XSimpleFileAccess.

## Definições

A tabela abaixo apresenta os principais parâmetros utilizados pela maioria dos métodos do serviço FileSystem.

Parâmetros | Descrição
--- | ---
FileName | O nome completo do ficheiro, incluindo o caminho, sem um separador de caminho no final.
FolderName | O nome completo da pasta, incluindo o caminho. Pode ou não conter o separador de fim de caminho.
Name | O último componente do Nome da pasta ou Nome do ficheiro, incluindo a sua extensão. Este parâmetro é sempre expresso utilizando o formato nativo do sistema operativo.
BaseName | O último componente do Nome da pasta ou do Nome do ficheiro, sem a extensão.
NamePattern | Qualquer um dos nomes acima que contenha caracteres curinga no seu último componente. Os caracteres curinga permitidos são: "?" representa qualquer carácter único "*" representa zero, um ou vários caracteres

O serviço FileSystem permite realizar operações em vários ficheiros ao mesmo tempo. Através da utilização de padrões de nomes, os scripts do utilizador podem copiar, mover ou eliminar vários ficheiros. Por outro lado, os métodos integrados do Basic só conseguem lidar com ficheiros individuais.

### Notação para a denominação de ficheiros

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

Em resumo, os tipos de representação possíveis são «URL» (notação de ficheiro URL), «SYS» (notação do sistema operativo) e «ANY» (predefinição). Consulte mais informações abaixo.

Um exemplo da notação URL é file:///C:/Documents/my_file.odt. Sempre que possível, considere utilizar a notação URL, pois é uma alternativa mais portátil.

A utilização do atalho «~» (tilde), comum em sistemas operativos baseados em Linux, não é suportada para indicar o caminho para uma pasta e o nome de um ficheiro. Em vez de utilizar «~/Documents/my_file.odt», utilize o caminho completo «/home/user/Documents/my_file.odt».

## Chamada de serviço

O seguinte fragmento de código invoca o serviço FileSystem. O método BuildPath foi utilizado como exemplo.

##### Em Basic

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim FSO As Object
          Set FSO = CreateScriptService("FileSystem")
          FSO.BuildPath(...)

##### Em Python

          from scriptforge import CreateScriptService
          fs = CreateScriptService("FileSystem")
          fs.BuildPath(...)

## Aceder ao sistema de ficheiros virtual de um documento

Os ficheiros LibreOffice são ficheiros ZIP comprimidos que contêm os ficheiros e pastas que representam o conteúdo real do documento. Enquanto o documento estiver aberto, é possível aceder a este sistema de ficheiros virtual, explorar a sua estrutura, bem como ler e criar ficheiros e pastas.

O exemplo seguinte mostra como criar um ficheiro de texto com o nome myFile.txt e guardá-lo no sistema de ficheiros virtual do documento.

##### Em Basic

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Dim oDoc As Object, fso As Object, oFile As Object
        Dim sRoot, sFile, sMyDir
        Set fso = CreateScriptService("FileSystem")
        Set oDoc = CreateScriptService("Document", ThisComponent)
        ' Obtém a notação do caminho da URL até à raiz do sistema de ficheiros virtual
        sRoot = oDoc.FileSystem()
        sMyDir = sRoot & "myDir"
        ' Cria a pasta «myDir» caso esta não exista
        If Not fso.FolderExists(sMyDir) Then
            fso.CreateFolder(sMyDir)
        End If
        ' Cria o ficheiro e insere algum texto nele
        sFile = fso.BuildPath(sMyDir, "myFile.txt")
        oFile = fso.CreateTextFile(sFile)
        oFile.WriteLine("Hello!")
        oFile.CloseFile()

##### Em Python

        from scriptforge import CreateScriptService
        bas = CreateScriptService("Basic")
        doc = CreateScriptService("Document", bas.ThisComponent)
        fso = CreateScriptService("FileSystem")
        sRoot = doc.FileSystem
        sMyDir = sRoot + "myDir"
        if not fso.FolderExists(sMyDir):
            fso.CreateFolder(sMyDir)
        sFile = fso.BuildPath(sMyDir, "myFile.txt")
        oFile = fso.CreateTextFile(sFile)
        oFile.WriteLine("Hello!")
        oFile.CloseFile()

Em geral, todos os métodos do serviço FileSystem podem ser utilizados para manipular ficheiros no sistema de ficheiros virtual do documento. No entanto, aplicam-se as seguintes restrições:

- Não é possível criar ficheiros na pasta raiz. Utilize subpastas existentes ou crie novas pastas para guardar ficheiros no sistema de ficheiros do documento.

- A notação FileNaming é sempre considerada como «URL».

- Os métodos CompareFiles, GetFileModified, HashFile, PickFile e PickFolder não são aplicáveis.

- O método GetFileLen devolve sempre zero.

- O método Normalize devolve sempre a cadeia de caracteres de entrada sem alterações.

O caminho para o sistema de ficheiros virtual não é um endereço físico no disco rígido do computador. Só é possível aceder-lhe a partir de um script LibreOffice e só existe enquanto o ficheiro do documento estiver aberto.

## Propriedades

Nome | Readonly | Tipo | Descrição
--- | --- | --- | ---
FileNaming | Não | String | Define ou devolve a notação atual de ficheiros e pastas, que pode ser «ANY», «URL» ou «SYS»: "ANY": (padrão) os métodos do serviço FileSystem aceitam tanto a notação URL como a notação do sistema operativo atual para os argumentos de entrada, mas devolvem sempre cadeias de caracteres URL. «URL»: os métodos do serviço FileSystem esperam que os argumentos de entrada sigam a notação URL e devolvem cadeias de caracteres do tipo URL. "SYS": os métodos do serviço FileSystem esperam que tanto os argumentos de entrada como as cadeias de caracteres de retorno sigam a notação do sistema operativo atual. Uma vez definida, a propriedade FileNaming permanece inalterada até ao final da sessão LibreOffice ou até ser definida novamente.
ConfigFolder | Sim | String | Devolve a pasta de configuração do LibreOffice.
ExtensionsFolder | Sim | String | Devolve a pasta onde as extensões estão instaladas.
HomeFolder | Sim | String | Devolve a pasta pessoal do utilizador.
InstallFolder | Sim | String | Devolve a pasta de instalação do LibreOffice.
TemplatesFolder | Sim | String | Devolve a pasta que contém os ficheiros de modelos do sistema.
TemporaryFolder | Sim | String | Devolve a pasta de ficheiros temporários definida nas definições de caminho LibreOffice.
UserTemplatesFolder | Sim | String | Devolve a pasta que contém os ficheiros de modelos definidos pelo utilizador.

Devolve a pasta que contém os ficheiros de modelos definidos pelo utilizador.
BuildPath CompareFiles CopyFile CopyFolder CreateFolder CreateTextFile DeleteFile DeleteFolder ExtensionFolder | FileExists Files FolderExists GetBaseName GetExtension GetFileLen GetFileModified GetName GetParentFolderName | GetTempName HashFile MoveFile MoveFolder Normalize OpenTextFile PickFile PickFolder SubFolders

## BuildPath

Junta o caminho de uma pasta ao nome de um ficheiro e devolve o nome completo do ficheiro com um separador de caminho válido. O separador de caminho só é adicionado se for necessário.

### Sintaxe:

svc.BuildPath(foldername: str, name: str): str

### Parâmetros:

nome-da-pasta: O caminho com o qual nome será combinado. O caminho especificado não precisa de ser uma pasta existente.

nome: O nome do ficheiro a ser acrescentado a nome da pasta. Este parâmetro utiliza a notação do sistema operativo atual.

### Exemplo:

##### Em Basic

          Dim FSO as Object
          Set FSO = CreateScriptService("FileSystem")
          Dim aFileName as String
          FSO.FileNaming = "URL"
          aFileName = FSO.BuildPath("file:///home/user", "sample file.odt")
          ' file:///home/user/sample%20file.odt

##### Em Python

          fs = CreateScriptService("FileSystem")
          fs.FileNaming = "URL"
          aFileName = fs.BuildPath("file:///home/user", "sample file.odt")
          # file:///home/user/sample%20file.odt

## CompareFiles

Compara dois ficheiros e devolve True quando estes parecem idênticos.

Dependendo do valor do argumento comparecontents, a comparação entre os dois ficheiros pode basear-se apenas nos atributos dos ficheiros (como a data da última modificação) ou no conteúdo dos ficheiros.

### Sintaxe:

svc.CompareFiles(filename1: str, filename2: str, comparecontents: bool = False): bool

### Parâmetros:

nome_do_ficheiro1, nome_do_ficheiro2: Os ficheiros a comparar.

comparecontents: Quando True, o conteúdo dos ficheiros é comparado (valor predefinido = False).

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          if fs.CompareFiles(r"C:\myFile1.txt", r"C:\myFile2.txt", comparecontents = False):
              # ...

## CopyFile

Copia um ou mais ficheiros de um local para outro. Devolve True se pelo menos um ficheiro tiver sido copiado ou False se tiver ocorrido um erro.

Também ocorrerá um erro se o parâmetro source utilizar caracteres curinga e não corresponder a nenhum ficheiro.

O método pára imediatamente após detetar um erro. O método não reverte nem anula as alterações efetuadas antes de o erro ter ocorrido.

### Sintaxe:

svc.CopyFile(source: str, destination: str, overwrite: bool = True): bool

### Parâmetros:

fonte: Pode ser um FileName ou um NamePattern que indique um ou mais ficheiros a copiar.

destino: Pode ser um FileName que especifique para onde o único ficheiro source deve ser copiado, ou um FolderName para o qual os vários ficheiros da source devem ser copiados.

- Se destino não existir, é criado.

- Não são permitidos caracteres curinga em destino.

overwrite: Se True (valor predefinido), os ficheiros podem ser substituídos. O método falhará se destination for de leitura apenas, independentemente do valor especificado em overwrite.

### Exemplo:

Nos exemplos abaixo, a primeira linha copia um único ficheiro, enquanto a segunda linha copia vários ficheiros utilizando caracteres joker.

##### Em Basic

          FSO.CopyFile("C:\Documents\my_file.odt", "C:\Temp\copied_file.odt")
          FSO.CopyFile("C:\Documents\*.*", "C:\Temp\", Overwrite := False)

##### Em Python

          fs.CopyFile(r"C:\Documents\my_file.odt", r"C:\Temp\copied_file.odt")
          fs.CopyFile(r"C:\Documents\*.*", r"C:\Temp", overwrite = False)

Tenha em atenção que as subpastas e o seu conteúdo não são copiados quando se utilizam caracteres curinga no argumento source.

## CopyFolder

Copia uma ou mais pastas de um local para outro. Devolve True se pelo menos uma pasta tiver sido copiada ou False se tiver ocorrido um erro.

Também ocorrerá um erro se o parâmetro source utilizar caracteres curinga e não corresponder a nenhuma pasta.

O método termina imediatamente após detetar um erro. O método não reverte nem anula as alterações efetuadas antes de o erro ter ocorrido.

### Sintaxe:

svc.CopyFolder(source: str, destination: str, overwrite: bool = True): bool

### Parâmetros:

fonte: Pode ser um FolderName ou um NamePattern que indique uma ou mais pastas a copiar.

destino: Especifica o FolderName para o qual serão copiadas uma ou várias pastas definidas em origem.

- Se destino não existir, é criado.

- Não são permitidos caracteres curinga em destino.

overwrite: Se True (valor predefinido), os ficheiros podem ser substituídos. O método falhará se destination for de leitura apenas, independentemente do valor especificado em overwrite.

### Exemplo:

Nos exemplos abaixo, todos os ficheiros, pastas e subpastas são copiados.

          ' Basic
          FSO.CopyFolder("C:\Documents\*", "C:\Temp\", Overwrite := False)

          # Python
          fs.CopyFolder(r"C:\Documents\*", r"C:\Temp", overwrite = False)

## CreateFolder

Cria a pasta FolderName especificada. Devolve True se a pasta tiver sido criada com sucesso.

Se a pasta especificada tiver uma pasta pai que não exista, esta será criada.

### Sintaxe:

svc.CreateFolder(foldername: str): bool

### Parâmetros:

nome-da-pasta: Uma cadeia de caracteres que representa a pasta a criar. Se a pasta já existir, será lançada uma exceção.

### Exemplo:

          ' Basic
          FSO.CreateFolder("C:\NewFolder")

          # Python
          fs.CreateFolder(r"C:\NewFolder")

## CreateTextFile

Cria um ficheiro especificado e devolve uma instância do serviço TextStream que pode ser utilizada para escrever nesse ficheiro.

O método devolve um objeto Null caso ocorra um erro.

### Sintaxe:

svc.CreateTextFile(filename: str, overwrite: bool = True, encoding: str = 'UTF-8'): svc

### Parâmetros:

nome do ficheiro: O nome do ficheiro a criar.

substituir: Valor booleano que determina se filename pode ser substituído (valor predefinido = True).

codificação: O conjunto de caracteres a utilizar. A codificação predefinida é «UTF-8».

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          myFile = fs.CreateTextFile(r"C:\Temp\ThisFile.txt", overwrite = True)

Para saber mais sobre os nomes dos conjuntos de caracteres, visite a página Conjuntos de Caracteres da IANA. Tenha em atenção que o LibreOffice não implementa todos os conjuntos de caracteres existentes.

## DeleteFile

Elimina um ou mais ficheiros. Devolve True se pelo menos um ficheiro tiver sido eliminado ou False se tiver ocorrido um erro.

Também ocorrerá um erro se o parâmetro filename utilizar caracteres curinga e não corresponder a nenhum ficheiro.

Os ficheiros a eliminar não podem estar definidos como «só de leitura».

O método termina imediatamente após detetar um erro. O método não reverte nem anula as alterações efetuadas antes da ocorrência do erro.

### Sintaxe:

svc.DeleteFile(filename: str): bool

### Parâmetros:

nome do ficheiro: Pode ser um NomeDoFicheiro ou um PadrãoDeNome que indique um ou mais ficheiros a eliminar.

### Exemplo:

Nos exemplos abaixo, apenas os ficheiros são eliminados; as subpastas não são eliminadas.

          ' Basic
          FSO.DeleteFile("C:\Temp\*.docx")

          # Python
          fs.DeleteFile(r"C:\Temp\*.docx")

## DeleteFolder

Elimina uma ou mais pastas. Devolve True se tiver sido eliminada pelo menos uma pasta ou False se tiver ocorrido um erro.

Também ocorrerá um erro se o parâmetro nome-da-pasta utilizar caracteres curinga e não corresponder a nenhuma pasta.

As pastas a eliminar não podem estar definidas como «somente leitura».

O método termina imediatamente após detetar um erro. O método não reverte nem anula as alterações efetuadas antes de o erro ter ocorrido.

### Sintaxe:

svc.DeleteFolder(foldername: str): bool

### Parâmetros:

nome da pasta: Pode ser um FolderName ou um NamePattern que indique uma ou mais pastas a eliminar.

### Exemplo:

Nos exemplos abaixo, apenas as pastas e o seu conteúdo são eliminados. Os ficheiros na pasta principal «C:\Temp» não são eliminados.

          ' Basic
          FSO.DeleteFolder("C:\Temp\*")

          # Python
          fs.DeleteFolder(r"C:\Temp\*")

## ExtensionFolder

Devolve uma cadeia de caracteres que contém a pasta onde o pacote de extensão especificado está instalado.

O valor atual da propriedade SF_FileSystem.FileNaming é utilizado para determinar a notação da cadeia de caracteres devolvida.

Utilize a propriedade Extensions do serviço Platform para obter um conjunto de cadeias de caracteres com os IDs de todas as extensões instaladas.

### Sintaxe:

svc.ExtensionFolder(extension: str): str

### Parâmetros:

extensão: Um valor de cadeia de caracteres com o ID da extensão. Se a extensão não estiver instalada, é lançada uma exceção.

### Exemplo:

Os exemplos abaixo, em Basic e Python, indicam a pasta onde a extensão APSO está instalada.

          ' Basic
          sFolder = FSO.ExtensionFolder("apso.python.script.organizer")
          ' file:///home/username/.config/libreoffice/4/user/uno_packages/cache/uno_packages/lu10833wz3u2i.tmp_/apso_1_2_7.oxt

          # Python
          sFolder = fs.ExtensionFolder("apso.python.script.organizer")

## FileExists

Devolve True se o nome de ficheiro indicado for válido e existir; caso contrário, o método devolve False.

Se o parâmetro filename for, na verdade, o nome de uma pasta existente, o método devolve False.

### Sintaxe:

svc.FileExists(filename: str): bool

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que representa o ficheiro a ser testado.

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          if fs.FileExists(r"C:\Documents\my_file.odt"):
              # ...

## Files

Devolve uma matriz com índice a partir de zero (BASIC) ou uma tupla (Python) com os ficheiros armazenados numa determinada pasta. Cada entrada da matriz ou da tupla é uma cadeia de caracteres que contém o caminho completo e o nome do ficheiro.

Se o argumento foldername especificar uma pasta que não existe, é lançada uma exceção.

A lista resultante pode ser filtrada com caracteres curinga.

### Sintaxe:

svc.Files(foldername: str, filter: str = '', includesubfolders: bool = False): str[0..*]

### Parâmetros:

nome-da-pasta: Uma cadeia de caracteres que representa uma pasta. A pasta tem de existir. Este argumento não pode designar um ficheiro.

filtro: Uma cadeia de caracteres que contém caracteres curinga («?» e «*») que serão aplicados à lista de ficheiros resultante (valor predefinido = «»).

includesubfolders: Defina este argumento como True para incluir o conteúdo das subpastas (Predefinição = False).

### Exemplo:

##### Em Basic

          Dim filesList As Variant, file As String
          FSO.FileNaming = "SYS"
          ' Devolve todos os ficheiros que correspondam ao filtro «*.txt», incluindo os ficheiros nas subpastas
          filesList = FSO.Files("/home/user/", "*.txt", IncludeSubfolders := True)
          For Each file In filesList
              ' ...
          Next file

##### Em Python

          fs.FileNaming = "SYS"
          filesList = fs.Files("/home/user/", "*.txt", includesubfolders = True)
          for file in fileList:
              # ...

## FolderExists

Devolve True se o FolderName especificado for válido e existir; caso contrário, o método devolve False.

Se o parâmetro foldername for, de facto, um nome de ficheiro existente, o método devolve False.

### Sintaxe:

svc.FolderExists(foldername: str): bool

### Parâmetros:

nome-da-pasta: Uma cadeia de caracteres que representa a pasta a ser testada.

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          if fs.FolderExists(r"C:\Documents\Thesis")
              # ...

## GetBaseName

Devolve o BaseName (equivalente ao último componente) do nome de uma pasta ou ficheiro, sem a extensão.

O método não verifica se o ficheiro ou a pasta especificados existem.

### Sintaxe:

svc.GetBaseName(filename: str): str

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que representa o nome do ficheiro e o seu caminho.

### Exemplo:

Nos exemplos abaixo, a primeira chamada ao método GetBaseName corresponde a uma pasta, pelo que a função devolve o último componente do caminho. A segunda chamada recebe um nome de ficheiro como entrada, pelo que o nome do ficheiro é devolvido sem a sua extensão.

##### Em Basic

          MsgBox FSO.GetBaseName("/home/user/Documents") ' "Documents"
          MsgBox FSO.GetBaseName("/home/user/Documents/my_file.ods") ' "my_file"

##### Em Python

          bas = CreateScriptService("Basic")
          bas.MsgBox(fs.GetBaseName("/home/user/Documents")) # "Documents"
          bas.MsgBox(fs.GetBaseName("/home/user/Documents/my_file.ods")) # "my_file"

## GetExtension

Devolve a extensão do nome de um ficheiro ou pasta sem o carácter ponto «.».

O método não verifica se o ficheiro ou a pasta especificados existem.

Se este método for aplicado a um nome de pasta ou a um ficheiro sem extensão, é devolvida uma cadeia de caracteres vazia.

### Sintaxe:

svc.GetExtension(filename: str): str

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que representa o nome do ficheiro e o seu caminho.

### Exemplo:

          ' Basic
          ext = FSO.GetExtension("C:\Windows\Notepad.exe")  ' "exe"

          # Python
          ext = fs.GetExtension(r"C:\Windows\Notepad.exe")  # "exe"

## GetFileLen

A função incorporada FileLen da linguagem Basic devolve o número de bytes contidos num ficheiro como um valor Long, ou seja, até 2 GB.

O método GetFileLen consegue lidar com ficheiros de tamanhos muito maiores, devolvendo um valor Currency.

### Sintaxe:

svc.GetFileLen(filename: str): num

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que representa um ficheiro existente.

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          fLen = fs.GetFileLen(r"C:\pagefile.sys")

## GetFileModified

Devolve a data da última modificação de um determinado ficheiro.

### Sintaxe:

svc.GetFileModified(filename: str): datetime

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que representa um ficheiro existente.

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          aDate = FSO.GetFileModified(r"C:\Documents\my_file.odt")

## GetName

Devolve o último componente do nome de um ficheiro ou pasta no formato nativo do sistema operativo.

O método não verifica se o ficheiro ou a pasta especificados existem.

### Sintaxe:

svc.GetName(filename: str): str

### Parâmetros:

filename: Uma cadeia de caracteres que representa o nome do ficheiro e o seu caminho.

### Exemplo:

          ' Basic
          a = FSO.GetName("C:\Windows\Notepad.exe")  ' Notepad.exe

          # Python
          a = fs.GetName(r"C:\Windows\Notepad.exe")  # Notepad.exe

## GetParentFolderName

Devolve uma cadeia de caracteres que contém o nome da pasta pai de um ficheiro ou pasta especificados.

O método não verifica se o ficheiro ou a pasta especificados existem.

### Sintaxe:

svc.GetParentFolderName(filename: str): str

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres com o nome do ficheiro ou da pasta a analisar.

### Exemplo:

          ' Basic
          a = FSO.GetParentFolderName("C:\Windows\Notepad.exe")  ' C:\Windows\

          # Python
          a = fs.GetParentFolderName(r"C:\Windows\Notepad.exe")  # C:\Windows\

## GetTempName

Devolve um nome de ficheiro temporário gerado aleatoriamente, útil para realizar operações que exijam um ficheiro temporário.

Por predefinição, o nome do ficheiro devolvido não tem extensão. Utilize o parâmetro extension para especificar a extensão do nome do ficheiro a gerar.

A parte da string devolvida que corresponde à pasta é a pasta temporária do sistema.

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

### Sintaxe:

svc.GetTempName(extension: str): str

### Parâmetros:

extensão: A extensão do nome do ficheiro temporário (Padrão = "").

### Exemplo:

##### Em Basic

          Dim fName As String
          FSO.FileNaming = "SYS"
          fName = FSO.GetTempName(Extension := "txt")
          ' "/tmp/SF_574068.txt"

##### Em Python

          fs.FileNaming = "SYS"
          fName = FSO.GetTempName(extension = "txt")
          # "/tmp/SF_574068.txt"

## HashFile

As funções hash são utilizadas por alguns algoritmos criptográficos, em assinaturas digitais, códigos de autenticação de mensagens, deteção de fraudes, impressões digitais, somas de verificação (verificação da integridade das mensagens), tabelas hash, armazenamento de palavras-passe e muito mais.

O método HashFile devolve o resultado de uma função hash, aplicada a um determinado ficheiro e utilizando um algoritmo especificado. O valor devolvido é uma cadeia de caracteres composta por dígitos hexadecimais em minúsculas.

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

### Sintaxe:

svc.HashFile(filename: str, algorithm: str): str

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que representa um ficheiro existente.

algoritmo: Um dos algoritmos suportados.

### Exemplo:

          ' Basic
          sHash = FSO.HashFile("C:\pagefile.sys", "MD5")

          # Python
          sHash = FSO.HashFile(r"C:\pagefile.sys", "MD5")

## MoveFile

Mova um ou mais ficheiros de um local para outro. Devolve True se pelo menos um ficheiro tiver sido movido ou False se tiver ocorrido um erro.

Também ocorrerá um erro se o parâmetro source utilizar caracteres curinga e não corresponder a nenhum ficheiro.

O método termina imediatamente após detetar um erro. O método não reverte nem anula as alterações efetuadas antes de o erro ter ocorrido.

### Sintaxe:

svc.MoveFile(source: str, destination: str): bool

### Parâmetros:

fonte: Pode ser um FileName ou um NamePattern para indicar um ou mais ficheiros a mover.

destino: Se origem for um FileName, este parâmetro indica o novo caminho e o nome do ficheiro que foi movido.

Se a operação de movimentação envolver vários ficheiros, então destino deve ser o nome de uma pasta. Se esta não existir, será criada.

Se origem e destino tiverem a mesma pasta pai, o método irá renomear a origem.

Não são permitidos caracteres curinga em destino.

### Exemplo:

Nos exemplos seguintes, apenas os ficheiros são movidos; as subpastas não são.

          ' Basic
          FSO.MoveFile("C:\Temp1\*.*", "C:\Temp2")

          # Python
          fs.MoveFile(r"C:\Temp1\*.*", r"C:\Temp2")

## MoveFolder

Mova uma ou mais pastas de um local para outro. Devolve True se pelo menos uma pasta tiver sido movida ou False se tiver ocorrido um erro.

Também ocorrerá um erro se o parâmetro source utilizar caracteres curinga e não corresponder a nenhuma pasta.

O método pára imediatamente após detetar um erro. O método não reverte nem anula as alterações efetuadas antes de o erro ter ocorrido.

### Sintaxe:

svc.MoveFolder(source: str, destination: str): bool

### Parâmetros:

fonte: Pode ser um FolderName ou um NamePattern para indicar uma ou mais pastas a serem movidas.

destino: Se a operação de movimentação envolver uma única pasta, então destino é o nome e o caminho da pasta movida, que não deve existir.

Se estiverem a ser movidas várias pastas, então destino indica para onde as pastas em origem serão movidas. Se destino não existir, será criado.

Não são permitidos caracteres curinga em destino.

### Exemplo:

          ' Basic
          FSO.MoveFolder("C:\Temp1\*", "C:\Temp2")

          # Python
          fs.MoveFolder(r"C:\Temp1\*", r"C:\Temp2")

## Normalize

Devolve uma cadeia de caracteres que contém o nome do caminho normalizado, eliminando separadores redundantes e referências a níveis superiores.

Por exemplo, os nomes de caminho A//B, A/B/, A/./B e A/foo/../B são todos normalizados para A/B.

No Windows, as barras "/" são convertidas em barras invertidas "\".

O valor atual da propriedade SF_FileSystem.FileNaming é utilizado para determinar a notação do argumento filename, bem como o formato da cadeia de caracteres devolvida.

### Sintaxe:

svc.Normalize(filename: str): str

### Parâmetros:

nome do ficheiro: uma cadeia de caracteres que representa um caminho válido. O ficheiro ou diretório representado por este argumento pode não existir.

### Exemplo:

##### Em Basic

        FSO.FileNaming = "URL"
        ' file:///home/user/Documents
        normPath = FSO.Normalize("file:///home/user/Documents/")
        ' file:///home/user/Documents
        normPath = FSO.Normalize("file:///home//user//Documents/")
        ' file:///home/user
        normPath = FSO.Normalize("file:///home//user//Documents/../")

##### Em Python

        fs.FileNaming = "URL"
        normPath = fs.Normalize("file:///home/user/Documents/")
        normPath = fs.Normalize("file:///home//user//Documents/")
        normPath = fs.Normalize("file:///home//user//Documents/../")

## OpenTextFile

Abre um ficheiro e devolve um objeto TextStream que pode ser utilizado para ler, escrever ou acrescentar dados ao ficheiro.

Note-se que o método não verifica se o ficheiro indicado é realmente um ficheiro de texto.

O método devolve um objeto Null (em Basic) ou None (em Python) caso ocorra um erro.

### Sintaxe:

svc.OpenTextFile(filename: str, iomode: int = 1, create: bool = False, encoding: str = 'UTF-8'): svc

### Parâmetros:

nome do ficheiro: Identifica o ficheiro a abrir.

iomode: Indica o modo de entrada/saída. Pode ser uma das três constantes: svc.ForReading (predefinição), svc.ForWriting ou svc.ForAppending.

create: Valor booleano que indica se é possível criar um novo ficheiro caso o nome do ficheiro especificado não exista:

- Se True, será criado um novo ficheiro e as suas pastas pai, caso estes não existam;

- Se False, não são criados novos ficheiros (por predefinição).

codificação: O conjunto de caracteres a utilizar. A codificação predefinida é «UTF-8».

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          myFile = fs.OpenTextFile(r"C:\Temp\ThisFile.txt", fs.ForReading)
          if myFile is not None:
              # ...

## PickFile

Abre uma caixa de diálogo para abrir ou guardar ficheiros.

Se o modo SAVE estiver definido e o ficheiro selecionado existir, será apresentada uma mensagem de aviso.

### Sintaxe:

svc.PickFile(defaultfile: str ='', mode: str = 'OPEN', filter: str = ''): str

### Parâmetros:

defaultfile: Este argumento é uma cadeia de caracteres composta por uma pasta e um nome de ficheiro:

- A parte relativa à pasta indica a pasta que será apresentada quando a caixa de diálogo for aberta (por predefinição = a última pasta selecionada).

- A parte «ficheiro» indica o ficheiro predefinido a abrir ou a guardar.

modo: Um valor de cadeia de caracteres que pode ser «OPEN» (para ficheiros de entrada) ou «SAVE» (para ficheiros de saída). O valor predefinido é «OPEN».

filtro: A extensão dos ficheiros apresentados quando a caixa de diálogo é aberta (por predefinição = sem filtro).

### Exemplo:

Os exemplos abaixo abrem um seletor de ficheiros com o filtro «txt» aplicado.

          ' Basic
          aFile = FSO.PickFile("C:\Documents", "OPEN", "txt")

          # Python
          aFile = fs.PickFile(r"C:\Documents", "OPEN", "txt")

## PickFolder

Abre uma caixa de diálogo para selecionar uma pasta.

### Sintaxe:

svc.PickFolder(defaultfolder: str = '', title: str = '', freetext: str = ''): str

### Parâmetros:

pasta-padrão: Uma cadeia de caracteres que contém o nome da pasta que será apresentado quando a caixa de diálogo for aberta (padrão = a última pasta selecionada).

título: Texto a apresentar no cabeçalho da caixa de diálogo. O valor predefinido é definido pelo ambiente de trabalho.

freetext: Texto a apresentar na caixa de diálogo (valor predefinido = ""). Este parâmetro está obsoleto.

### Exemplo:

          ' Basic
          aFolder = FSO.PickFolder("C:\Documents", "Escolha uma pasta ou clique em Cancelar")

          # Python
          aFolder = fs.PickFolder(r"C:\Documents", "Escolha uma pasta ou clique em Cancelar")

## SubFolders

Devolve uma matriz de cadeias de caracteres, com índice a partir de zero, correspondente às pastas armazenadas num determinado nome-da-pasta.

A lista pode ser filtrada com caracteres curinga.

### Sintaxe:

svc.SubFolders(foldername: str, filter: str = '', includesubfolders: bool = False): str[0..*]

### Parâmetros:

foldername: Uma cadeia de caracteres que representa uma pasta. A pasta tem de existir. nome-da-pasta não pode designar um ficheiro.

filter: Uma cadeia de caracteres que contém caracteres curinga («?» e «*») que serão aplicados à lista de pastas resultante (valor predefinido = «»).

includesubfolders: Defina este argumento como True para incluir o conteúdo das subpastas (Predefinição = False).

### Exemplo:

##### Em Basic

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

##### Em Python

          fs.FileNaming = "SYS"
          folderList = fs.SubFolders("/home/user/")
          for folder in folderList:
              # ...

Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.

Tópicos relacionados

ScriptForge.TextStream service

Função de entrada [VBA]

Declaração de abertura

Necessitamos da sua ajuda!