#include <map>
#include <filesystem>
#include <functional>
#include <memory>
#include <string>
#include <unordered_set>
#include <kicommon.h>
#include <wx/arrstr.h>
#include <wx/dir.h>
#include <wx/filename.h>
#include <wx/process.h>
#include <wx/zipstrm.h>

Classes
class	SCOPED_TEMP_PATH
	A temporary file or directory that is removed when the object goes out of scope. More...

class	DIR_LOOP_GUARD

Macros
#define	UNIX_STRING_DIR_SEP wxT( "/" )

#define	WIN_STRING_DIR_SEP wxT( "\\" )

Typedefs
using	ARCHIVE_STREAM_FACTORY = std::function<std::unique_ptr<wxOutputStream>( wxFFile& )>

Enumerations
enum class	ARCHIVE_FORMAT { ZIP , TGZ }

enum class	DIR_LOOP_POLICY { CONFINE_TO_ROOT , BLOCK_ROOT_ESCAPE }

Functions
KICOMMON_API std::filesystem::path	ToFsPath (const wxString &aPath)
	Give aPath to std::filesystem without a detour through the C locale.

KICOMMON_API wxString	FromFsPath (const std::filesystem::path &aPath)

KICOMMON_API bool	WriteDirectoryArchive (const wxString &aSourceDir, wxOutputStream &aOut, ARCHIVE_FORMAT aFormat, const wxString &aTopDir)
	Write directory entries in sorted archive path order, using the archive root when aTopDir is empty.

KICOMMON_API bool	WriteDirectoryArchive (const wxString &aSourceDir, const wxString &aArchive, ARCHIVE_FORMAT aFormat, const wxString &aTopDir, wxString *aError=nullptr, const ARCHIVE_STREAM_FACTORY &aOpen={})
	Replace the archive atomically after writing and closing a sibling temporary file.

KICOMMON_API bool	OpenPDF (const wxString &file)
	Run the PDF viewer and display a PDF file.

KICOMMON_API void	KiCopyFile (const wxString &aSrcPath, const wxString &aDestPath, wxString &aErrors)

KICOMMON_API void	CopySexprFile (const wxString &aSrcPath, const wxString &aDestPath, std::function< bool(const std::string &token, wxString &value)> aCallback, wxString &aErrors)

KICOMMON_API int	ExecuteFile (const wxString &aEditorName, const wxString &aFileName=wxEmptyString, wxProcess *aCallback=nullptr, bool aFileForKicad=true)
	Call the executable file aEditorName with the parameter aFileName.

KICOMMON_API int	ExecuteCommandThroughShell (const wxString &aCommand, wxProcess *aProcess=nullptr)
	Run a user-supplied command line through the platform shell so glob expansion, pipes, and other shell features work consistently.

KICOMMON_API void	QuoteString (wxString &string)
	Add un " to the start and the end of string (if not already done).

KICOMMON_API wxString	FindKicadFile (const wxString &shortname)
	Search the executable file shortname in KiCad binary path and return full file name if found or shortname if the kicad binary path is kicad/bin.

KICOMMON_API wxString	QuoteFullPath (wxFileName &fn, wxPathFormat format=wxPATH_NATIVE)
	Quote return value of wxFileName::GetFullPath().

KICOMMON_API bool	RmDirRecursive (const wxString &aDirName, wxString *aErrors=nullptr)
	Remove the directory aDirName and all its contents including subdirectories and their files.

KICOMMON_API bool	CopyDirectory (const wxString &aSourceDir, const wxString &aDestDir, const std::vector< wxString > &aOverwriteExclusions, wxString &aErrors)
	Copy a directory and its contents to another directory.

KICOMMON_API bool	CopyFilesOrDirectory (const wxString &aSourceDir, const wxString &aDestDir, bool aAllowOverwrite, wxString &aErrors, std::vector< wxString > &aPathsWritten)

KICOMMON_API bool	AddDirectoryToZip (wxZipOutputStream &aZip, const wxString &aSourceDir, wxString &aErrors, const wxString &aParentDir="")
	Add a directory and its contents to a zip file.

