ScriptForge (SF_FileSystem) IncludeSubfolders argument

In the FileSystem service, the
- SubFolders()
- Files()
methods receive an optional argument
IncludeSubfolders (Boolean).

That argument determines whether or not only
the given FolderName is explored or also its subfolders
up to the bottom of the folders structure.

The argument must be used with caution as the number
of returned folders or files may increase rapidly.
anThis could consume excessive process time.

This patch will require an update of the
help page about the filesystem service.

The new argument is available both for Basic and Python
user scripts.

Change-Id: Id2a96cd63cb51f8681f20a203a711b47a636fc3a
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/154763
Reviewed-by: Jean-Pierre Ledure <jp@ledure.be>
Tested-by: Jenkins

3 files changed, 151 insertions, 61 deletions

diff --git a/wizards/source/scriptforge/SF_FileSystem.xba b/wizards/source/scriptforge/SF_FileSystem.xba
index bb611d69b59a..2364ec4206b1 100644
--- a/wizards/source/scriptforge/SF_FileSystem.xba
+++ b/wizards/source/scriptforge/SF_FileSystem.xba
@@ -84,6 +84,11 @@ Const cstForAppending			=	8
 '''	Document file system
 Const DOCFILESYSTEM				=	"vnd.sun.star.tdoc:/"
 
+'''	Folders and files scanning
+Const cstSEPARATOR				=	"//;"	'	Separates folders or files in the accumulators
+Const cstFILES					=	1		'	Caler = Files()
+Const cstFOLDERS				=	2		'	Caller = SubFolders()
+
 REM ===================================================== CONSTRUCTOR/DESTRUCTOR
 
 REM -----------------------------------------------------------------------------
@@ -762,11 +767,15 @@ End Function    '   ScriptForge.SF_FileSystem.FileExists
 REM -----------------------------------------------------------------------------
 Public Function Files(Optional ByVal FolderName As Variant _
 						, Optional ByVal Filter As Variant _
+						, Optional ByVal IncludeSubfolders As Variant _
 						) As Variant
 '''	Return an array of the FileNames stored in the given folder. The folder must exist
+'''	Subfolders may be optionally explored too.
+'''	If the number of files exceeds a reasonable amount (> 1000 ?), the process time may become long.
 '''	Args:
 '''		FolderName: the folder to explore
 '''		Filter: contains wildcards ("?" and "*") to limit the list to the relevant files (default = "")
+'''		IncludeSubfolders: when True (default = False), subfolders are explored too.
 '''	Returns:
 '''		An array of strings, each entry is the FileName of an existing file
 '''	Exceptions:
