Služba ScriptForge.TextStream

Služba TextStream se používá k postupnému čtení/zápisu z/do souborů otevřených či vytvořených pomocí služby ScriptForge.FileSystem.

Instanci služby TextStream vrátí metody OpenTextFile a CreateTextFile ze služby FileSystem.

Uživatel může určit oddělovače řádků. Při vstupních operacích je možné použít CR, LF nebo CR+LF. Při výstupních operacích je výchozím oddělovačem řádků ten, který je používán operačním systémem.

Oddělovač řádků pro operační systém, v němž je marko spuštěno, lze získat z vlastnosti SF_String.sfNEWLINE.

note

Předpokládá se, že všechny operace potřebné k čtení ze souboru nebo zápisu do něj (otevření, čtení/zápis a zavření) budou provedeny během téhož běhu makra.


Vytvoření instance služby

Níže uvedená část kódu používá pro vytvoření instance služby TextStream metodu OpenTextFile.


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

Tato služba je plně podporována v jazycích Basic i Python. Všechny příklady jsou uvedeny v programovacím jazyce Basic a lze je snadno převést na Python.


Po provedení všech operací čtení či zápisu je nutné soubor uzavřít pomocí metody CloseFile:


      myFile.CloseFile()
    

Zdroje použité instancí služby TextStream lze také uvolnit metodou Dispose:


      Set myFile = myFile.Dispose()
    
note

Metody služby TextStream jsou zpravidla založeny na rozhraních UNO XTextInputStream a XTextOutputStream.


Vlastnosti

Název

Pouze pro čtení

Typ

Popis

AtEndOfStream

ano

Boolean

Použito v režimu čtení. Hodnota True značí, že bylo dosaženo konce souboru. Kontrola provedená touto metodou by měla předcházet volání metody ReadLine.

Encoding

ano

String

Znaková sada, která se má použít. Výchozím kódováním je "UTF-8".

FileName

ano

String

Vrátí název aktuálního souboru buď ve formátu URL, nebo v nativním formátu operačního systému, a to podle aktuální hodnoty vlastnosti FileNaming služby FileSystem.

IOMode

ano

String

Udává režim vstupu/výstupu. Možnými hodnotami jsou "READ" (čtení), "WRITE" (zápis) a "APPEND" (přidávání).

Line

ano

Long

Vrátí počet doposud přečtených či zapsaných řádků.

NewLine

ne

String

Nastaví nebo vrátí aktuální oddělovač vkládaný mezi dva následující zapisované řádky. Výchozí hodnotou je nativní oddělovač řádků z aktuálního operačního systému.


note

Podrobnosti o názvech znakových sad naleznete na stránce znakových sad IANA. Mějte na paměti, že v LibreOffice nemusí být všechny znakové sady implementovány.


Seznam metod služby TextStream

CloseFile
ReadAll

ReadLine
SkipLine

WriteBlankLines
WriteLine


CloseFile

Zavře aktuální vstupní či výstupní proud a vyprázdní výstupní buffer, je-li to relevantní. V případě úspěšného uzavření vrátí True.

Syntaxe:


        myFile.CloseFile() As Boolean
    

ReadAll

Vrátí všechny řádky zbývající v textovém proudu jako jediný řetězec. Zalomení řádků nejsou odstraněna.

Výsledný řetězec je možné rozdělit na řádky pomocí vestavěné funkce Basicu Split, je-li oddělovač řádků znám, nebo metodou SF_String.SplitLines.

U velkých souborů znamená použití metody ReadAll zbytečně velké paměťové nároky. V takových případech je doporučeno číst řádky souboru po jednom pomocí metody ReadLine.

Syntaxe:


        myFile.ReadAll() As String
    

Příklad:

Textový soubor "Students.txt" obsahuje následující řádky (jméno na každém z nich):


      Herbie Peggy
      Hardy Jarrett
      Edith Lorelle
      Roderick Rosamund
      Placid Everette
    

V níže uvedených příkladech se využívají metody ReadAll a SplitLines k načtení obsahu souboru do pole řetězců:


      Sub ReadFile_Example
          ' Načte službu FileSystem
          Dim FSO : FSO = CreateScriptService("FileSystem")
          ' Otevře textový soubor se jmény, která se mají načíst
          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

Vrátí následující řádek v textovém proudu jako řetězec. Zalomení řádků jsou z vraceného řetězce odstraněna.

Metodě ReadLine by měla předcházet kontrola vlastnosti AtEndOfStream, stejně jako v níže uvedeném příkladu.

Jestliže byl dosažen konec souboru představovaný vlastností AtEndOfStream během volání metody ReadLine nebo SkipLine, nastane chyba.

Syntaxe:


        myFile.ReadLine() As String
    

Příklad:


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

SkipLine

Přeskočí při čtení ze souboru TextStream ve vstupním proudu následující řádek.

Výsledkem této metody může být nastavení vlastnosti AtEndOfStream na hodnotu True.

Syntaxe:


        myFile.SkipLine()
    

WriteBlankLines

Zapíše do výstupního proudu zadaný počet prázdných řádků.

Syntaxe:


        myFile.WriteBlankLines(Lines As Long)
    

Parametry:

Lines: Počet prázdných řádků, které se mají zapsat.

WriteLine

Zapíše do výstupního proudu zadaný řetězec jako jeden řádek.

Jako oddělovač řádků se použije znak definovaný ve vlastnosti NewLine.

Syntaxe:


        myFile.WriteLine(Line As String)
    

Parametry:

Line: Řádek, který se má zapsat, může být prázdný.

Příklad:


      Sub SquaredValuesFile(lastValue as Integer)
          ' Vytvoří instanci služby FileSystem
          Dim FSO as Variant : FSO = CreateScriptService("FileSystem")
          ' Vytvoří textový soubor
          Dim myFile as Variant : myFile = FSO.CreateTextFile("~/Documents/squares.csv")
          ' Zapíše hodnoty a jejich druhé mocniny, oddělovačem je středník ";"
          Dim value as Integer
          myFile.WriteLine("Hodnota;Druhá mocniny hodnoty")
          For value = 1 To lastValue
              myFile.WriteLine(value & ";" & value ^ 2)
          Next value
          ' Zavře soubor a uvolní zdroje
          myFile.CloseFile()
          myFile.Dispose()
      End Sub
    
warning

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu.