diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk
index 53af112a0c..cc0b7f3837 100644
--- a/AllLangHelp_sbasic.mk
+++ b/AllLangHelp_sbasic.mk
@@ -88,6 +88,7 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\
helpcontent2/source/text/sbasic/shared/03/sf_session \
helpcontent2/source/text/sbasic/shared/03/sf_services \
helpcontent2/source/text/sbasic/shared/03/sf_string \
+ helpcontent2/source/text/sbasic/shared/03/sf_textstream \
helpcontent2/source/text/sbasic/shared/03/sf_timer \
helpcontent2/source/text/sbasic/shared/03/sf_ui \
helpcontent2/source/text/sbasic/shared/03/lib_schedule \
diff --git a/source/text/sbasic/shared/03/lib_ScriptForge.xhp b/source/text/sbasic/shared/03/lib_ScriptForge.xhp
index 7ef2387b3e..82e11d5c67 100644
--- a/source/text/sbasic/shared/03/lib_ScriptForge.xhp
+++ b/source/text/sbasic/shared/03/lib_ScriptForge.xhp
@@ -22,7 +22,7 @@
-
+ GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")The described modules and classes are invoked from user scripts as "Services". A generic constructor of those services has been designed for that purpose:
@@ -30,46 +30,88 @@
Services from external libraries can be registered with the RegisterScriptServices(...) method in order to extend the set of available services.The ScriptForge Basic library is available from %PRODUCTNAME 7.1 onwards.
-
@@ -114,7 +156,7 @@
- TextStream class Service
+
diff --git a/source/text/sbasic/shared/03/sf_calc.xhp b/source/text/sbasic/shared/03/sf_calc.xhp
index 156ef6a8e6..a2b782bfb1 100644
--- a/source/text/sbasic/shared/03/sf_calc.xhp
+++ b/source/text/sbasic/shared/03/sf_calc.xhp
@@ -67,7 +67,7 @@
The use of the prefix "SFDocuments." while calling the service is optional.
Definitions
- Many methods require a "Sheet" or a "Range" as argument. Single cells are considered a special case of a Range).
+ Many methods require a "Sheet" or a "Range" as argument. Single cells are considered a special case of a Range.Both may be expressed either as a string or as a reference (= object) depending on the situation:
@@ -86,10 +86,10 @@
oDocB.CopyToRange(oDocA.Range("SheetX.D4:F8"), "D2:F6") 'CopyToRange(source, target)
-
SheetName
+
SheetName
Either the sheet name as a string or an object produced by the .Sheet property.The shortcut "~" (tilde) represents the current sheet.
-
RangeName
+
RangeName
Either a string designating a set of contiguous cells located in a sheet of the current instance or an object produced by the .Range property.The shortcut "~" (tilde) represents the current selection or the first range if multiple ranges are selected.The shortcut "*" represents all used cells.
diff --git a/source/text/sbasic/shared/03/sf_filesystem.xhp b/source/text/sbasic/shared/03/sf_filesystem.xhp
index 16bb454908..96402fa027 100644
--- a/source/text/sbasic/shared/03/sf_filesystem.xhp
+++ b/source/text/sbasic/shared/03/sf_filesystem.xhp
@@ -333,8 +333,8 @@
FSO.BuildPath(FolderName As String, Name As String) As String
- FolderName : The path with which Name will be combined. The specified path does not need to be an existing folder.
- Name : The name of the file to be appended to FolderName. This parameter uses the notation of the current operating system.
+ FolderName: The path with which Name will be combined. The specified path does not need to be an existing folder.
+ Name: The name of the file to be appended to FolderName. This parameter uses the notation of the current operating system.
Dim FSO : FSO = CreateScriptService("FileSystem")
@@ -357,8 +357,8 @@
FSO.CompareFiles(FileName1 As String, FileName2 As String, [CompareContents As Boolean]) As Boolean
- FileName1, FileName2 : The files to compare.
- CompareContents : When True, the contents of the files are compared (default = False).
+ FileName1, FileName2: The files to compare.
+ CompareContents: When True, the contents of the files are compared (default = False).
FSO.FileNaming = "SYS"
@@ -382,8 +382,8 @@
FSO.CopyFile(Source As String, Destination As String, [Overwrite As Boolean]) As Boolean
- Source : It can be a FileName or a NamePattern indicating one or more files to be copied.
- Destination : It can be either a FileName specifying where the single Source file is to be copied, or a FolderName into which the multiple files from Source are to be copied.
+ Source: It can be a FileName or a NamePattern indicating one or more files to be copied.
+ Destination: It can be either a FileName specifying where the single Source file is to be copied, or a FolderName into which the multiple files from Source are to be copied.If FolderName does not exist, it is created.
@@ -392,7 +392,7 @@
Wildcard characters are not allowed in Destination.
- Overwrite : If True (default), files may be overwritten. The method will fail if Destination is readonly, regardless of the value specified in Overwrite.
+ Overwrite: If True (default), files may be overwritten. The method will fail if Destination is readonly, regardless of the value specified in Overwrite.
FSO.FileNaming = "SYS"
@@ -417,8 +417,8 @@
FSO.CopyFolder(Source As String, Destination As String, [Overwrite As Boolean]) As Boolean
- Source : It can be a FolderName or a NamePattern indicating one or more folders to be copied.
- Destination : Specifies the FolderName into which the single or multiple folders defined in Source are to be copied.
+ Source: It can be a FolderName or a NamePattern indicating one or more folders to be copied.
+ Destination: Specifies the FolderName into which the single or multiple folders defined in Source are to be copied.If FolderName does not exist, it is created.
@@ -427,7 +427,7 @@
Wildcard characters are not allowed in Destination.
- Overwrite : If True (default), files may be overwritten. The method will fail if Destination is readonly, regardless of the value specified in Overwrite.
+ Overwrite: If True (default), files may be overwritten. The method will fail if Destination is readonly, regardless of the value specified in Overwrite.
FSO.FileNaming = "SYS"
@@ -449,7 +449,7 @@
FSO.CreateFolder(FolderName As String) As Boolean
- FolderName : A string representing the folder to be created. If the folder already exists, an exception will be raised.
+ FolderName: A string representing the folder to be created. If the folder already exists, an exception will be raised.
FSO.FileNaming = "SYS"
@@ -470,9 +470,9 @@
FSO.CreateTextFile(FileName As String, [Overwrite As Boolean], [Encoding As String]) As Object
- FileName : The name of the file to be created.
- Overwrite : Boolean value that determines if FileName can be overwritten (default = True).
- Encoding : The character set to be used. The default encoding is "UTF-8".
+ FileName: The name of the file to be created.
+ Overwrite: Boolean value that determines if FileName can be overwritten (default = True).
+ Encoding: The character set to be used. The default encoding is "UTF-8".
Dim myFile As Object
@@ -497,7 +497,7 @@
FSO.DeleteFile(FileName As String) As Boolean
- FileName : It can be a FileName or a NamePattern indicating one or more files to be deleted.
+ FileName: It can be a FileName or a NamePattern indicating one or more files to be deleted.
FSO.FileNaming = "SYS"
@@ -521,7 +521,7 @@
FSO.DeleteFolder(FolderName As String) As Boolean
- FolderName : It can be a FolderName or a NamePattern indicating one or more folders to be deleted.
+ FolderName: It can be a FolderName or a NamePattern indicating one or more folders to be deleted.
FSO.FileNaming = "SYS"
@@ -543,7 +543,7 @@
FSO.FileExists(FileName As String) As Boolean
- FileName : A string representing the file to be tested.
+ FileName: A string representing the file to be tested.
FSO.FileNaming = "SYS"
@@ -567,8 +567,8 @@
FSO.Files(FolderName As String, [Filter As String]) As Variant
- FolderName : A string representing a folder. The folder must exist. FolderName must not designate a file.
- Filter : A string containing wildcards ("?" and "*") that will be applied to the resulting list of files (default = "").
+ FolderName: A string representing a folder. The folder must exist. FolderName must not designate a file.
+ Filter: A string containing wildcards ("?" and "*") that will be applied to the resulting list of files (default = "").
Dim filesList As Variant, file As String
@@ -593,7 +593,7 @@
FSO.FolderExists(FolderName As String) As Boolean
- FolderName : A string representing the folder to be tested.
+ FolderName: A string representing the folder to be tested.
FSO.FolderNaming = "SYS"
@@ -616,7 +616,7 @@
FSO.GetBaseName(FileName As String) As String
- FileName : A string representing the file name and its path.
+ FileName: A string representing the file name and its path.
' If the input parameter is a folder, it returns the last component of the path
@@ -640,7 +640,7 @@
FSO.GetExtension(FileName As String) As String
- FileName : A string representing the file name and its path.
+ FileName: A string representing the file name and its path.
FSO.FileNaming = "SYS"
@@ -661,7 +661,7 @@
FSO.GetFileLen(FileName As String) As Currency
- FileName : A string representing an existing file.
+ FileName: A string representing an existing file.
Dim a As Currency
@@ -682,7 +682,7 @@
FSO.GetFileModified(FileName As String) As Date
- FileName : A string representing an existing file.
+ FileName: A string representing an existing file.
Dim a As Date
@@ -704,7 +704,7 @@
FSO.GetName(FileName As String) As String
- FileName : A string representing the file name and its path.
+ FileName: A string representing the file name and its path.
Dim a As String
@@ -726,7 +726,7 @@
FSO.GetParentFolderName(FileName As String) As String
- FileName : A string with the file or folder name to be analyzed.
+ FileName: A string with the file or folder name to be analyzed.
Dim a As String
@@ -771,8 +771,8 @@
FSO.HashFile(FileName As String, Algorithm As String) As String
- FileName : A string representing an existing file.
- Algorithm : One of the supported algorithms.
+ FileName: A string representing an existing file.
+ Algorithm: One of the supported algorithms.
FSO.FileNaming = "SYS"
@@ -794,8 +794,8 @@
FSO.MoveFile(Source As String, Destination As String) As Boolean
- Source : It can be a FileName or NamePattern to designate one or more files to be moved.
- Destination : If Source is a FileName then this parameter indicates the new path and file name of the moved file.
+ Source: It can be a FileName or NamePattern to designate one or more files to be moved.
+ Destination: If Source is a FileName then this parameter indicates the new path and file name of the moved file.If the move operation involves multiple files, then Destination must be a folder name. If it does not exist, it is created.If Source and Destination have the same parent folder, the method will rename the Source.Wildcard characters are not allowed in Destination.
@@ -822,8 +822,8 @@
FSO.MoveFolder(Source As String, Destination As String) As Boolean
- Source : It can be a FolderName or NamePattern to designate one or more folders to be moved.
- Destination : If the move operation involves a single folder, then Destination is the name and path of the moved folder and it must not exist.
+ Source: It can be a FolderName or NamePattern to designate one or more folders to be moved.
+ Destination: If the move operation involves a single folder, then Destination is the name and path of the moved folder and it must not exist.If multiple folders are being moved, then Destination designates where the folders in Source will be moved into. If Source does not exist, it is created.Wildcard characters are not allowed in Destination.
@@ -848,9 +848,9 @@
FSO.OpenTextFile(FileName As String, [IOMode As Integer], [Create As Boolean], [Encoding As String]) As Object
- FileName : Identifies the file to open.
- IOMode : Indicates the input/output mode. It can be one of three constants: FSO.ForReading (default), FSO.ForWriting, or FSO.ForAppending.
- Create : Boolean value that indicates whether a new file can be created if the specified filename doesn't exist:
+ FileName: Identifies the file to open.
+ IOMode: Indicates the input/output mode. It can be one of three constants: FSO.ForReading (default), FSO.ForWriting, or FSO.ForAppending.
+ Create: Boolean value that indicates whether a new file can be created if the specified filename doesn't exist:If True a new file and its parent folders will be created if they do not exist;
@@ -859,7 +859,7 @@
If False then new files are not created (default).
- Encoding : The character set to be used. The default encoding is "UTF-8".
+ Encoding: The character set to be used. The default encoding is "UTF-8".
Dim myFile As Object
@@ -884,7 +884,7 @@
FSO.PickFile([DefaultFile As String], [Mode As String], [Filter As String]) As String
- DefaultFile : This argument is a string composed of a folder and file name:
+ DefaultFile: This argument is a string composed of a folder and file name:The folder part indicates the folder that will be shown when the dialog opens (default = the last selected folder).
@@ -893,8 +893,8 @@
The file part designates the default file to open or save.
- Mode : OPEN (input file) or SAVE (output file). The default value is OPEN.
- Filter : The extension of the files displayed when the dialog is opened (default = no filter).
+ Mode: OPEN (input file) or SAVE (output file). The default value is OPEN.
+ Filter: The extension of the files displayed when the dialog is opened (default = no filter).
Dim a As Variant
@@ -916,8 +916,8 @@
FSO.PickFolder([DefaultFolder As String], [FreeText As String]) As String
- DefaultFolder : A string containing the folder name that will be displayed when the dialog is opened (default = the last selected folder).
- FreeText : Text to display in the dialog (default = "").
+ DefaultFolder: A string containing the folder name that will be displayed when the dialog is opened (default = the last selected folder).
+ FreeText: Text to display in the dialog (default = "").
Dim a As Variant
@@ -939,8 +939,8 @@
FSO.SubFolders(FolderName As String, [Filter As String]) As Variant
- FolderName : A string representing a folder. The folder must exist. FolderName must not designate a file.
- Filter : A string containing wildcards ("?" and "*") that will be applied to the resulting list of folders (default = "").
+ FolderName: A string representing a folder. The folder must exist. FolderName must not designate a file.
+ Filter: A string containing wildcards ("?" and "*") that will be applied to the resulting list of folders (default = "").
Dim folderList As Variant, folder As String
@@ -954,7 +954,7 @@
- Link here SF_TextStream help page after it is finished
+
Input FunctionOpen Statement
diff --git a/source/text/sbasic/shared/03/sf_textstream.xhp b/source/text/sbasic/shared/03/sf_textstream.xhp
new file mode 100644
index 0000000000..99c158e19f
--- /dev/null
+++ b/source/text/sbasic/shared/03/sf_textstream.xhp
@@ -0,0 +1,337 @@
+
+
+
+
+
+
+ ScriptForge.TextStream service
+ /text/sbasic/shared/03/sf_textstream.xhp
+
+
+
+
+
+
+ TextStream service
+
+
+
+
+
ScriptForge.TextStream service
+ The TextStream service is used to sequentially read from and write to files opened or created using the ScriptForge.FileSystem service.
+ The methods OpenTextFile and CreateTextFile from the FileSystem service return an instance of the TextStream service.
+
+ Line delimiters may be specified by the user. In input operations CR, LF or CR+LF are supported. In output operations, the default line delimiter is the one used by the operating system.
+ The line delimiter for the operating system where the macro is being executed can be accessed using the SF_String.sfNEWLINE property.
+ All operations needed to read from or write to a file (open, read/write and close) are presumed to happen during the same macro run.
+
+
Service instantiation
+ The code snippet below uses the OpenTextFile method to create an instance of the TextStream Service.
+
+ GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
+ Dim FSO As Variant
+ FSO = CreateScriptService("FileSystem")
+ Set myFile = FSO.OpenTextFile("C:\Temp\ThisFile.txt", FSO.ForReading)
+
+ The file must be closed with the CloseFile method after all read or write operations have been executed:
+
+ myFile.CloseFile()
+
+ Optionally, the resources used by the TextStream instance can be released using the Dispose method:
+
+ Set myFile = myFile.Dispose()
+
+ The methods in the TextStream service are mostly based on the XTextInputStream and XTextOutputStream UNO interfaces.
+
+
+
+
+ Name
+
+
+ Readonly
+
+
+ Type
+
+
+ Description
+
+
+
+
+ AtEndOfStream
+
+
+ Yes
+
+
+ Boolean
+
+
+ Used in read mode. A True value indicates that the end of the file has been reached. A test using this property should precede calls to the ReadLine method.
+
+
+
+
+ Encoding
+
+
+ Yes
+
+
+ String
+
+
+ The character set to be used. The default encoding is "UTF-8".
+
+
+
+
+ FileName
+
+
+ Yes
+
+
+ String
+
+
+ Returns the name of the current file either in URL format or in the native operating system's format, depending on the current value of the FileNaming property of the FileSystem service.
+
+
+
+
+ IOMode
+
+
+ Yes
+
+
+ String
+
+
+ Indicates the input/output mode. Possible values are "READ", "WRITE" or "APPEND".
+
+
+
+
+ Line
+
+
+ Yes
+
+
+ Long
+
+
+ Returns the number of lines read or written so far.
+
+
+
+
+ NewLine
+
+
+ No
+
+
+ String
+
+
+ Sets or returns the current delimiter to be inserted between two successive written lines. The default value is the native line delimiter in the current operating system.
+
+
+
+To learn more about the names of character sets, visit IANA's Character Set page. Beware that %PRODUCTNAME does not implement all existing character sets.
+
+
+ List of Methods in the TextStream Service
+
+
+
+
+ CloseFile
+ ReadAll
+
+
+
+
+ ReadLine
+ SkipLine
+
+
+
+
+ WriteBlankLines
+ WriteLine
+
+
+
+
+ Returns all the remaining lines in the text stream as a single string. Line breaks are not removed.
+ The resulting string can be split in lines either by using the Split built-in Basic function if the line delimiter is known, or with the SF_String.SplitLines method.
+ For large files, using the ReadAll method wastes memory resources. In such cases it is recommended to read the file line by line using the ReadLine method.
+
+
+ myFile.ReadAll() As String
+
+
+ Consider the text file "Students.txt" with the following contents (a name in each line):
+
+ Herbie Peggy
+ Hardy Jarrett
+ Edith Lorelle
+ Roderick Rosamund
+ Placid Everette
+
+ The example below uses the ReadAll and SplitLines methods to read the contents of the file into an array of strings:
+
+ Sub ReadFile_Example
+ 'Loads the FileSystem service
+ Dim FSO : FSO = CreateScriptService("FileSystem")
+ 'Opens the text file with the names to be read
+ 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 --------------------------------------------------------------------------------------------------------------------------
+
+ TextStream service;ReadLine
+
+
ReadLine
+ Returns the next line in the text stream as a string. Line breaks are removed from the returned string.
+ The AtEndOfStream test should precede the ReadLine method like in the example below.
+ An error will be raised if the AtEndOfStream was reached during the previous ReadLine or SkipLine method call.
+
+
+ myFile.ReadLine() As String
+
+
+
+ Dim sLine As String
+ Do While Not myFile.AtEndOfStream
+ sLine = myFile.ReadLine()
+ ' (...)
+ Loop
+
+
+
+
+ SkipLine --------------------------------------------------------------------------------------------------------------------------
+
+ TextStream service;SkipLine
+
+
SkipLine
+ Skips the next line in the input stream when reading a TextStream file.
+ This method can result in AtEndOfStream being set to True.
+
+ Writes a specified number of empty lines to the output stream.
+
+
+ myFile.WriteBlankLines(Lines As Long)
+
+
+ Lines: The number of empty lines to write.
+
+
+
+ WriteLine --------------------------------------------------------------------------------------------------------------------------
+
+ TextStream service;WriteLine
+
+
WriteLine
+ Writes the given string to the output stream as a single line.
+ The character defined in the NewLine property is used as the line delimiter.
+
+
+ myFile.WriteLine(Line As String)
+
+
+ Line: The line to write, may be empty.
+
+
+ Sub SquaredValuesFile(lastValue as Integer)
+ 'Instantiates the FileSystem Service
+ Dim FSO as Variant : FSO = CreateScriptService("FileSystem")
+ 'Creates a text file
+ Dim myFile as Variant : myFile = FSO.CreateTextFile("~/Documents/squares.csv")
+ 'Writes the Value and Value squared, separated by ";"
+ Dim value as Integer
+ myFile.WriteLine("Value;Value Squared")
+ For value = 1 To lastValue
+ myFile.WriteLine(value & ";" & value ^ 2)
+ Next value
+ 'Closes the file and free resources
+ myFile.CloseFile()
+ myFile.Dispose()
+ End Sub
+
+
+
+
+
+
+ Input Function
+ Open Statement
+
+
+