Contenuto

# Servizio ScriptForge.TextStream

Il servizio TextStream è usato per leggere e scrivere sequenzialmente da file aperti o creati usando il servizio ScriptForge.FileSystem.

I metodi OpenTextFile e CreateTextFile del servizio FileSystem restituiscono un'istanza del servizio TextStream.

I delimitatori di riga possono essere specificati dall'utente. Nelle operazioni d'inserimento sono supportati i caratteri CR, LF o CR+LF. Nelle operazioni di output, il delimitatore predefinito è quello usato dal sistema operativo.

Il delimitatore di riga del sistema operativo in cui è in esecuzione la macro può essere ottenuto usando la proprietà SF_String.sfNEWLINE.

Tutte le operazioni necessarie per leggere da o scrivere in un file (apertura, lettura/scrittura e chiusura) si presume che avvengano durante la stessa esecuzione della macro.

## Invocazione del servizio

Gli esempi sottostanti in Basic e Python usano il metodo OpenTextFile per creare un'istanza del servizio TextStream.

##### In Basic

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

Il file deve essere chiuso con il metodo CloseFile dopo che sono state eseguite tutte le operazioni di lettura e scrittura:

        myFile.CloseFile()

Le risorse usate dall'istanza di TextStream possono, facoltativamente, essere liberate usando il metodo Dispose:

        Set myFile = myFile.Dispose()

I metodi del servizio TextStream si basano principalmente sulle interfacce UNO XTextInputStream e XTextOutputStream.

##### In Python

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

## Proprietà

Nome | Sola lettura | Tipo | Descrizione
--- | --- | --- | ---
AtEndOfStream | Sì | Boolean | Usato in modo lettura. Un valore True indica che è stata raggiunta la fine del file. Un controllo che fa uso di questa proprietà dovrebbe precedere le chiamate al metodo ReadLine.
Encoding | Sì | String | Il set di caratteri da usare. La codifica predefinita è "UTF-8".
FileName | Sì | String | Restituisce il nome del file attuale in formato URL o nel formato nativo del sistema operativo, a seconda del valore corrente della proprietà FileNaming del servizio FileSystem.
IOMode | Sì | String | Indica il modo di input/output. I valori possibili sono "READ", "WRITE" o "APPEND".
Line | Sì | Long | Restituisce il numero di righe lette o scritte fino a quel momento.
NewLine | No | String | Imposta o restituisce il delimitatore corrente da inserire tra due righe scritte successive. Il valore predefinito è il delimitatore di riga nativo del sistema operativo in uso.

Per saperne di più in merito ai nomi delle codifiche dei caratteri, visitare la pagina Codifiche dei caratteri IANA. È bene notare che LibreOffice non implementa tutte le codifiche dei caratteri esistenti.

Elenco dei metodi del servizio TextStream
CloseFile ReadAll | ReadLine SkipLine | WriteBlankLines WriteLine

## CloseFile

Chiude il flusso di input o output corrente e svuota il buffer di output, se necessario. Restituisce True se il file è stato chiuso correttamente.

### Sintassi:

myFile.CloseFile(): bool

## ReadAll

Restituisce tutte le righe rimanenti del flusso di testo come un'unica stringa. Le interruzioni di riga non vengono rimosse.

La stringa risultante può essere divisa in righe sia usando la funzione Split incorporata in Basic, se il delimitatore di riga è noto, sia con il metodo SF_String.SplitLines.

Con file di grandi dimensioni, l'uso del metodo ReadAll consuma risorse di memoria. In tali casi è consigliato leggere il file riga per riga usando il metodo ReadLine.

### Sintassi:

myFile.ReadAll(): str

### Esempio:

Si consideri il file di testo "Students.txt" col seguente contenuto (un nome per ciascuna riga):

        Herbie Peggy
        Hardy Jarrett
        Edith Lorelle
        Roderick Rosamund
        Placid Everette

Gli esempi sottostanti in Basic e Python usano i metodi ReadAll e SplitLines per leggere il contenuto del file all'interno di una matrice di stringhe:

##### In Basic

        'Carica il servizio FileSystem
        Dim FSO : FSO = CreateScriptService("FileSystem")
        'Apre il file di testo con i nomi da leggere
        Dim inputFile as Object
        Set inputFile = FSO.OpenTextFile("/home/user/Documents/Students.txt")
        'Legge tutto il contenuto del file di input come un'unica stringa
        Dim allData as String
        allData = inputFile.ReadAll()
        'Suddivide la stringa in una matrice
        Dim arrNames as Variant
        arrNames = SF_String.SplitLines(allData)
        ' (...)
        inputFile.CloseFile()

##### In Python

        fs = CreateScriptService("FileSystem")
        inputFile = fs.OpenTextFile("/home/user/Documents/Students.txt")
        allData = inputFile.ReadAll()
        arrNames = allData.split(inputFile.NewLine)
        # ...
        inputFile.CloseFile()

## ReadLine

Restituisce la riga successiva del flusso di testo in formato stringa. Le interruzioni di riga vengono rimosse dalla stringa restituita.

Il controllo AtEndOfStream dovrebbe precedere il metodo ReadLine come nell'esempio sottostante.

Verrà generato un errore se AtEndOfStream viene raggiunto durante le precedenti chiamate ai metodi ReadLine o SkipLine.

### Sintassi:

myFile.ReadLine(): str

### Esempio:

##### In Basic

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

##### In Python

        while not myFile.AtEndOfStream:
            sLine = myFile.ReadLine()
            # ...

## SkipLine

Salta la prossima riga del flusso di input durante la lettura di un file TextStream.

Questo metodo può comportare che AtEndOfStream venga impostato a True.

### Sintassi:

myFile.SkipLine()

## WriteBlankLines

Scrive nel flusso di output il numero specificato di righe vuote.

### Sintassi:

myFile.WriteBlankLines(lines: int)

### Parametri:

lines: il numero di righe vuote da scrivere nel file.

## WriteLine

Scrive la stringa indicata nel flusso di output in una singola riga.

Il carattere definito nella proprietà NewLine è usato come delimitatore di riga.

### Sintassi:

myFile.WriteLine(line: str)

### Parametri:

line: la riga da scrivere, può essere vuota.

### Esempio:

Gli esempi seguenti in Basic e Python creano un file di testo in formato CSV nel quale ogni riga contiene un valore ed il suo quadrato fino al raggiungimento del valore lastValue.

##### In Basic

        Sub SquaredValuesFile(lastValue as Integer)
            'Istanzia il servizio FileSystem
            Dim FSO as Variant : FSO = CreateScriptService("FileSystem")
            'Crea un file di testo
            Dim myFile as Variant : myFile = FSO.CreateTextFile("/home/user/Documents/squares.csv")
            'Scrive il valore di Value e Value elevato al quadrato, separati da ";"
            Dim value as Integer
            myFile.WriteLine("Value;Value Squared")
            For value = 1 To lastValue
                myFile.WriteLine(value & ";" & value ^ 2)
            Next value
            'Chiude il file e libera le risorse
            myFile.CloseFile()
            Set myFile = myFile.Dispose()
        End Sub

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

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.

Argomenti correlati

Servizio ScriptForge.FileSystem

Funzione Input [VBA]

Istruzione Open