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

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.


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.


♥ Doe para nosso projeto! ♥