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.

note

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.


Istanziazione del servizio

Il frammento di codice sottostante usa il metodo OpenTextFile per creare un'istanza del servizio TextStream.


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

Questo servizio è pienamente supportato sia in Basic, sia in Python. Tutti gli esempi sono espressi nel linguaggio di programmazione Basic e possono essere facilmente convertiti in Python.


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

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


Proprietà

Nome

Sola lettura

Tipo

Descrizione

AtEndOfStream

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

String

Il set di caratteri da usare. La codifica predefinita è "UTF-8".

FileName

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

String

Indica il modo di input/output. I valori possibili sono "READ", "WRITE" o "APPEND".

Line

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.


note

Per saperne di più in merito ai nomi delle codifiche dei caratteri, visitate la pagina Codifiche dei caratteri IANA. Fate attenzione 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() As Boolean
    

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

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
    

L'esempio sottostante usa i metodi ReadAll e SplitLines per leggere il contenuto del file all'interno di una matrice di stringhe:


      Sub ReadFile_Example
          '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("~/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

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

Esempio:


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

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

Parametri:

Lines: il numero di righe vuote da scrivere.

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

Parametri:

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

Esempio:


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

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.