with / without
These special statements affect the way that Phix compiles your program.
They are not meant to change the logic of your program, but may affect the
diagnostic information that you get from running your program.
See Debugging and Profiling for more information.
without debug prevents the creation of diagnostic and tracing information. Default: on, ie with debug only has any effect if there has already been an earlier without debug. This is typically used in the builtins/VM parts of Phix to help avoid cluttering up any ex.err with excessive and often unhelpful information, especially when said pertains to thoroughly tested routines that have not been altered for many years. One trick I often use is to wrap a bunch of include statements in without/with debug and that way obtain much easier to use ex.err reports, at least temporarily, but I would not recommend that be left in for released software. The without debug directive also causes any error to be reported on the calling line rather than within the routine itself, a classic example is printf(), and trust me you would far rather be taken to the line where you have just entered an incorrect format than the line deep within builtins\VM\pprntfN.e that discovered it.
Careful/intelligent use of the nFrames parameter of crash/assert() can also be used to effect the latter, without resorting to this (rather blanket) directive.
with js disables/traps the underlying copy-on-write mechanisms, triggering fatal runtime errors when running code on desktop/Phix that would fail should it be transpiled to JavaScript by pwa/p2js and subsequently run in a browser. Default: off/any, ie without js has no effect on desktop/Phix, unless the compiler detects both (with and without) which is treated as an error, and without js also stops pwa/p2js dead in its tracks. Both of those errors could potentially save someone from wasting their time, for instance trying to use a dll/so, read/write files, or something equally illegal from within a browser.
Note that "with js" is kinda whole-program only and will crash if specified "too late", while "without js" could be used to mark a component as browser-incompatible. Should you want to mark a specific component as browser-only, requires(JS) is a better idea. The best way to mark a component as fine on both destktop and browser is a plain old comment. See the Incompatibilities section of pwa/p2js for more information.
Also aliased to with/out javascript and with/out javascript_semantics: obviously "js" is far easier to type, however a search for that on say rosettacode is likely to be less useful than a search for the longest form, and admittedly the middle-length variety is probably no good for either, but there may be times in the docs/examples where that is simply the readability king.
with profile enables execution count profiling, which is written to ex.pro when the program terminates. Default: off, ie without profile only has any effect if there has already been an earlier with profile, and that can eliminate some noise or hotspots that might be making it difficult to see what is going on elsewhere. Attempts to enable profile and profile_time at any point in the same program triggers a fatal error, even when they do not overlap.
with profile_time enables execution time profiling, otherwise the same as above. Default: off, ie without profile_time works he same way as above too.
with safe_mode disables most potentially dangerous features such as file i/o and invoking c_func/proc() which should make it safer to try out code from an untrusted source. It behaves identically to a -safe command line option. See demo\rosetta\safe_mode.exw for further details.
with trace enables single-stepping through the code as it executes, or creating a ctrace.out file as it runs. Default: off, ie without trace only has any effect if there has already been an earlier with trace, and those can be used in pairs to select which parts of your program are available for tracing, as above eliminating regions you do not want to accidentally step into, though you can still step in/over/out using F7/F8/F9. Note that with trace effectively does nothing by itself: it marks regions of the code that can be traced, but you also need call(s) to trace() to actually start(/stop) it. Typically I would add with trace at the top, then trace(1) somewhere lower down, when it actually gets round to doing that pesky item[57] or whatever it is that is going wrong.
without type_check disables user defined type checking, which can improve performance. Default: on, ie with type_check only has any effect if there has already been an earlier without type_check, and generally speaking that is quite a rare thing to (need or want to) do.
without warning disables selected compile-time warnings such as unused parameters. Default: on, ie with warning only has any effect if there has already been an earlier without warning, though in this case it is quite common to use a without/with pair to remove a single specific warning while letting earlier and subsequent ones be seen. Note this option predates the introduction of un-named parameters and I believe there is no longer any case where you actually need to use without warning.
Any warnings that are issued will appear on your screen after your program has finished execution.
Warnings indicate very minor problems, and will never stop your program from executing.
with nested_globals enables the definition of local constants with embedded globals. Default: off, ie [local] constant S = {A:=1} defines both S and A as local, when enabled S is still local, but A is global, as would everything defined via the ":=" syntax be. There is a matching complementary option with nested_locals which causes global constant S = {A:=1} to define S as global but A as local, and likewise the default is off. It would of course be prudent to re-disable asap, to prevent any later innocent and possibly legacy definitions from accidentally defining potentially clashing globals, or failing to define globals that they should.
There was once also a special with number option, which is no longer used and can safely be deleted.
Phix also allows console/gui: this is deprecated, see format.
You may only enable either profile or profile_time, but not both, for a given run of your program.
Unlike Euphoria, settings can be changed mid-routine.
Note that "without warning strict" is a Euphoria thing; Phix simply ignores the "strict", but complains should any of the other 17 or so complex warning settings of Euphoria be encountered. Phix also simply ignores attempts to set indirect_includes and inline, but currently displays an error for ifdef tags (ie with/without define).
An included file inherits the with/without settings in effect at the point where it is included. An included file can change these settings, but they will revert back to their original state at the end of the included file. For instance, an included file might turn off warnings for itself and (initially) for any files that it includes, but this will not turn off warnings for the main file.
without debug prevents the creation of diagnostic and tracing information. Default: on, ie with debug only has any effect if there has already been an earlier without debug. This is typically used in the builtins/VM parts of Phix to help avoid cluttering up any ex.err with excessive and often unhelpful information, especially when said pertains to thoroughly tested routines that have not been altered for many years. One trick I often use is to wrap a bunch of include statements in without/with debug and that way obtain much easier to use ex.err reports, at least temporarily, but I would not recommend that be left in for released software. The without debug directive also causes any error to be reported on the calling line rather than within the routine itself, a classic example is printf(), and trust me you would far rather be taken to the line where you have just entered an incorrect format than the line deep within builtins\VM\pprntfN.e that discovered it.
Careful/intelligent use of the nFrames parameter of crash/assert() can also be used to effect the latter, without resorting to this (rather blanket) directive.
with js disables/traps the underlying copy-on-write mechanisms, triggering fatal runtime errors when running code on desktop/Phix that would fail should it be transpiled to JavaScript by pwa/p2js and subsequently run in a browser. Default: off/any, ie without js has no effect on desktop/Phix, unless the compiler detects both (with and without) which is treated as an error, and without js also stops pwa/p2js dead in its tracks. Both of those errors could potentially save someone from wasting their time, for instance trying to use a dll/so, read/write files, or something equally illegal from within a browser.
Note that "with js" is kinda whole-program only and will crash if specified "too late", while "without js" could be used to mark a component as browser-incompatible. Should you want to mark a specific component as browser-only, requires(JS) is a better idea. The best way to mark a component as fine on both destktop and browser is a plain old comment. See the Incompatibilities section of pwa/p2js for more information.
Also aliased to with/out javascript and with/out javascript_semantics: obviously "js" is far easier to type, however a search for that on say rosettacode is likely to be less useful than a search for the longest form, and admittedly the middle-length variety is probably no good for either, but there may be times in the docs/examples where that is simply the readability king.
with profile enables execution count profiling, which is written to ex.pro when the program terminates. Default: off, ie without profile only has any effect if there has already been an earlier with profile, and that can eliminate some noise or hotspots that might be making it difficult to see what is going on elsewhere. Attempts to enable profile and profile_time at any point in the same program triggers a fatal error, even when they do not overlap.
with profile_time enables execution time profiling, otherwise the same as above. Default: off, ie without profile_time works he same way as above too.
with safe_mode disables most potentially dangerous features such as file i/o and invoking c_func/proc() which should make it safer to try out code from an untrusted source. It behaves identically to a -safe command line option. See demo\rosetta\safe_mode.exw for further details.
with trace enables single-stepping through the code as it executes, or creating a ctrace.out file as it runs. Default: off, ie without trace only has any effect if there has already been an earlier with trace, and those can be used in pairs to select which parts of your program are available for tracing, as above eliminating regions you do not want to accidentally step into, though you can still step in/over/out using F7/F8/F9. Note that with trace effectively does nothing by itself: it marks regions of the code that can be traced, but you also need call(s) to trace() to actually start(/stop) it. Typically I would add with trace at the top, then trace(1) somewhere lower down, when it actually gets round to doing that pesky item[57] or whatever it is that is going wrong.
without type_check disables user defined type checking, which can improve performance. Default: on, ie with type_check only has any effect if there has already been an earlier without type_check, and generally speaking that is quite a rare thing to (need or want to) do.
without warning disables selected compile-time warnings such as unused parameters. Default: on, ie with warning only has any effect if there has already been an earlier without warning, though in this case it is quite common to use a without/with pair to remove a single specific warning while letting earlier and subsequent ones be seen. Note this option predates the introduction of un-named parameters and I believe there is no longer any case where you actually need to use without warning.
Any warnings that are issued will appear on your screen after your program has finished execution.
Warnings indicate very minor problems, and will never stop your program from executing.
with nested_globals enables the definition of local constants with embedded globals. Default: off, ie [local] constant S = {A:=1} defines both S and A as local, when enabled S is still local, but A is global, as would everything defined via the ":=" syntax be. There is a matching complementary option with nested_locals which causes global constant S = {A:=1} to define S as global but A as local, and likewise the default is off. It would of course be prudent to re-disable asap, to prevent any later innocent and possibly legacy definitions from accidentally defining potentially clashing globals, or failing to define globals that they should.
There was once also a special with number option, which is no longer used and can safely be deleted.
Phix also allows console/gui: this is deprecated, see format.
You may only enable either profile or profile_time, but not both, for a given run of your program.
Unlike Euphoria, settings can be changed mid-routine.
Note that "without warning strict" is a Euphoria thing; Phix simply ignores the "strict", but complains should any of the other 17 or so complex warning settings of Euphoria be encountered. Phix also simply ignores attempts to set indirect_includes and inline, but currently displays an error for ifdef tags (ie with/without define).
An included file inherits the with/without settings in effect at the point where it is included. An included file can change these settings, but they will revert back to their original state at the end of the included file. For instance, an included file might turn off warnings for itself and (initially) for any files that it includes, but this will not turn off warnings for the main file.