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.

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.

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

Propriedades

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 Collabora Office não implementa todos os conjuntos de caracteres existentes.

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.

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.

myFile.ReadAll(): str

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:

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

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.

myFile.ReadLine(): str

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

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.

myFile.SkipLine()

WriteBlankLines

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

myFile.WriteBlankLines(lines: int)

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.

myFile.WriteLine(line: str)

line: Linha a ser escrita, pode ser vazia.

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.

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

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.