Obsah

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

## Volání služby

Níže uvedené příklady v Basicu a Pythonu používají pro vytvoření instance služby TextStream metodu OpenTextFile.

##### V Basicu

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

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.

##### V Pythonu

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

## 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(): bool

## 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(): str

### 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 v Basicu a Pythonu se využívají metody ReadAll a SplitLines k načtení obsahu souboru do pole řetězců:

##### V Basicu

        ' 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("/home/user/Documents/Students.txt")
        ' Načte celý obsah vstupního souboru jako jediný řetězec
        Dim allData as String
        allData = inputFile.ReadAll()
        ' Rozdělí řetězec na pole
        Dim arrNames as Variant
        arrNames = SF_String.SplitLines(allData)
        ' (...)
        inputFile.CloseFile()

##### V Pythonu

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

## 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(): str

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## 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: int)

### Parametry:

lines: Počet prázdných řádků, které se mají do souboru 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: str)

### Parametry:

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

### Příklad:

V níže uvedených příkladech v Basicu a Pythonu se vytvoří textový soubor ve formátu CSV, v němž každý řádek obsahuje hodnotu a její druhou mocninu, a to až do hodnoty lastValue.

##### V Basicu

        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("/home/user/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()
            Set myFile = myFile.Dispose()
        End Sub

##### V Pythonu

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

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 nebo skriptech Pythonu.

Související témata

Služba ScriptForge.FileSystem

Funkce Input [VBA]

Příkaz Open