@@ -775,58 +784,36 @@ Public Function Files(Optional ByVal FolderName As Variant _
 '''	Example:
 '''		Dim a As Variant
 '''			FSO.FileNaming = "SYS"
-'''			a = FSO.Files("C:\Windows\")
+'''			a = FSO.Files("C:\Windows\", IncludeSubfolders := True)
 
 Dim vFiles As Variant			'	Return value
 Dim oSfa As Object				'	com.sun.star.ucb.SimpleFileAccess
-Dim sFolderName As String		'	URL lias for FolderName
-Dim sFile As String				'	Single file
-Dim bDocFileSystem As Boolean	'	When True, a document file system is being explored
+Dim sFilesColl As String		'	cstSEPARATOR delimited string of list of files (FileNaming notation)
 Dim i As Long
 
 Const cstThisSub = "FileSystem.Files"
-Const cstSubArgs = "FolderName, [Filter=""""]"
+Const cstSubArgs = "FolderName, [Filter=""""], [IncludeSubfolders=False]"
 
 	If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 	vFiles = Array()
 
 Check:
 	If IsMissing(Filter) Or IsEmpty(Filter) Then Filter = ""
+	If IsMissing(IncludeSubfolders) Or IsEmpty(IncludeSubfolders) Then IncludeSubfolders = False
 	If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not SF_Utils._ValidateFile(FolderName, "FolderName") Then GoTo Finally
 		If Not SF_Utils._Validate(Filter, "Filter", V_STRING) Then GoTo Finally
+		If Not SF_Utils._Validate(IncludeSubfolders, "IncludeSubfolders", V_BOOLEAN) Then GoTo Finally
 	End If
-	sFolderName = SF_FileSystem._ConvertToUrl(FolderName)
 	If SF_FileSystem.FileExists(FolderName) Then GoTo CatchFile				' Must not be a file
 	If Not SF_FileSystem.FolderExists(FolderName) Then GoTo CatchFolder		' Folder must exist
 
-	bDocFileSystem = SF_String.StartsWith(sFolderName, DOCFILESYSTEM)
-
 Try:
-	'	Get files
+	sFilesColl = ""
 	Set oSfa = SF_Utils._GetUnoService("FileAccess")
-	vFiles = oSfa.getFolderContents(sFolderName, False)	'	NB: The False argument is ignored in document file systems
-	'	Adjust notations
-	For i = 0 To UBound(vFiles)
-		sFile = SF_FileSystem._ConvertFromUrl(vFiles(i))
-		vFiles(i) = sFile
-	Next i
-
-	'	Reduce list to valid items:
-		'	- those passing the filter
-		'	- files only, not folders: in documents file systems, the False argument of getFolderContents() is ignored.
-	If Len(Filter) > 0 Or bDocFileSystem Then
-		For i = 0 To UBound(vFiles)
-			sFile = SF_FileSystem.GetName(vFiles(i))
-			If Len(Filter) > 0 Then
-				If Not SF_String.IsLike(sFile, Filter) Then vFiles(i) = ""
-			End If
-			If bDocFileSystem Then
-				If oSfa.isFolder(ConvertToUrl(vFiles(i))) Then vFiles(i) = ""
-			End If
-		Next i
-		vFiles = Sf_Array.TrimArray(vFiles)
-	End If
+	SF_FileSystem._ScanFolder(cstFiles, sFilesColl, FolderName, oSfa, Filter, IncludeSubfolders)
+
+	If Len(sFilesColl) > Len(cstSEPARATOR) Then vFiles() = Split(Mid(sFilesColl, Len(cstSEPARATOR) + 1), cstSEPARATOR)
 
 Finally:
 	Files = vFiles
@@ -1025,7 +1012,7 @@ End Function    '   ScriptForge.SF_FileSystem.GetFileLen
 REM -----------------------------------------------------------------------------
 Public Function GetFileModified(Optional ByVal FileName As Variant) As Variant
 '''	Returns the last modified date for the given file
-'''	The method is not supported for document's internal file systems.
+'''	The method is not supporte for document's internal file systems.
 '''	Args:
 '''		FileName: a string representing an existing file
 '''	Returns:
@@ -1253,7 +1240,7 @@ Public Function HashFile(Optional ByVal FileName As Variant _
 							) As String
 '''	Return an hexadecimal string representing a checksum of the given file
 '''	Next algorithms are supported: MD5, SHA1, SHA224, SHA256, SHA384 and SHA512
-'''	The method is not supported for document's internal file systems.
+'''	The method is not supporte for document's internal file systems.
 '''	Args:
 '''		FileName: a string representing a file
 '''		Algorithm: The hashing algorithm to use
@@ -1602,7 +1589,7 @@ Public Function PickFile(Optional ByVal DefaultFile As Variant _
 '''	The mode, OPEN or SAVE, and the filter may be preset
 '''	If mode = SAVE and the picked file exists, a warning message will be displayed
 '''	Modified from Andrew Pitonyak's Base Macro Programming §10.4
-'''	The method is not supported for document's internal file systems.
+'''	The method is not supporte for document's internal file systems.
 '''	Args:
 '''		DefaultFile:	Folder part: the FolderName from which to start. Default = the last selected folder
 '''						File part: the default file to open or save
@@ -1699,7 +1686,7 @@ Public Function PickFolder(Optional ByVal DefaultFolder As Variant _
 							, Optional ByVal FreeText As Variant _
 							) As String
 '''	Display a FolderPicker dialog box
-'''	The method is not supported for document's internal file systems.
+'''	The method is not supporte for document's internal file systems.
 '''	Args:
 '''		DefaultFolder: the FolderName from which to start. Default = the last selected folder
 '''		FreeText: text to display in the dialog. Default = ""
@@ -1813,11 +1800,14 @@ End Function	'	ScriptForge.SF_FileSystem.SetProperty
 REM -----------------------------------------------------------------------------
 Public Function SubFolders(Optional ByVal FolderName As Variant _
 								, Optional ByVal Filter As Variant _
+								, Optional ByVal IncludeSubfolders As Variant _
 								) As Variant
-'''	Return an array of the FolderNames stored in the given folder. The folder must exist
+'''	Return an array of the FolderNames stored in the given folder. The folder must exist,
+'''	Subfolders may be optionally explored too.
 '''	Args:
 '''		FolderName: the folder to explore
 '''		Filter: contains wildcards ("?" and "*") to limit the list to the relevant folders (default = "")
+'''		IncludeSubfolders: when True (default = False), subfolders are explored too.
 '''	Returns:
 '''		An array of strings, each entry is the FolderName of an existing folder
 '''	Exceptions:
@@ -1826,45 +1816,36 @@ Public Function SubFolders(Optional ByVal FolderName As Variant _
 '''	Example:
 '''		Dim a As Variant
 '''			FSO.FileNaming = "SYS"
-'''			a = FSO.SubFolders("C:\Windows\")
+'''			a = FSO.SubFolders("C:\Windows\", IncludeSubfolders := True)
 
 Dim vSubFolders As Variant		'	Return value
 Dim oSfa As Object				'	com.sun.star.ucb.SimpleFileAccess
-Dim sFolderName As String		'	URL lias for FolderName
-Dim sFolder As String			'	Single folder
+Dim sFoldersColl As String		'	cstSEPARATOR delimited string of list of folders (FileNaming notation)
 Dim i As Long
 
 Const cstThisSub = "FileSystem.SubFolders"
-Const cstSubArgs = "FolderName, [Filter=""""]"
+Const cstSubArgs = "FolderName, [Filter=""""], [IncludeSubfolders=False]"
 
 	If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 	vSubFolders = Array()
 
 Check:
 	If IsMissing(Filter) Or IsEmpty(Filter) Then Filter = ""
+	If IsMissing(IncludeSubfolders) Or IsEmpty(IncludeSubfolders) Then IncludeSubfolders = False
 	If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not SF_Utils._ValidateFile(FolderName, "FolderName") Then GoTo Finally
 		If Not SF_Utils._Validate(Filter, "Filter", V_STRING) Then GoTo Finally
+		If Not SF_Utils._Validate(IncludeSubfolders, "IncludeSubfolders", V_BOOLEAN) Then GoTo Finally
 	End If
-	sFolderName = SF_FileSystem._ConvertToUrl(FolderName)
 	If SF_FileSystem.FileExists(FolderName) Then GoTo CatchFile				' Must not be a file
-	If Not SF_FileSystem.FolderExists(FolderName) Then GoTo CatchFolder		' Folder must exist
+	If Not SF_FileSystem.FolderExists(FolderName) Then GoTo CatchFolder		' Top folder must exist
 
 Try:
-	'	Get SubFolders
+	sFoldersColl = ""
 	Set oSfa = SF_Utils._GetUnoService("FileAccess")
-	vSubFolders = oSfa.getFolderContents(sFolderName, True)
-	'	List includes files; remove them or adjust notations of folders
-	For i = 0 To UBound(vSubFolders)
-		sFolder = SF_FileSystem._ConvertFromUrl(vSubFolders(i) & "/")
-		If SF_FileSystem.FileExists(sFolder) Then vSubFolders(i) = "" Else vSubFolders(i) = sFolder
-		'	Reduce list to those passing the filter
-		If Len(Filter) > 0 And Len(vSubFolders(i)) > 0 Then
-			sFolder = SF_FileSystem.GetName(vSubFolders(i))
-			If Not SF_String.IsLike(sFolder, Filter) Then vSubFolders(i) = ""
-		End If
-	Next i
-	vSubFolders = SF_Array.TrimArray(vSubFolders)
+	SF_FileSystem._ScanFolder(cstFolders, sFoldersColl, FolderName, oSfa, Filter, IncludeSubfolders)
+
+	If Len(sFoldersColl) > Len(cstSEPARATOR) Then vSubFolders() = Split(Mid(sFoldersColl, Len(cstSEPARATOR) + 1), cstSEPARATOR)
 
 Finally:
 	SubFolders = vSubFolders
@@ -2240,6 +2221,115 @@ Public Function _IsDocFileSystem(psFile As String) As Boolean
 End Function	'	ScriptForge.SF_FileSystem._IsDocFileSystem
 
 REM -----------------------------------------------------------------------------
+Private Sub _ScanFolder(ByVal piTarget As Integer _
+							, ByRef psItemsColl As String _
+							, ByVal psFolderName As String _
+							, ByRef poSfa As Object _
+							, ByVal psFilter As String _
+							, ByVal pbIncludeSubFolders As Boolean _
+							)
+'''	Scan a folder and, when requested, its subfolders recursively.
+'''	The psItemsColl in-out argument concatenates, depending on the target,
+'''	either all files or all folders found.
+'''	The Sub calls itself recursively when relevant.
+'''	Args:
+'''		piTarget: 1 when caller routine = Files(), 2 when caller routine = SubFolders()
+'''			It determines the type of items to collect: files or folders
+'''		psItemsColl: the current and future list of folders or files (FileNaming format) separated with cstSEPARATOR
+'''		psFolderName: the folder to scan (FileNaming format)
+'''		poSfa: com.sun.star.ucb.SimpleFileAccess
+'''		psFilter: contains wildcards ("?" and "*") to limit the list to the relevant folders or files.
+'''			Zero-length string when not applicable.
+'''		pbIncludeSubfolders: when True, subfolders are explored too.
+
+Dim vSubFolders As Variant			'	Array of subfolders 1st level in URL notation
+Dim vFiles As Variant				'	Array of files present in psFolderName in FileNaming notation
+Dim lFiles As Long					'	Number of files found passing the filter
+Dim sFolderName As String			'	URL lias for psFolderName
+Dim sItem As String					'	Single folder or single file in FileNaming notation
+Dim sItemName As String				'	Base name of sItem
+Dim bFolder As Boolean				'	When True, the considered string points to a folder, not a file
+Dim bFilter As Boolean				'	When True, no filter or the filter is passed
+Dim i As Long		
+
+Check:
+	On Local Error Goto catch
+
+Try:
+	With poSfa
+
+		'	Get SubFolders, initialize files list
+		sFolderName = SF_FileSystem._ConvertToUrl(psFolderName)
+		vSubFolders = .getFolderContents(sFolderName, True)
+		If UBound(vSubFolders) < 0 Then Exit Sub
+		vFiles = Array()
+		If piTarget = cstFiles Then
+			lFiles = 0
+			ReDim vFiles(0 To UBound(vSubFolders))
+		End If
+
+		'	List includes files: remove them or adjust notations of folders
+		'	When piTarget = cstFiles, the list of files is stored in the vFiles() array
+		For i = 0 To UBound(vSubFolders)
+			sItem = SF_FileSystem._ConvertFromUrl(vSubFolders(i))
+			bFolder = .isFolder(vSubFolders(i))
+			Select Case piTarget
+				Case cstFiles
+					If bFolder Then
+						vSubFolders(i) = sItem & "/"
+					Else
+						'	Build list of files passing the filter
+						bFilter = ( Len(psFilter) = 0 )
+						If Not bFilter Then
+							sItemName = SF_FileSystem.GetName(sItem)
+							bFilter = SF_String.IsLike(sItemName, psFilter)
+						End If
+						If bFilter Then			'	Copy files from folders + files list
+							vFiles(lFiles) = sItem
+							lFiles = lFiles + 1
+						End If
+						vSubFolders(i) = ""		'	Keep folders only
+					End If
+				Case cstFolders
+					If bFolder Then vSubFolders(i) = sItem & "/" Else vSubFolders(i) = ""
+					'	Reduce list to those passing the filter
+					If Len(psFilter) > 0 And Len(vSubFolders(i)) > 0 Then
+						sItemName = SF_FileSystem.GetName(sItem)
+						If Not SF_String.IsLike(sItemName, psFilter) Then vSubFolders(i) = ""
+					End If
+			End Select
+		Next i
+		vSubFolders = SF_Array.TrimArray(vSubFolders)
+
+		'	Store the list of either files or subfolders in the global collection
+		Select Case piTarget
+			Case cstFiles
+				If lFiles > 0 Then
+					ReDim Preserve vFiles(0 To lFiles - 1)
+					psItemsColl = psItemsColl & cstSEPARATOR & Join(vFiles, cstSEPARATOR)
+				End If
+			Case cstFolders
+				If UBound(vSubFolders) >= 0 Then psItemsColl = psItemsColl & cstSEPARATOR & Join(vSubFolders, cstSEPARATOR)
+		End Select
+
+		'	Scan each subfolder when relevant
+		If pbIncludeSubfolders Then
+			For i = 0 To UBound(vSubFolders)
+				_ScanFolder(piTarget, psItemsColl, vSubFolders(i), poSfa, psFilter, True)
+			Next i
+		End If
+
+	End With
+
+Finally:
+	Exit Sub
+Catch:
+	SF_Exception.Clear()
+	psItemsColl = ""
+	GoTo Finally
+End Sub			'	ScriptForge.SF_FileSystem._ScanFolder
+
+REM -----------------------------------------------------------------------------
 Public Function _ParseUrl(psUrl As String) As Object
 '''	Returns a com.sun.star.util.URL structure based on the argument
 
@@ -2280,4 +2370,4 @@ Dim sFolder As String		'	Folder
 End Function	'	ScriptForge.SF_FileSystem._SFInstallFolder
 
 REM ============================================ END OF SCRIPTFORGE.SF_FileSystem
-</script:module>
+</script:module>
\ No newline at end of file
diff --git a/wizards/source/scriptforge/SF_TextStream.xba b/wizards/source/scriptforge/SF_TextStream.xba
index a5c1b09129de..3860bebd1b0a 100644
--- a/wizards/source/scriptforge/SF_TextStream.xba
+++ b/wizards/source/scriptforge/SF_TextStream.xba
@@ -722,4 +722,4 @@ Private Function _Repr() As String
 End Function	&apos;	ScriptForge.SF_TextStream._Repr
 
 REM ============================================ END OF SCRIPTFORGE.SF_TextStream
-</script:module>
+</script:module>
\ No newline at end of file
diff --git a/wizards/source/scriptforge/python/scriptforge.py b/wizards/source/scriptforge/python/scriptforge.py
index 631ac00eb0df..d073197a11a5 100644
--- a/wizards/source/scriptforge/python/scriptforge.py
+++ b/wizards/source/scriptforge/python/scriptforge.py
@@ -1127,8 +1127,8 @@ class SFScriptForge:
         def FileExists(self, filename):
             return self.ExecMethod(self.vbMethod, 'FileExists', filename)
 
-        def Files(self, foldername, filter = ''):
-            return self.ExecMethod(self.vbMethod, 'Files', foldername, filter)
+        def Files(self, foldername, filter = '', includesubfolders = False):
+            return self.ExecMethod(self.vbMethod, 'Files', foldername, filter, includesubfolders)
 
         def FolderExists(self, foldername):
             return self.ExecMethod(self.vbMethod, 'FolderExists', foldername)
@@ -1185,8 +1185,8 @@ class SFScriptForge:
         def PickFolder(self, defaultfolder = ScriptForge.cstSymEmpty, freetext = ''):
             return self.ExecMethod(self.vbMethod, 'PickFolder', defaultfolder, freetext)
 
-        def SubFolders(self, foldername, filter = ''):
-            return self.ExecMethod(self.vbMethod, 'SubFolders', foldername, filter)
+        def SubFolders(self, foldername, filter = '', includesubfolders = False):
+            return self.ExecMethod(self.vbMethod, 'SubFolders', foldername, filter, includesubfolders)
 
         @classmethod
         def _ConvertFromUrl(cls, filename):