Sumário

# 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.

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

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.

Para saber mais sobre os nomes dos conjuntos de caracteres, visite a página IANA's Character Set (página somente no inglês). Note que o LibreOffice não implementa todos os conjuntos de caracteres 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()

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.

Tópicos relacionados

Serviço ScriptForge.FileSystem

Função de Input [VBA]

Instrução Open