KICOMMON_API void	CollectFilesLoopSafe (const wxString &aRoot, wxArrayString &aFiles, const wxString &aFileSpec=wxEmptyString, int aFlags=wxDIR_DEFAULT)
	Recursively collect every file under aRoot, deduplicating subdirectories by their resolved path.

KICOMMON_API void	CollectSubdirsLoopSafe (const wxString &aRoot, wxArrayString &aDirs, int aFlags=wxDIR_DIRS)
	Recursively collect every subdirectory under aRoot using the same loop detection as CollectFilesLoopSafe().

Macro Definition Documentation

◆ UNIX_STRING_DIR_SEP

#define UNIX_STRING_DIR_SEP wxT( "/" )

Note: Do we really need these defined?

Definition at line 40 of file gestfich.h.

Referenced by GetAssociatedDocument(), PGM_BASE::InitPgm(), and PCB_EDIT_FRAME::OpenProjectFiles().

◆ WIN_STRING_DIR_SEP

#define WIN_STRING_DIR_SEP wxT( "\\" )

Definition at line 41 of file gestfich.h.

Referenced by GetAssociatedDocument(), PGM_BASE::InitPgm(), and PCB_EDIT_FRAME::OpenProjectFiles().

Typedef Documentation

◆ ARCHIVE_STREAM_FACTORY

using ARCHIVE_STREAM_FACTORY = std::function<std::unique_ptr<wxOutputStream>( wxFFile& )>

Definition at line 81 of file gestfich.h.

Enumeration Type Documentation

◆ ARCHIVE_FORMAT

enum class ARCHIVE_FORMAT

strong

Enumerator
ZIP
TGZ

Definition at line 49 of file gestfich.h.

◆ DIR_LOOP_POLICY

enum class DIR_LOOP_POLICY

strong

Enumerator
CONFINE_TO_ROOT
BLOCK_ROOT_ESCAPE

Definition at line 249 of file gestfich.h.

Function Documentation

◆ AddDirectoryToZip()

KICOMMON_API bool AddDirectoryToZip	(	wxZipOutputStream &	aZip,
		const wxString &	aSourceDir,
		wxString &	aErrors,
		const wxString &	aParentDir = "" )

Add a directory and its contents to a zip file.

Parameters

aZip	is the zip file to add to.
aSourceDir	is the directory to add.
aErrors	is a string to append any errors to.
aParentDir	is the parent directory to add to the zip file.

Definition at line 669 of file gestfich.cpp.

References _, and AddDirectoryToZip().

Referenced by AddDirectoryToZip(), and JOBS_OUTPUT_ARCHIVE::HandleOutputs().

◆ CollectFilesLoopSafe()

KICOMMON_API void CollectFilesLoopSafe	(	const wxString &	aRoot,
		wxArrayString &	aFiles,
		const wxString &	aFileSpec = wxEmptyString,
		int	aFlags = wxDIR_DEFAULT )

Recursively collect every file under aRoot, deduplicating subdirectories by their resolved path.

Legitimate one-level symlinks resolve normally, but recursive symlinks (a Wine dosdevices/z: -> / loop, a self-referencing . link, etc.) are visited at most once instead of recursing until OOM. This is a loop-safe replacement for wxDir::GetAllFiles() when scanning user-controlled directory trees.

Parameters

aRoot	is the directory to walk.
aFiles	receives the full path of every matching file found.
aFileSpec	is an optional wildcard filter (e.g. `*.step`); empty matches all.
aFlags	is the wxDir traversal flag set; defaults to wxDIR_DEFAULT to match wxDir::GetAllFiles(). Pass `wxDIR_FILES \| wxDIR_DIRS` to exclude hidden entries. wxDIR_FILES and wxDIR_DIRS are always implied so recursion and file collection happen regardless.

Definition at line 1110 of file gestfich.cpp.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), MODEL_SUBSTITUTION::STEP_CATALOG::Build(), PCB_IO_GEDA::DeleteLibrary(), PCB_IO_KICAD_SEXPR::DeleteLibrary(), PCB_IO_SPRINT_LAYOUT::FootprintEnumerate(), and DIALOG_MIGRATE_3D_MODELS::scanDirectory().

◆ CollectSubdirsLoopSafe()

KICOMMON_API void CollectSubdirsLoopSafe	(	const wxString &	aRoot,
		wxArrayString &	aDirs,
		int	aFlags = wxDIR_DIRS )

Recursively collect every subdirectory under aRoot using the same loop detection as CollectFilesLoopSafe().

Loop-safe replacement for wxDir::GetAllFiles() called with the wxDIR_DIRS flag.

Parameters

aRoot	is the directory to walk.
aDirs	receives the full path of every subdirectory found.
aFlags	is the wxDir traversal flag set; defaults to wxDIR_DIRS (hidden directories excluded). Pass `wxDIR_DIRS \| wxDIR_HIDDEN` to include them. wxDIR_DIRS is always implied.

Definition at line 1120 of file gestfich.cpp.

Referenced by BOOST_AUTO_TEST_CASE(), and DESIGN_BLOCK_IO::DeleteLibrary().

◆ CopyDirectory()

KICOMMON_API bool CopyDirectory	(	const wxString &	aSourceDir,
		const wxString &	aDestDir,
		const std::vector< wxString > &	aOverwriteExclusions,
		wxString &	aErrors )

Copy a directory and its contents to another directory.

Parameters

aSourceDir	is the directory to copy.
aDestDir	is the directory to copy to.
aOverwriteExclusions
aErrors	is a string to append any errors to.

Definition at line 492 of file gestfich.cpp.

References _, alg::contains(), and CopyDirectory().

Referenced by CopyDirectory(), and JOBS_OUTPUT_FOLDER::HandleOutputs().

◆ CopyFilesOrDirectory()

KICOMMON_API bool CopyFilesOrDirectory	(	const wxString &	aSourceDir,
		const wxString &	aDestDir,
		bool	aAllowOverwrite,
		wxString &	aErrors,
		std::vector< wxString > &	aPathsWritten )

Definition at line 546 of file gestfich.cpp.

References _, and CopyFilesOrDirectory().

Referenced by CopyFilesOrDirectory(), and JOBS_RUNNER::runSpecialCopyFiles().

◆ CopySexprFile()

KICOMMON_API void CopySexprFile	(	const wxString &	aSrcPath,
		const wxString &	aDestPath,
		std::function< bool(const std::string &token, wxString &value)>	aCallback,
		wxString &	aErrors )

Parameters

	aSrcPath	is the full filename of the source.
[in]	aDestPath	is the full filename of the target.
[in]	aCallback	a facility to allow modification of the values of particular tokens. Normally used to update paths in the copied document.
[out]	aErrors	a wxString to append any errors to.

Definition at line 375 of file gestfich.cpp.

References PRETTIFIED_FILE_OUTPUTFORMATTER::Finish(), SEXPR::PARSER::ParseFromFile(), OUTPUTFORMATTER::Print(), TO_UTF8, and traverseSEXPR().

Referenced by PCB::IFACE::SaveFileAs(), and SCH::IFACE::SaveFileAs().

◆ ExecuteCommandThroughShell()

KICOMMON_API int ExecuteCommandThroughShell	(	const wxString &	aCommand,
		wxProcess *	aProcess = nullptr )

Run a user-supplied command line through the platform shell so glob expansion, pipes, and other shell features work consistently.

On Windows the command is wrapped as cmd.exe /d /s /c "<cmd>" so that absolute paths containing spaces or quotes survive cmd.exe's quote handling intact. On POSIX the command is handed to /bin/sh -c as a single argument.

Parameters

aCommand	the command line exactly as entered by the user.
aProcess	an optional wxProcess for the call; pass a Redirect()ed process to capture output.

Returns: the process exit code, or -1 if the command could not be executed.

Definition at line 277 of file gestfich.cpp.

References flag.

Referenced by executeViaShell(), and JOBS_RUNNER::runSpecialExecute().

◆ ExecuteFile()

KICOMMON_API int ExecuteFile	(	const wxString &	aEditorName,
		const wxString &	aFileName = wxEmptyString,
		wxProcess *	aCallback = nullptr,
		bool	aFileForKicad = true )

Call the executable file aEditorName with the parameter aFileName.

Parameters

[in]	aEditorName	is the full filename for the binary.
[in]	aFileName	is the full filename of the file to open.
[in]	aCallback	a wxProcess* for the call.
	aFileForKicad	a boolean to flag if aFileName runs with a KiCad binary. In this case aFileName is a shortname and FindKicadFile() is called to return the path. In the other case, aFileName is a full file name (passed prefixed with the path).

Definition at line 166 of file gestfich.cpp.

References _, DisplayErrorMessage(), and FindKicadFile().

Referenced by COMMON_CONTROL::Execute(), DIALOG_CONFIG_EQUFILES::OnEditEquFile(), DIALOG_BOM::OnEditGenerator(), SCH_EDIT_FRAME::OnOpenPcbnew(), PROJECT_TREE_PANE::onOpenSelectedFileWithTextEditor(), FOOTPRINT_EDITOR_CONTROL::OpenWithTextEditor(), SYMBOL_EDITOR_CONTROL::OpenWithTextEditor(), BOARD_EDITOR_CONTROL::ShowEeschema(), and GERBVIEW_INSPECTION_TOOL::ShowSource().

◆ FindKicadFile()

KICOMMON_API wxString FindKicadFile ( const wxString & shortname )

Search the executable file shortname in KiCad binary path and return full file name if found or shortname if the kicad binary path is kicad/bin.

The binary path is found from:

binary path.
KICAD environment variable.
c:\kicad or /usr/local/kicad (the default).
default binary path.

Definition at line 67 of file gestfich.cpp.

References arrayDim(), PGM_BASE::GetExecutablePath(), PGM_BASE::GetKicadEnvVariable(), and Pgm().

Referenced by API_PLUGIN_MANAGER::doInvokeAction(), KICAD_MANAGER_FRAME::DoWithAcceptedFiles(), ExecuteFile(), PYTHON_MANAGER::FindPythonInterpreter(), API_HANDLER_COMMON::handleGetKiCadBinaryPath(), and API_PLUGIN_MANAGER::processNextJob().

◆ FromFsPath()

KICOMMON_API wxString FromFsPath ( const std::filesystem::path & aPath )

Definition at line 919 of file gestfich.cpp.

Referenced by generateOneODBPackage().

◆ KiCopyFile()

KICOMMON_API void KiCopyFile	(	const wxString &	aSrcPath,
		const wxString &	aDestPath,
		wxString &	aErrors )

Parameters

	aSrcPath	is the full filename of the source.
[in]	aDestPath	is the full filename of the target.
[out]	aErrors	a wxString to append any errors to.

Definition at line 348 of file gestfich.cpp.

References _.

Referenced by MIGRATION_TRAVERSER::OnFile(), PROJECT_TREE_TRAVERSER::OnFile(), GERBV::IFACE::SaveFileAs(), PGE::IFACE::SaveFileAs(), HEADLESS_PCB_CONTEXT::SavePcbCopy(), PCB_EDIT_FRAME::SavePcbCopy(), and PCB_EDIT_FRAME::SavePcbFile().

◆ OpenPDF()

KICOMMON_API bool OpenPDF ( const wxString & file )

Run the PDF viewer and display a PDF file.

Parameters

file	the PDF file to open.

Return values

true	if PDF viewer found.
false	if no PDF viewer found.

Definition at line 312 of file gestfich.cpp.

References _, DisplayErrorMessage(), PGM_BASE::GetPdfBrowserName(), LaunchExternal(), Pgm(), and PGM_BASE::ReadPdfBrowserInfos().

Referenced by PROJECT_TREE_ITEM::Activate(), GetAssociatedDocument(), and DIALOG_PLOT_SCHEMATIC::plotSchematic().

