common.h File Reference

The common library. More...

#include <functional>
#include <memory>
#include <wx/fileconf.h>
#include <wx/string.h>
#include <wx/process.h>

Go to the source code of this file.

Functions
wxString	SearchHelpFileFullPath (const wxString &aBaseName)
	Return the help file's full path. More...
bool	EnsureFileDirectoryExists (wxFileName *aTargetFullFileName, const wxString &aBaseFilename, REPORTER *aReporter=nullptr)
	Make aTargetFullFileName absolute and create the path of this file if it doesn't yet exist. More...
const wxString	ExpandEnvVarSubstitutions (const wxString &aString, const PROJECT *aProject)
	Replace any environment variable & text variable references with their values. More...
wxString	ExpandTextVars (const wxString &aSource, const std::function< bool(wxString *)> *aResolver)
	Expand '${var-name}' templates in text. More...
wxString	ExpandTextVars (const wxString &aSource, const PROJECT *aProject)
const wxString	ResolveUriByEnvVars (const wxString &aUri, PROJECT *aProject)
	Replace any environment and/or text variables in file-path uris (leaving network-path URIs alone). More...
long long	TimestampDir (const wxString &aDirPath, const wxString &aFilespec)
	A copy of ConvertFileTimeToWx() because wxWidgets left it as a static function private to src/common/filename.cpp. More...
bool	WarnUserIfOperatingSystemUnsupported ()
	Checks if the operating system is explicitly unsupported and displays a disclaimer message box. More...

Detailed Description

The common library.

Definition in file common.h.

Function Documentation

EnsureFileDirectoryExists()

bool EnsureFileDirectoryExists	(	wxFileName *	aTargetFullFileName,
		const wxString &	aBaseFilename,
		REPORTER *	aReporter = nullptr
	)

Make aTargetFullFileName absolute and create the path of this file if it doesn't yet exist.

Parameters

aTargetFullFileName	the wxFileName containing the full path and file name to modify. The path may be absolute or relative to aBaseFilename .
aBaseFilename	a full filename. Only its path is used to set the aTargetFullFileName path.
aReporter	a point to a REPORTER object use to show messages (can be NULL)

Returns

true if aOutputDir already exists or was successfully created.

Definition at line 327 of file common.cpp.

{
 wxString msg;
 wxString baseFilePath = wxFileName( aBaseFilename ).GetPath();
 
 // make aTargetFullFileName path, which is relative to aBaseFilename path (if it is not
 // already an absolute path) absolute:
 if( !aTargetFullFileName->MakeAbsolute( baseFilePath ) )
 {
 if( aReporter )
 {
 msg.Printf( _( "Cannot make path '%s' absolute with respect to '%s'." ),
 aTargetFullFileName->GetPath(),
 baseFilePath );
 aReporter->Report( msg, RPT_SEVERITY_ERROR );
 }
 
 return false;
 }
 
 // Ensure the path of aTargetFullFileName exists, and create it if needed:
 wxString outputPath( aTargetFullFileName->GetPath() );
 
 if( !wxFileName::DirExists( outputPath ) )
 {
 // Make every directory provided when the provided path doesn't exist
 if( wxFileName::Mkdir( outputPath, wxS_DIR_DEFAULT, wxPATH_MKDIR_FULL ) )
 {
 if( aReporter )
 {
 msg.Printf( _( "Output directory '%s' created." ), outputPath );
 aReporter->Report( msg, RPT_SEVERITY_INFO );
 return true;
 }
 }
 else
 {
 if( aReporter )
 {
 msg.Printf( _( "Cannot create output directory '%s'." ), outputPath );
 aReporter->Report( msg, RPT_SEVERITY_ERROR );
 }
 
 return false;
 }
 }
 
 return true;
}

References _, REPORTER::Report(), RPT_SEVERITY_ERROR, and RPT_SEVERITY_INFO.

