[Scummvm-git-logs] scummvm master -> 5c49468ecdb2ad4d343021e03d03a77b48849e08

Sat Sep 24 17:23:04 UTC 2022

This automated email contains information about 1 new commit which have been
pushed to the 'scummvm' repo located at https://github.com/scummvm/scummvm .

Summary:
5c49468ecd COMMON: Added comments to indicate ScummVM forbidden equivalents


Commit: 5c49468ecdb2ad4d343021e03d03a77b48849e08
    https://github.com/scummvm/scummvm/commit/5c49468ecdb2ad4d343021e03d03a77b48849e08
Author: Paul Gilbert (dreammaster at scummvm.org)
Date: 2022-09-24T10:22:55-07:00

Commit Message:
COMMON: Added comments to indicate ScummVM forbidden equivalents

Changed paths:
    common/forbidden.h

diff --git a/common/forbidden.h b/common/forbidden.h
index 80ad4d1dee7..b3148a2a941 100644
--- a/common/forbidden.h
+++ b/common/forbidden.h
@@ -54,131 +54,166 @@
  * we try to make clear what is causing the error.
  */
 
+// Use debug and warning in common/textconsole.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_printf
 #undef printf
 #define printf	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use g_system->getSaveFileManager()->openForSaving
+// to create output streams and use the stream's methods
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fprintf
 #undef fprintf
 #define fprintf	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::String::format to format strings,
+// and then debug or warning to output to console
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_vprintf
 #undef vprintf
 #define vprintf	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::String::format to format strings,
+// and then use the save file manager's methods to write
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_vfprintf
 #undef vfprintf
 #define vfprintf	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_FILE
 #undef FILE
 #define FILE	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use g_system->getEventManager()->pollEvent to
+// get events, one type of which is keyboard events
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_stdin
 #undef stdin
 #define stdin	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use debug and warning in common/textconsole.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_stdout
 #undef stdout
 #define stdout	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use debug and warning in common/textconsole.h
+// ScummVM also has an error method, but this also
+// exits the program immediately
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_stderr
 #undef stderr
 #define stderr	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fopen
 #undef fopen
 #define fopen(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fclose
 #undef fclose
 #define fclose(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fread
 #undef fread
 #define fread(a,b,c,d)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fwrite
 #undef fwrite
 #define fwrite(a,b,c,d)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fseek
 #undef fseek
 #define fseek(a,b,c)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_ftell
 #undef ftell
 #define ftell(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_feof
 #undef feof
 #define feof(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fgetc
 #undef fgetc
 #define fgetc(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// For writing to files use the save file manager
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fputc
 #undef fputc
 #define fputc(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::File in common/file.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fgets
 #undef fgets
 #define fgets(a,b,c)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// For writing to files use the save file manager
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_fputs
 #undef fputs
 #define fputs(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use g_system->getEventManager()->pollEvent to
+// get events, one type of which is keyboard events
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_getc
 #undef getc
 #define getc(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use debug and warning in common/textconsole.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_putc
 #undef putc
 #define putc(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use g_system->getEventManager()->pollEvent to
+// get events, one type of which is keyboard events
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_gets
 #undef gets
 #define gets(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use debug and warning in common/textconsole.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_puts
 #undef puts
 #define puts(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use g_system->getEventManager()->pollEvent to
+// get events, one type of which is keyboard events
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_getchar
 #undef getchar
 #define getchar()	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use debug and warning in common/textconsole.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_putchar
 #undef putchar
 #define putchar(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// No equivalent in ScummVM
 // mingw-w64 uses [set|long]jmp in system headers
 #if !defined __MINGW64__ && ! defined __MINGW32__
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_setjmp
@@ -186,42 +221,59 @@
 #define setjmp(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// No equivalent in ScummVM
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_longjmp
 #undef longjmp
 #define longjmp(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 #endif // __MINGW64__ __MINGW32__
 
+// No equivalent in ScummVM. The functionality of
+// any system calls need to reimplemented as code
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_system
 #undef system
 #define system(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// You can either use error in common/textconsole.h
+// to force stopping your engine, or do a call
+// g_engine->quitGame(). For the latter, make sure to
+// do g_engine->shouldQuit() checks in the loops of any
+// calling methods so execution can break out of them
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_exit
 #undef exit
 #define exit(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use error or quitGame
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_abort
 #undef abort
 #define abort()	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use ConfMan in common/config-manager.h to save
+// settings rather than environment variables
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_getenv
 #undef getenv
 #define getenv(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use ConfMan in common/config-manager.h to save
+// settings rather than environment variables
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_putenv
 #undef putenv
 #define putenv(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use ConfMan in common/config-manager.h to save