◆ QuoteFullPath()

KICOMMON_API wxString QuoteFullPath	(	wxFileName &	fn,
		wxPathFormat	format = wxPATH_NATIVE )

extern

Quote return value of wxFileName::GetFullPath().

This allows file name paths with spaces to be used as parameters to ProcessExecute function calls.

Parameters

fn	is the filename to wrap.
format	if provided, can be used to transform the nature of the wrapped filename to another platform.

Definition at line 438 of file gestfich.cpp.

◆ QuoteString()

KICOMMON_API void QuoteString ( wxString & string )

Add un " to the start and the end of string (if not already done).

Parameters

string string to modify.

Definition at line 57 of file gestfich.cpp.

◆ RmDirRecursive()

KICOMMON_API bool RmDirRecursive	(	const wxString &	aDirName,
		wxString *	aErrors = nullptr )

Remove the directory aDirName and all its contents including subdirectories and their files.

Definition at line 444 of file gestfich.cpp.

References _, and path.

Referenced by LIBGIT_BACKEND::RemoveVCS(), and DIALOG_GIT_REPOSITORY::~DIALOG_GIT_REPOSITORY().

◆ ToFsPath()

KICOMMON_API std::filesystem::path ToFsPath ( const wxString & aPath )

Give aPath to std::filesystem without a detour through the C locale.

Definition at line 909 of file gestfich.cpp.

Referenced by BOOST_FIXTURE_TEST_CASE(), DIR_LOOP_GUARD::DIR_LOOP_GUARD(), generateOneODBPackage(), and DIR_LOOP_GUARD::ShouldDescend().

◆ WriteDirectoryArchive() [1/2]

KICOMMON_API bool WriteDirectoryArchive	(	const wxString &	aSourceDir,
		const wxString &	aArchive,
		ARCHIVE_FORMAT	aFormat,
		const wxString &	aTopDir,
		wxString *	aError = nullptr,
		const ARCHIVE_STREAM_FACTORY &	aOpen = {} )

Replace the archive atomically after writing and closing a sibling temporary file.

Definition at line 831 of file gestfich.cpp.

References _, KIPLATFORM::IO::CLOUD_SYNC_BUFFER_SIZE, KIPLATFORM::IO::CommitTempFile(), KIPLATFORM::IO::FlushToDisk(), KIPLATFORM::IO::OpenUniqueSiblingTempFile(), and WriteDirectoryArchive().

◆ WriteDirectoryArchive() [2/2]

KICOMMON_API bool WriteDirectoryArchive	(	const wxString &	aSourceDir,
		wxOutputStream &	aOut,
		ARCHIVE_FORMAT	aFormat,
		const wxString &	aTopDir )

Write directory entries in sorted archive path order, using the archive root when aTopDir is empty.

Definition at line 793 of file gestfich.cpp.

References DIR_LOOP_GUARD::IsRooted(), and TGZ.

Referenced by GenerateIpc2581File(), generateOneODBPackage(), and WriteDirectoryArchive().

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ UNIX_STRING_DIR_SEP

◆ WIN_STRING_DIR_SEP

Typedef Documentation

◆ ARCHIVE_STREAM_FACTORY

Enumeration Type Documentation

◆ ARCHIVE_FORMAT

◆ DIR_LOOP_POLICY

Function Documentation

◆ AddDirectoryToZip()

◆ CollectFilesLoopSafe()

◆ CollectSubdirsLoopSafe()

◆ CopyDirectory()

◆ CopyFilesOrDirectory()

◆ CopySexprFile()

◆ ExecuteCommandThroughShell()

◆ ExecuteFile()

◆ FindKicadFile()

◆ FromFsPath()

◆ KiCopyFile()

◆ OpenPDF()

◆ QuoteFullPath()

◆ QuoteString()

◆ RmDirRecursive()

◆ ToFsPath()

◆ WriteDirectoryArchive() [1/2]

◆ WriteDirectoryArchive() [2/2]