Referenced by DIALOG_GEN_FOOTPRINT_POSITION::CreateAsciiFiles(), DIALOG_GEN_FOOTPRINT_POSITION::CreateGerberFiles(), SCH_PLOTTER::createPlotFileName(), DIALOG_EXPORT_SVG::ExportSVGFile(), DIALOG_GENDRILL::GenDrillAndMapFiles(), PLOT_CONTROLLER::OpenPlotfile(), and DIALOG_PLOT::Plot().

ExpandEnvVarSubstitutions()

const wxString ExpandEnvVarSubstitutions	(	const wxString &	aString,
		const PROJECT *	aProject
	)

Replace any environment variable & text variable references with their values.

Parameters

aString

a string containing (perhaps) references to env var

Returns

the expanded environment variable.

Definition at line 299 of file common.cpp.

{
 // wxGetenv( wchar_t* ) is not re-entrant on linux.
 // Put a lock on multithreaded use of wxGetenv( wchar_t* ), called from wxEpandEnvVars(),
 static std::mutex getenv_mutex;
 
 std::lock_guard<std::mutex> lock( getenv_mutex );
 
 // We reserve the right to do this another way, by providing our own member function.
 return KIwxExpandEnvVars( aString, aProject );
}

References KIwxExpandEnvVars().

Referenced by FILENAME_RESOLVER::addPath(), FILENAME_RESOLVER::checkEnvVarPath(), S3D_PLUGIN_MANAGER::checkPluginName(), DIALOG_GEN_FOOTPRINT_POSITION::CreateAsciiFiles(), DIALOG_GEN_FOOTPRINT_POSITION::CreateGerberFiles(), FILENAME_RESOLVER::createPathList(), DIALOG_EXPORT_SVG::ExportSVGFile(), DIALOG_GENDRILL::GenDrillAndMapFiles(), LIB_TABLE_ROW::GetFullURI(), DIALOG_PLOT_SCHEMATIC::getOutputPath(), TEXT_BUTTON_FILE_BROWSER::OnButtonClick(), PANEL_SYM_LIB_TABLE::onConvertLegacyLibraries(), DIALOG_GENDRILL::OnGenReportFile(), DIALOG_PLOT_SCHEMATIC::OnOutputDirectoryBrowseClicked(), DIALOG_EXPORT_SVG::OnOutputDirectoryBrowseClicked(), DIALOG_GEN_FOOTPRINT_POSITION::OnOutputDirectoryBrowseClicked(), DIALOG_GENDRILL::OnOutputDirectoryBrowseClicked(), DIALOG_PLOT::OnOutputDirectoryBrowseClicked(), DIALOG_PAGES_SETTINGS::OnWksFileSelection(), PLOT_CONTROLLER::OpenPlotfile(), DIALOG_PLOT::Plot(), SIM_LIB_MGR::ResolveLibraryPath(), FILENAME_RESOLVER::ResolvePath(), DS_DATA_MODEL::ResolvePath(), ResolveUriByEnvVars(), S3D_CACHE::Set3DConfigDir(), FILENAME_RESOLVER::Set3DConfigDir(), FILENAME_RESOLVER::SetProject(), FILENAME_RESOLVER::ShortenPath(), ERC_TESTER::TestTextVars(), and NETLIST_EXPORTER_SPICE::writeInclude().

ExpandTextVars() [1/2]

wxString ExpandTextVars	(	const wxString &	aSource,
		const PROJECT *	aProject
	)

Definition at line 58 of file common.cpp.

{
 std::function<bool( wxString* )> projectResolver =
 [&]( wxString* token ) -> bool
 {
 return aProject->TextVarResolver( token );
 };
 
 return ExpandTextVars( aSource, &projectResolver );
}

References ExpandTextVars(), and PROJECT::TextVarResolver().