+// settings rather than environment variables
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_setenv
 #undef setenv
 #define setenv(a,b,c)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use ConfMan in common/config-manager.h to save
+// settings rather than environment variables
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_unsetenv
 #undef unsetenv
 #define unsetenv(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
@@ -230,6 +282,7 @@
 
 //
 // Disable various symbols from time.h
+// Use instead g_system->getTimeAndDate
 //
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_time_h
 
@@ -292,21 +345,30 @@
 //
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_unistd_h
 
+	// ScummVM does not allow changing the current directory
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_chdir
 	#undef chdir
 	#define chdir(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// ScummVM has no equivalent for getting the current directory.
+	// However, you can use ConfMan.get("path") to get the
+	// running game's directory
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_getcwd
 	#undef getcwd
 	#define getcwd(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
-	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_getwd
+	// ScummVM has no equivalent for getting the current directory.
+	// However, you can use ConfMan.get("path") to get the
+	// running game's directory
+#ifndef FORBIDDEN_SYMBOL_EXCEPTION_getwd
 	#undef getwd
 	#define getwd(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// ScummVM only allows deleting save files, via the
+	// save file manager's removeSavefile method
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_unlink
 	#undef unlink
 	#define unlink(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
@@ -320,66 +382,79 @@
 //
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_ctype_h
 
+	// Use Common::isAlnum in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isalnum
 	#undef isalnum
 	#define isalnum(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isAlpha in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isalpha
 	#undef isalpha
 	#define isalpha(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isCntrl in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_iscntrl
 	#undef iscntrl
 	#define iscntrl(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isDigit in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isdigit
 	#undef isdigit
 	#define isdigit(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isGraph in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isgraph
 	#undef isgraph
 	#define isgraph(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isDigit in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isnumber
 	#undef isnumber
 	#define isnumber(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isLower in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_islower
 	#undef islower
 	#define islower(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isPrint in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isprint
 	#undef isprint
 	#define isprint(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isPunct in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_ispunct
 	#undef ispunct
 	#define ispunct(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isSpace in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isspace
 	#undef isspace
 	#define isspace(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isUpper in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isupper
 	#undef isupper
 	#define isupper(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isXDigit in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isxdigit
 	#undef isxdigit
 	#define isxdigit(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 	#endif
 
+	// Use Common::isBlank in common/util.h
 	#ifndef FORBIDDEN_SYMBOL_EXCEPTION_isblank
 	#undef isblank
 	#define isblank(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
@@ -387,6 +462,7 @@
 
 #endif // FORBIDDEN_SYMBOL_EXCEPTION_ctype_h
 
+// No equivalent in ScummVM
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_mkdir
 #undef mkdir
 #define mkdir(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
@@ -399,68 +475,83 @@
 #endif
 */
 
+// No equivalent in ScummVM
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_setvbuf
 #undef setvbuf
 #define setvbuf(a,b,c,d)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
-
+// Temporary files must be manually implemented using save files
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_tmpfile
 #undef tmpfile
 #define tmpfile()	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Temporary files must be manually implemented using save files
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_tmpnam
 #undef tmpnam
 #define tmpnam(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Temporary files must be manually implemented using save files
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_tempnam
 #undef tempnam
 #define tempnam(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Define a Common::RandomSource as part of the engine,
+// which has a getRandomNumber method
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_rand
 #undef rand
 #define rand()	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Define a Common::RandomSource as part of the engine,
+// which has a setSeed method
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_srand
 #undef srand
 #define srand(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Define a Common::RandomSource as part of the engine,
+// which has a getRandomNumber method
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_random
 #undef random
 #define random()	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Define a Common::RandomSource as part of the engine,
+// which has a setSeed method
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_srandom
 #undef srandom
 #define srandom(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
-
+// Use Common:scumm_stricmp in common/str.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_stricmp
 #undef stricmp
 #define stricmp(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common:scumm_strnicmp in common/str.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_strnicmp
 #undef strnicmp
 #define strnicmp(a,b,c)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common:scumm_stricmp in common/str.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_strcasecmp
 #undef strcasecmp
 #define strcasecmp(a,b)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common:scumm_strnicmp in common/str.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_strncasecmp
 #undef strncasecmp
 #define strncasecmp(a,b,c)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*
 #endif
 
+// Use Common::scumm_strdup in common/str.h
 #ifndef FORBIDDEN_SYMBOL_EXCEPTION_strdup
 #undef strdup
 #define strdup(a)	FORBIDDEN_look_at_common_forbidden_h_for_more_info SYMBOL !%*


