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.


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

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

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.


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

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.


♥ Doe para nosso projeto! ♥