Conteúdo
Índice 🔎︎

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

## Instanciando o serviço

O trecho de código abaixo usa o método OpenTextFile para criar uma instância do serviço TextStream Service.

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

Este serviço é totalmente compatível com as linguagens Basic e Python. Todos os exemplos são descritos usando a linguagem de programação Basic e podem ser facilmente convertidos para Python.

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.

## 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 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() As Boolean

## 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() As String

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

O exemplo abaixo usa os métodos ReadAll e SplitLines para ler os conteúdos do arquivo em um Array de Strings:

          Sub ReadFile_Example
              '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("~/Documents/Students.txt")
              'Reads all the contents in the input file as a single string
              Dim allData as String
              allData = inputFile.ReadAll()
              'Splits the string into an array
              Dim arrNames as Variant
              arrNames = SF_String.SplitLines(allData)
              ' (...)
              inputFile.CloseFile()
          End Sub

## 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() As String

### Exemplo:

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

## 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 As Long)

### Parâmetros:

Lines: Número de linhas em branco a serem escritas.

## 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 As String)

### Parâmetros:

Line: Linha a ser escrita, pode ser vazia.

### Exemplo:

          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("~/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()
              myFile.Dispose()
          End Sub

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.

Tópicos relacionados

Serviço ScriptForge.FileSystem

Função Input

Instrução Open