Referenced by AddGerberX2Header(), GERBER_JOBFILE_WRITER::addJSONGeneralSpecs(), DS_DRAW_ITEM_LIST::BuildFullText(), DIALOG_GEN_FOOTPRINT_POSITION::CreateAsciiFiles(), DIALOG_GEN_FOOTPRINT_POSITION::CreateGerberFiles(), CreateHeaderInfoData(), SCH_PLOTTER::createPDFFile(), KIGFX::expandLibItemTextVars(), ExpandTextVars(), DIALOG_EXPORT_SVG::ExportSVGFile(), DIALOG_GENDRILL::GenDrillAndMapFiles(), DIALOG_PLOT_SCHEMATIC::getOutputPath(), SCH_FIELD::GetShownText(), SCH_LABEL_BASE::GetShownText(), SCH_TEXT::GetShownText(), SCH_TEXTBOX::GetShownText(), FP_TEXT::GetShownText(), FP_TEXTBOX::GetShownText(), PCB_TEXT::GetShownText(), PCB_TEXTBOX::GetShownText(), NETLIST_EXPORTER_XML::makeDesignHeader(), DIALOG_PLOT::OnOutputDirectoryBrowseClicked(), PLOT_CONTROLLER::OpenPlotfile(), DIALOG_PLOT::Plot(), ResolveUriByEnvVars(), and TITLE_BLOCK::TextVarResolver().

ExpandTextVars() [2/2]

wxString ExpandTextVars	(	const wxString &	aSource,
		const std::function< bool(wxString *)> *	aResolver
	)

Expand '${var-name}' templates in text.

Definition at line 70 of file common.cpp.

{
 wxString newbuf;
 size_t sourceLen = aSource.length();
 
 newbuf.Alloc( sourceLen ); // best guess (improves performance)
 
 for( size_t i = 0; i < sourceLen; ++i )
 {
 if( aSource[i] == '$' && i + 1 < sourceLen && aSource[i+1] == '{' )
 {
 wxString token;
 
 for( i = i + 2; i < sourceLen; ++i )
 {
 if( aSource[i] == '}' )
 break;
 else
 token.append( aSource[i] );
 }
 
 if( token.IsEmpty() )
 continue;
 
 if( aResolver && (*aResolver)( &token ) )
 {
 newbuf.append( token );
 }
 else
 {
 // Token not resolved: leave the reference unchanged
 newbuf.append( "${" + token + "}" );
 }
 }
 else
 {
 newbuf.append( aSource[i] );
 }
 }
 
 return newbuf;
}

ResolveUriByEnvVars()

const wxString ResolveUriByEnvVars	(	const wxString &	aUri,
		PROJECT *	aProject
	)

Replace any environment and/or text variables in file-path uris (leaving network-path URIs alone).

Definition at line 312 of file common.cpp.

{
 wxString uri = ExpandTextVars( aUri, aProject );
 
 // URL-like URI: return as is.
 wxURL url( uri );
 
 if( url.GetError() == wxURL_NOERR )
 return uri;
 
 // Otherwise, the path points to a local file. Resolve environment variables if any.
 return ExpandEnvVarSubstitutions( aUri, aProject );
}

References ExpandEnvVarSubstitutions(), and ExpandTextVars().

Referenced by GetAssociatedDocument().

SearchHelpFileFullPath()

wxString SearchHelpFileFullPath

(

const wxString &

aBaseName

)

Return the help file's full path.

Return the full path and name (including extension) of the given KiCad help file. It is expected to be found in a subfolder help/<LANG>/ in one of the system paths. Supported file types are *.html and *.pdf. If no such file is available for the current locale, an attempt to find the English version is made. The search order for <LANG> is: 1) canonical form (e.g., "fr_FR"), 2) short form (e.g., "fr"), and 3) "en".

Parameters

aBaseName

is the name of the help file to search for (without extension).

Returns

the full path and filename if aBaseName is found, else wxEmptyString.

Definition at line 32 of file searchhelpfilefullpath.cpp.

{
 SEARCH_STACK basePaths;
 wxString helpFile;
 
 // help files are most likely located in the documentation install path
 basePaths.Add( PATHS::GetDocumentationPath() );
 
#ifndef __WIN32__
 // just in case, add all known system directories to the search stack
 SystemDirsAppend( &basePaths );
#endif
 
#if defined( DEBUG )
 basePaths.Show( wxString( __func__ ) + wxS( ": basePaths" ) );
#endif
 
 // By default, the documentation from kicad-doc is installed to a folder called "help" with
 // subdirectories for all supported languages. Although this can be changed at build-time by
 // overwriting ${KICAD_DOC_PATH}, the best guess KiCad can make is that help files are always
 // located in a folder named "help". If no translation matching the current locale settings is
 // available, the English version will be returned instead.
 
 wxLocale* currentLocale = Pgm().GetLocale();
 wxArrayString localeNameDirs;
 
 // canonical form of the current locale (e.g., "fr_FR")
 localeNameDirs.Add( currentLocale->GetCanonicalName() );
 
 // short form of the current locale (e.g., "fr")
 // wxLocale::GetName() does not always return the short form
 localeNameDirs.Add( currentLocale->GetName().BeforeLast( wxS( '_' ) ) );
 
 // plain English (in case a localised version of the help file cannot be found)
 localeNameDirs.Add( wxS( "en" ) );
 
 for( wxString& locale : localeNameDirs )
 {
 SEARCH_STACK docPaths;
 
 for( wxString& base : basePaths )
 {
 wxFileName path( base, wxEmptyString );
 
 // add <base>/help/<locale>/
 path.AppendDir( wxS( "help" ) );
 path.AppendDir( locale );
 docPaths.AddPaths( path.GetPath() );
 
 // add <base>/doc/help/<locale>/
 path.InsertDir( path.GetDirCount() - 2, wxS( "doc" ) );
 docPaths.AddPaths( path.GetPath() );
 
 // add <base>/doc/kicad/help/<locale>/
 path.InsertDir( path.GetDirCount() - 2, wxS( "kicad" ) );
 docPaths.AddPaths( path.GetPath() );
 }
 
#if defined( DEBUG )
 docPaths.Show( wxString( __func__ ) + wxS( ": docPaths (" ) + locale + wxS( ")" ) );
#endif
 
 // search HTML first, as it is the preferred format for help files
 wxLogTrace( tracePathsAndFiles, wxS( "Checking SEARCH_STACK for file %s.html" ),
 aBaseName );
 helpFile = docPaths.FindValidPath( aBaseName + wxS( ".html" ) );
 
 if( !helpFile.IsEmpty() )
 {
 // prepend URI protocol to open the file in a browser
 helpFile = wxS( "file://" ) + helpFile;
 break;
 }
 
 // search PDF only when no corresponding HTML file was found
 wxLogTrace( tracePathsAndFiles, wxS( "Checking SEARCH_STACK for file %s.pdf" ), aBaseName );
 helpFile = docPaths.FindValidPath( aBaseName + wxS( ".pdf" ) );
 
 if( !helpFile.IsEmpty() )
 break;
 }
 
 return helpFile;
}

References SEARCH_STACK::AddPaths(), PATHS::GetDocumentationPath(), path, Pgm(), SystemDirsAppend(), and tracePathsAndFiles.

Referenced by COMMON_CONTROL::ShowHelp().

TimestampDir()

long long TimestampDir	(	const wxString &	aDirPath,
		const wxString &	aFilespec
	)

A copy of ConvertFileTimeToWx() because wxWidgets left it as a static function private to src/common/filename.cpp.

This routine offers SIGNIFICANT performance benefits over using wxWidgets to gather timestamps from matching files in a directory.

Parameters

aDirPath	is the directory to search.
aFilespec	is a (wildcarded) file spec to match against.

Returns

a hash of the last-mod-dates of all matching files in the directory.

Definition at line 536 of file common.cpp.

