ScriptForge. Serviço TextStream

O serviço TextStream é utilizado para ler e escrever sequencialmente em ficheiros abertos ou criados através do serviço ScriptForge.FileSystem.

Os métodos OpenTextFile e CreateTextFile do serviço FileSystem devolvem uma instância do serviço TextStream.

Os delimitadores de linha podem ser especificados pelo utilizador. Nas operações de entrada, são suportados os caracteres CR, LF ou CR+LF. Nas operações de saída, o delimitador de linha predefinido é aquele utilizado pelo sistema operativo.

O delimitador de linha do sistema operativo em que a macro está a ser executada pode ser acedido através da propriedade SF_String.sfNEWLINE.

Presume-se que todas as operações necessárias para ler ou escrever num ficheiro (abrir, ler/escrever e fechar) ocorram durante a mesma execução da macro.

Chamada de serviço

Os exemplos abaixo, em Basic e Python, utilizam o método OpenTextFile para criar uma instância do serviço TextStream.

    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Dim FSO As Variant
    FSO = CreateScriptService("FileSystem")
    Set myFile = FSO.OpenTextFile("C:\Temp\ThisFile.txt", FSO.ForReading)
  

O ficheiro deve ser fechado com o método CloseFile após a execução de todas as operações de leitura ou escrita:

    myFile.CloseFile()
  

Opcionalmente, os recursos utilizados pela instância TextStream podem ser libertados através do método Dispose:

    Set myFile = myFile.Dispose()
  

Os métodos do serviço TextStream baseiam-se, na sua maioria, no XTextInputStream e XTextOutputStream.

    from scriptforge import CreateScriptService
    fs = CreateScriptService("FileSystem")
    myFile = fs.OpenTextFile(r"C:\Temp\ThisFile.txt", fs.ForReading)
    # ...
    myFile.CloseFile()
    myFile = myFile.Dispose()
  

Características

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.

CloseFile

Fecha o fluxo de entrada ou saída atual e esvazia o buffer de saída, se for o caso. Devolve True se o ficheiro tiver sido fechado com sucesso.

myFile.CloseFile(): bool

ReadAll

Devolve todas as linhas restantes no fluxo de texto como uma única cadeia de caracteres. As quebras de linha não são removidas.

A cadeia de caracteres resultante pode ser dividida em linhas, quer utilizando a função incorporada do Basic Split, caso se conheça o delimitador de linha, quer através do método SF_String.SplitLines.

No caso de ficheiros de grande dimensão, a utilização do método ReadAll desperdiça recursos de memória. Nesses casos, recomenda-se a leitura do ficheiro linha a linha, utilizando o método ReadLine.

myFile.ReadAll(): str

Considere o ficheiro de texto «Students.txt» com o seguinte conteúdo (um nome em cada linha):

    Herbie Peggy
    Hardy Jarrett
    Edith Lorelle
    Roderick Rosamund
    Placid Everette
  

Os exemplos abaixo, em Basic e Python, utilizam os métodos ReadAll e SplitLines para ler o conteúdo do ficheiro e armazená-lo numa matriz de cadeias de caracteres:

    'Carrega o serviço FileSystem'
    Dim FSO : FSO = CreateScriptService("FileSystem")
    'Abre o ficheiro de texto com os nomes a ler
    Dim inputFile as Object
    Set inputFile = FSO.OpenTextFile("/home/user/Documents/Students.txt")
    'Lê todo o conteúdo do ficheiro de entrada como uma única cadeia de caracteres'
    Dim allData as String
    allData = inputFile.ReadAll()
    'Divide a cadeia de caracteres num array
    Dim arrNames as Variant
    arrNames = SF_String.SplitLines(allData)
    ' (...)
    inputFile.CloseFile()
  

    fs = CreateScriptService("FileSystem")
    inputFile = fs.OpenTextFile("/home/user/Documents/Students.txt")
    allData = inputFile.ReadAll()
    arrNames = allData.split(inputFile.NewLine)
    # ...
    inputFile.CloseFile()
  

ReadLine

Devolve a linha seguinte do fluxo de texto como uma cadeia de caracteres. As quebras de linha são removidas da cadeia de caracteres devolvida.

O teste AtEndOfStream deve preceder o método ReadLine, tal como no exemplo abaixo.

Será gerado um erro se o AtEndOfStream tiver sido atingido durante a chamada anterior ao método ReadLine ou SkipLine.

myFile.ReadLine(): str

    Dim sLine As String
    Do While Not myFile.AtEndOfStream
        sLine = myFile.ReadLine()
        ' (...)
    Loop
  

    while not myFile.AtEndOfStream:
        sLine = myFile.ReadLine()
        # ...
  

SkipLine

Ignora a linha seguinte no fluxo de entrada ao ler um ficheiro TextStream.

Este método pode fazer com que AtEndOfStream seja definido como True.

myFile.SkipLine()

WriteBlankLines

Escreve um número especificado de linhas vazias no fluxo de saída.

myFile.WriteBlankLines(lines: int)

linhas: O número de linhas vazias a escrever no ficheiro.

WriteLine

Grava a cadeia de caracteres indicada no fluxo de saída como uma única linha.

O carácter definido na propriedade NewLine é utilizado como delimitador de linha.

myFile.WriteLine(line: str)

line: A linha a escrever; pode estar vazia.

Os exemplos abaixo, em Basic e Python, criam um ficheiro de texto no formato CSV, no qual cada linha contém um valor e o seu quadrado, até se chegar a lastValue.

    Sub SquaredValuesFile(lastValue as Integer)
        'Cria uma instância do Serviço FileSystem'
        Dim FSO as Variant : FSO = CreateScriptService("FileSystem")
        'Cria um ficheiro de texto
        Dim myFile as Variant : myFile = FSO.CreateTextFile("/home/user/Documents/squares.csv")
        «Escreve o valor e o valor ao quadrado, separados por «;»»
        Dim value as Integer
        myFile.WriteLine("Valor;Valor ao quadrado")
        For value = 1 To lastValue
            myFile.WriteLine(value & ";" & value ^ 2)
        Next value
        'Fecha o ficheiro e liberta os recursos
        myFile.CloseFile()
        Set myFile = myFile.Dispose()
    End Sub
  

    def squared_values_file(lastValue):
        fs = CreateScriptService("FileSystem")
        myFile = fs.CreateTextFile("/home/user/Documents/squares.csv")
        myFile.WriteLine("Value;Value Squared")
        for value in range(1, lastValue + 1):
            myFile.WriteLine("{};{}".format(value, value ** 2))
        myFile.CloseFile()
        myFile = myFile.Dispose()
  

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.