diff options
author | William Deegan <bill@baddogconsulting.com> | 2022-08-15 21:13:04 -0700 |
---|---|---|
committer | William Deegan <bill@baddogconsulting.com> | 2022-08-15 21:13:04 -0700 |
commit | d4ed957cb6562938a434d268f062238647f9f9fb (patch) | |
tree | 8e739be08be728911f96e5aac3e0219492094d72 | |
parent | 0a482919aa521a45abab2fb77f7474151a9f4b82 (diff) | |
download | scons-git-d4ed957cb6562938a434d268f062238647f9f9fb.tar.gz |
Address doc and docstring feedback from mwichmannadd_api_to_check_for_invalid_options_issue_4187
-rw-r--r-- | SCons/Script/Main.py | 10 | ||||
-rw-r--r-- | SCons/Script/Main.xml | 16 |
2 files changed, 19 insertions, 7 deletions
diff --git a/SCons/Script/Main.py b/SCons/Script/Main.py index 3516e90c8..442ee56e2 100644 --- a/SCons/Script/Main.py +++ b/SCons/Script/Main.py @@ -494,11 +494,19 @@ def SetOption(name, value): def ValidateOptions(throw_exception=False): - """ + """Validate options passed to SCons on the command line. + If you call this after you set all your command line options with AddOption(), it will verify that all command line options are valid. So if you added an option --xyz and you call SCons with --xyy you can cause SCons to issue an error message and exit by calling this function. + + args: + throw_exception (bool): Should this function raise an error if there's an + invalid option, or issue a message and exit with error status. + + Raises: + SConsBadOptionError """ OptionsParser.raise_exception_on_error = throw_exception diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index ace17991c..efec64f37 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -956,12 +956,7 @@ SetOption('max_drift', 0) <summary> <para> Check that all the options specified on the command line are either defined by SCons itself - or defined by &f-link-AddOption;. - </para> - <para> - If <parameter>throw_exception</parameter> is True, &f-ValidateOptions; will raise a - <literal>SConsBadOptionError</literal> - exception instead of printing an error message and exiting with an error status. + or defined by calls to &f-link-AddOption;. </para> <para> If there are any command line options not defined. @@ -969,6 +964,13 @@ SetOption('max_drift', 0) status. </para> <para> + If optional <parameter>throw_exception</parameter> is True, &f-ValidateOptions; will raise a + <exceptionname>SConsBadOptionError</exceptionname> + exception instead of printing an error message and exiting with an error status. Then the calling + &SConscript; logic can catch that exception and handle invalid options itself. + </para> + + <para> This function should only be called after the last &f-link-AddOption; call in your &SConscript; logic. </para> @@ -982,6 +984,8 @@ SetOption('max_drift', 0) </para> <example_commands> +try: + ValidateOptions(throw_exception=True) except SConsBadOptionError as e: print("Parser is SConsOptionParser:%s" % (isinstance(e.parser, SConsOptionParser))) print("Message is :%s" % e.opt_str) |