Obsah
Rejstřík 🔎︎

# 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.

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)

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

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.

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

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.

Související témata

Služba ScriptForge.FileSystem

Funkce Input

Příkaz Open