{
 long long timestamp = 0;
 
#if defined( __WIN32__ )
 // Win32 version.
 // Save time by not searching for each path twice: once in wxDir.GetNext() and once in
 // wxFileName.GetModificationTime(). Also cuts out wxWidgets' string-matching and case
 // conversion by staying on the MSW side of things.
 std::wstring filespec( aDirPath.t_str() );
 filespec += '\\';
 filespec += aFilespec.t_str();
 
 WIN32_FIND_DATA findData;
 wxDateTime lastModDate;
 
 HANDLE fileHandle = ::FindFirstFile( filespec.data(), &findData );
 
 if( fileHandle != INVALID_HANDLE_VALUE )
 {
 do
 {
 ConvertFileTimeToWx( &lastModDate, findData.ftLastWriteTime );
 timestamp += lastModDate.GetValue().GetValue();
 
 // Get the file size (partial) as well to check for sneaky changes.
 timestamp += findData.nFileSizeLow;
 }
 while ( FindNextFile( fileHandle, &findData ) != 0 );
 }
 
 FindClose( fileHandle );
#else
 // POSIX version.
 // Save time by not converting between encodings -- do everything on the file-system side.
 std::string filespec( aFilespec.fn_str() );
 std::string dir_path( aDirPath.fn_str() );
 
 DIR* dir = opendir( dir_path.c_str() );
 
 if( dir )
 {
 for( dirent* dir_entry = readdir( dir ); dir_entry; dir_entry = readdir( dir ) )
 {
 if( !matchWild( filespec.c_str(), dir_entry->d_name, true ) )
 continue;
 
 std::string entry_path = dir_path + '/' + dir_entry->d_name;
 struct stat entry_stat;
 
 if( wxCRT_Lstat( entry_path.c_str(), &entry_stat ) == 0 )
 {
 // Timestamp the source file, not the symlink
 if( S_ISLNK( entry_stat.st_mode ) ) // wxFILE_EXISTS_SYMLINK
 {
 char buffer[ PATH_MAX + 1 ];
 ssize_t pathLen = readlink( entry_path.c_str(), buffer, PATH_MAX );
 
 if( pathLen > 0 )
 {
 struct stat linked_stat;
 buffer[ pathLen ] = '\0';
 entry_path = dir_path + buffer;
 
 if( wxCRT_Lstat( entry_path.c_str(), &linked_stat ) == 0 )
 {
 entry_stat = linked_stat;
 }
 else
 {
 // if we couldn't lstat the linked file we'll have to just use
 // the symbolic link info
 }
 }
 }
 
 if( S_ISREG( entry_stat.st_mode ) ) // wxFileExists()
 {
 timestamp += entry_stat.st_mtime * 1000;
 
 // Get the file size as well to check for sneaky changes.
 timestamp += entry_stat.st_size;
 }
 }
 else
 {
 // if we couldn't lstat the file itself all we can do is use the name
 timestamp += (signed) std::hash<std::string>{}( std::string( dir_entry->d_name ) );
 }
 }
 
 closedir( dir );
 }
#endif
 
 return timestamp;
}

References matchWild().

Referenced by GPCB_FPL_CACHE::GetTimestamp(), and FP_CACHE::GetTimestamp().

WarnUserIfOperatingSystemUnsupported()

bool WarnUserIfOperatingSystemUnsupported

(

)

Checks if the operating system is explicitly unsupported and displays a disclaimer message box.

Returns

true if the operating system is unsupported

Definition at line 635 of file common.cpp.

{
 if( !KIPLATFORM::APP::IsOperatingSystemUnsupported() )
 return false;
 
 wxMessageDialog dialog( nullptr, _( "This operating system is not supported "
 "by KiCad and its dependencies." ),
 _( "Unsupported Operating System" ),
 wxOK | wxICON_EXCLAMATION );
 
 dialog.SetExtendedMessage( _( "Any issues with KiCad on this system cannot "
 "be reported to the official bugtracker." ) );
 dialog.ShowModal();
 
 return true;
}

References _, and KIPLATFORM::APP::IsOperatingSystemUnsupported().

Referenced by PGM_BASE::InitPgm(), and COMMON_CONTROL::ReportBug().