Spis treści

# Usługa ScriptForge.TextStream

Usługa TextStream służy do sekwencyjnego odczytu i zapisu do plików otwartych lub utworzonych za pomocą usługi ScriptForge.FileSystem.

Metody OpenTextFile i CreateTextFile z usługi FileSystem zwracają instancję usługi TextStream.

Separatory wierszy mogą być określone przez użytkownika. W operacjach wejściowych obsługiwane są CR, LF lub CR+LF. W operacjach wyjściowych domyślnym ogranicznikiem wierszy jest ten używany przez system operacyjny.

Dostęp do ogranicznika wierszy systemu operacyjnego, w którym wykonywane jest makro, można uzyskać za pomocą właściwości SF_String.sfNEWLINE.

Zakłada się, że wszystkie operacje potrzebne do odczytu lub zapisu pliku (otwieranie, odczyt/zapis i zamykanie) mają miejsce podczas tego samego uruchomienia makra.

## Wywoływanie usługi

Poniższe przykłady w języku Basic i Python wykorzystują metodę OpenTextFile do utworzenia instancji usługi TextStream.

##### W języku Basic

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

Po wykonaniu wszystkich operacji odczytu lub zapisu plik należy zamknąć metodą CloseFile:

        myFile.CloseFile()

Opcjonalnie zasoby wykorzystywane przez instancję TextStream można zwolnić przy użyciu metody Dispose:

        Set myFile = myFile.Dispose()

Metody usługi TextStream bazują najczęściej na interfejsach UNO XTextInputStream i XTextOutputStream.

##### W języku Python

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

## Właściwości

Nazwa | Tylko do odczytu | Typ | Opis
--- | --- | --- | ---
AtEndOfStream | Tak | Boolean | Używany w trybie odczytu. Wartość True wskazuje, że plik został osiągnięty. Test wykorzystujący tę właściwość powinien poprzedzać wywołanie metody ReadLine.
Encoding | Tak | String | Zestaw znaków, który ma być używany. Domyślne kodowanie to "UTF-8".
FileName | Tak | String | Zwraca nazwę bieżącego pliku w formacie URL lub w formacie natywnego systemu operacyjnego, w zależności od bieżącej wartości właściwości FileNaming usługi FileSystem.
IOMode | Tak | String | Wskazuje tryb wejścia/wyjścia. Możliwe wartości to "READ", "WRITE" lub "APPEND".
Line | Tak | Long | Zwraca liczbę wierszy przeczytanych lub zapisanych do tej pory.
NewLine | Nie | String | Ustawia lub zwraca bieżący ogranicznik, który ma zostać wstawiony pomiędzy dwoma kolejnymi zapisanymi wierszami. Wartość domyślna to natywny ogranicznik wierszy w bieżącym systemie operacyjnym.

Aby dowiedzieć się więcej o nazwach zestawów znaków, odwiedź stronę Zestaw znaków IANA. Należy pamiętać, że LibreOffice nie implementuje wszystkich istniejących zestawów znaków.

Lista metod w usłudze TextStream
CloseFile ReadAll | ReadLine SkipLine | WriteBlankLines WriteLine

## CloseFile

Zamyka bieżący strumień wejściowy lub wyjściowy i opróżnia bufor wyjściowy, jeśli ma to zastosowanie. Zwraca wartość True, jeśli plik został pomyślnie zamknięty.

### Składnia:

myFile.CloseFile(): bool

## ReadAll

Zwraca wszystkie pozostałe wiersze strumienia tekstowego jako pojedynczy ciąg. Podziały wierszy nie są usuwane.

Wynikowy ciąg można podzielić na wiersze za pomocą wbudowanej funkcji Basic Split, jeśli znany jest ogranicznik wierszy, lub za pomocą metody SF_String.SplitLines.

W przypadku dużych plików użycie metody ReadAll marnuje zasoby pamięci. W takich przypadkach zaleca się czytanie pliku wiersz po wierszu metodą ReadLine.

### Składnia:

myFile.ReadAll(): str

### Przykład:

Rozważmy plik tekstowy "Students.txt" o następującej zawartości (nazwa w każdym wierszu):

        Herbie Peggy
        Hardy Jarrett
        Edith Lorelle
        Roderick Rosamund
        Placid Everette

Poniższe przykłady w języku Basic i Python wykorzystują metody ReadAll i SplitLines do wczytywania zawartości pliku w tablicę ciągów znaków:

##### W języku Basic

        ' Ładuje usługę FileSystem
        Dim FSO : FSO = CreateScriptService("FileSystem")
        Otwiera plik tekstowy z nazwami do odczytania
        Dim inputFile as Object
        Set inputFile = FSO.OpenTextFile("/home/user/Documents/Students.txt")
        ' Odczytuje całą zawartość pliku wejściowego jako pojedynczy ciąg
        Dim allData as String
        allData = inputFile.ReadAll()
        ' Dzieli ciąg na tablicę
        Dim arrNames as Variant
        arrNames = SF_String.SplitLines(allData)
        ' (...)
        inputFile.CloseFile()

##### W języku Python

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

## ReadLine

Zwraca następny wiersz w strumieniu tekstowym jako ciąg znaków. Podziały wierszy są usuwane ze zwróconego ciągu.

Test AtEndOfStream powinien poprzedzać metodę ReadLine jak w przykładzie poniżej.

Jeżeli podczas poprzedniego wywołania metody ReadLine lub SkipLine osiągnięto AtEndOfStream, zostanie zgłoszony błąd.

### Składnia:

myFile.ReadLine(): str

### Przykład:

##### W języku Basic

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

##### W języku Python

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

## SkipLine

Pomija następny wiersz w strumieniu wejściowym podczas odczytu pliku TextStream.

Ta metoda może skutkować ustawieniem AtEndOfStream na True.

### Składnia:

myFile.SkipLine()

## WriteBlankLines

Zapisuje określoną liczbę pustych wierszy w strumieniu wyjściowym.

### Składnia:

myFile.WriteBlankLines(lines: int)

### Parametry:

lines: liczba pustych wierszy do zapisania w pliku.

## WriteLine

Zapisuje dany ciąg do strumienia wyjściowego jako pojedynczy wiersz.

Znak zdefiniowany we właściwości NewLine jest używany jako ogranicznik wierszy.

### Składnia:

myFile.WriteLine(line: str)

### Parametry:

line: wiersz do zapisania może być pusty.

### Przykład:

Poniższe przykłady w języku Basic i Python tworzą plik tekstowy CSV, w którym każdy wiersz zawiera wartość i jej kwadrat, aż do lastValue.

##### W języku Basic

        Sub SquaredValuesFile(lastValue as Integer)
            ' Tworzy instancję usługi FileSystem
            Dim FSO as Variant : FSO = CreateScriptService("FileSystem")
            ' Tworzy plik tekstowy
            Dim myFile as Variant : myFile = FSO.CreateTextFile("/home/user/Documents/squares.csv")
            ' Zapisuje wartość i wartość do kwadratu, oddzielone ";"
            Dim value as Integer
            myFile.WriteLine("Wartość;Wartość do kwadratu")
            For value = 1 To lastValue
                myFile.WriteLine(value & ";" & value ^ 2)
            Next value
            ' Zamyka plik i zwalnia zasoby
            myFile.CloseFile()
            Set myFile = myFile.Dispose()
        End Sub

##### W języku 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()

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Usługa ScriptForge.FileSystem

Funkcja Input [VBA]

Instrukcja Open