Serviço ScriptForge.TextStream

O serviço TextStream é usado para ler e escrever sequencialmente de/para arquivos abertos usando o serviço ScriptForge.FileSystem service.

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

Delimitadores de linha pode ser especificados pelo usuário. Em operações de escrita CR, LR ou CR+LF são suportados. Em operações de leitura, o delimitador padrão é o usado pelo sistema operacional.

O caractere de quebra de linha para o sistema operacional onde a macro está sendo executada pode ser acessado usando a propriedade SF_String.sfNEWLINE.

note

Este serviço assume que todas as operações necessárias para ler ou escrever de/para um arquivo (abrir, ler/escrever e fechar) ocorrem durante a execução de uma mesma macro.


Invocação do serviço

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

Em Basic

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

O arquivo deve ser fechado com o método CloseFile após todas as operações de leitura e escrita terem sido executadas:


    myFile.CloseFile()
  

Opcionalmente, os recursos usados pela instância TextStream podem ser liberados pelo método Dispose:


    Set myFile = myFile.Dispose()
  
note

Os métodos no serviço TextStream são baseados principalmente nas interfaces UNO XTextInputStream e XTextOutputStream.


Em Python

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

Propriedades

Nome

Somente leitura

Tipo

Descrição

AtEndOfStream

Sim

Boolean

Usado no modo de leitura. Um valor True indica que o final do arquivo foi alcançado. Um teste usando esta propriedade deve preceder chamadas do método ReadLine.

Encoding

Sim

String

Codificação de caracteres a ser usada. A codificação padrão é "UTF-8".

FileName

Sim

String

Retorna o nome do arquivo atual no formato URL ou no formato nativo do sistema operacional, dependendo do valor atual da propriedade FileNaming do serviço FileSystem.

IOMode

Sim

String

Indica o modo de entrada/saída. Os valores possíveis são "READ", "WRITE" ou "APPEND".

Line

Sim

Long

Retorna o número de linhas lidas ou escritas até o momento.

NewLine

Não

String

Define ou retorna o delimitador atual a ser inserido entre duas linhas sucessivas escritas no arquivo. O valor padrão é o delimitador de linha nativo do sistema operacional em uso.


note

To learn more about the names of character sets, visit IANA's Character Set page. Be aware that LibreOfficeDev does not implement all existing character sets.


Lista de Métodos no Serviço TextStream

CloseFile
ReadAll

ReadLine
SkipLine

WriteBlankLines
WriteLine


CloseFile

Fecha o fluxo de entrada ou saída atual e esvazia o buffer se necessário. Retorna True se o arquivo foi fechado com sucesso.

Sintaxe:

myFile.CloseFile(): bool

ReadAll

Retorna todas as linhas restantes do arquivo de texto em uma única String. Quebras de linha não são removidas.

A String resultante pode ser dividida em linhas usando o método Basic interno Split se o delimitador for conhecido, ou com o método SF_String.SplitLines.

Para arquivos longos, usar o método ReadAll é um desperdício de recursos de memória. Em tais casos, recomenda-se ler o arquivo uma linha de cada vez com o método ReadLine.

Sintaxe:

myFile.ReadAll(): str

Exemplo:

Considere o arquivo de texto "Students.txt" com os seguintes conteúdos (um nome em cada linha):


    Herbie Peggy
    Hardy Jarrett
    Edith Lorelle
    Roderick Rosamund
    Placid Everette
  

Os exemplos abaixo em Basic e Python usam o método ReadAll e SplitLines para ler os conteúdos do arquivo em um array de strings:

Em Basic

    'Carrega o serviço FileSystem
    Dim FSO : FSO = CreateScriptService("FileSystem")
    'Abre o arquivo de texto com os nomes a serem lidos
    Dim inputFile as Object
    Set inputFile = FSO.OpenTextFile("/home/user/Documents/Students.txt")
    ' Lê todo o conteúdo de um arquivo de entrada como uma única string
    Dim allData as String
    allData = inputFile.ReadAll()
    ' Separa a string em um Array
    Dim arrNames as Variant
    arrNames = SF_String.SplitLines(allData)
    ' (...)
    inputFile.CloseFile()
  
Em Python

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

ReadLine

Retorna uma String com a próxima linha no fluxo de texto. Quebras de linha são removidas da String retornada.

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

Um erro será lançado se AtEndOfStream foi atingido durante a chamada anterior dos métodos ReadLine ou SkipLine.

Sintaxe:

myFile.ReadLine(): str

Exemplo:

Em Basic

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

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

SkipLine

Pula a próxima linha no fluxo de entrada quando um arquivo TextStream estiver sendo lido.

Este método pode resultar alteração do valor da propriedade AtEndOfStream para True.

Sintaxe:

myFile.SkipLine()

WriteBlankLines

Escreve um número especificado de linhas em branco para o fluxo de saída.

Sintaxe:

myFile.WriteBlankLines(lines: int)

Parâmetros:

lines: Número de linhas em branco a serem escritas no arquivo.

WriteLine

Escreve a String especificada para o fluxo de saída em uma única linha.

O caractere definido na propriedade NewLine é usado como delimitador de linha.

Sintaxe:

myFile.WriteLine(line: str)

Parâmetros:

line: Linha a ser escrita, pode ser vazia.

Exemplo:

Os exemplos abaixo em Basic e Python criam um arquivo texto no formato CSV no qual cada linha contém um valor e se quadrado até que lastValue seja atingido.

Em Basic

    Sub SquaredValuesFile(lastValue as Integer)
        'Cria instância do serviço FileSystem
        Dim FSO as Variant : FSO = CreateScriptService("FileSystem")
        'Cria o arquivo texto
        Dim myFile as Variant : myFile = FSO.CreateTextFile("/home/user/Documents/squares.csv")
        'Escreve o "Valor" e "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 arquivo e libera os recursos
        myFile.CloseFile()
        Set myFile = myFile.Dispose()
    End Sub
  
Em Python

    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()
  
warning

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.