MethodScript

File options are a way to granularly control options for a single file. Some file options affect the compiler directly, others are simply used by the reflection mechanism to provide info during runtime, or for future readers of the code. Unrecognized file options are ignored, but are otherwise not an error, however, you should prefix all custom file options with "x-" to prevent future conflicts if new file options are introduced. The general format of a file option is: option: value; where the semicolon is optional for the last value. However, some file options are booleans. For booleans, either true or on are considered positive values, and false or off are considered negative values. Furthermore, leaving the value off entirely, e.g. option; is equivalent to option: on; The file options must be defined at the top of the file, and can only be preceeded by comments, and start with <! and end with >. Newlines within the file options are allowed. If, within the value, you need a literal > or semicolon, you must escape it with \, so \> or \;. == Inheritance == Default file options can be supplied on a per directory basis, by creating a file named .msfileoptions in any directory. Scripts in that directory as well as subdirectories will then use the defaults set in this file. If there are multiple .msfileoptions files in the parent directory chain, then they are read in from root to subfolder, using the value set in the file closest to the script file. That is, if you have a directory with files /scripts/myScript.ms, /scripts/.msfileoptions and /.msfileoptions, then options in /scripts/.msfileoptions will take precedence over options in /.msfileoptions for script /scripts/myScript.ms. In any case, the file options in the file itself always take precedence. The format of this file is the same as for file options directly in source code, except you leave off the beginning <! and end >. == Examples == Enables strict mode. Enables strict mode and adds a description to the file Disables strict mode for this file and adds a description. Below, the various file options and their effects are described: == strict == Enables strict mode for just this single file. See the page on [[Strict_Mode|strict mode]] for a discussion of what this mode actually does. == suppressWarnings == Suppresses the given compiler warnings for this file. The list should be comma separated, but can contain multiple types. * UnreachableCode - Code that comes after methods such as return() or exit() won't be run, and represents dead code, which should usually be removed, or can represent an error with your branching logic. (added 3.3.4) * HardcodedDynamicParameter - Code that is hardcoded and sent to eval is going to perform worse than simply writing the code normally. (added 3.3.4) * OverrideArguments - Defining a variable called @arguments overrides the built in @arguments value, making it impossible to access. (added 3.3.4) * UseBareStrings - Using bare strings can cause code to error or worse silently change behavior when using future versions of MethodScript that introduce new keywords. Therefore, it is always recommended to quote all strings. In strict mode, this is always an error that can't be suppressed. (added 3.3.4) * IncludedFileNotFound - When an include is encountered by the compiler, it checks to ensure that the file being included exists. It doesn't actually need to exist until runtime, but a warning is issued at compile time if it can't be found. (added 3.3.4) * CodeUpgradeNotices - Code that uses old formats should generally be upgraded to newer versions. This is encouraged to make code more readable, and is not a deprecation notice. This type of warning is only displayed in strict mode, and is even still suppressible. (added 3.3.4) * UseOfSecureString - When storing sensitive information such as passwords, it is advisable to use the secure_string class instead of string. There is first class language support for this in many places, but in general makes it harder to accidentally leak sensitive data in for example log messages, even when passing the data around to code that accepts strings. (added 3.3.4) * FutureNestedCommentChange - In version 3.3.6 or later, nested comment blocks will be allowed. This will cause the code here to suddenly change behavior by opening a new comment block, which will never be closed (as that's impossible with 3.3.5 behavior). If you accept that this will suddenly break in a future upgrade, you may do nothing now and deal with it later by closing the comment, but this (suppressable) warning is provided now during a phase in period in case you would like to deal with it by removing the opening comment symbol. (added 3.3.5) * UselessCode - The code or element at this location serves no purpose, and should be removed. Its existence may indicate a problem with the code. (added 3.3.5) * UnexpectedStatement - In strict mode, unexpected statements are an error, but in non-strict mode, they are a warning. (added 3.3.5) * PossibleUnexpectedExecution - If the parenthesis following a token is on a different line as the previous token, and it in general looks like a value that might be executable, this warning is issued, as it will cause an attempt at executing the previous statement. This warning will be removed in 3.3.7, and code will always attempt to execute, but in the meantime, to get rid of it, place a semicolon at the end of the previous line (if you don't mean for it to be executed) or move the left parenthesis up to the same line (if you do mean for it to be executed). (added 3.3.5) * MalformedComment - The comment related to this element is malformed. (added 3.3.5) * FutureError - This warning will be changed into a compile error in future versions, and should not be suppressed. (added 3.3.5) == name == This should be the name of the file. If it exists, and the file name does not match this value, the a compiler warning will be issued. The name must simply match the end of the actual file path, so providing a partial path, just the file name, the path within the project, or the absolute path are all acceptable. It is recommended that you do not provide the absolute path however, or the files cannot be easily moved. Both forward and backward slashes are accepted, and spaces in file paths are allowed. == author == The author of this file. This value is not used by the system, but is available using {{function|reflect_pull}}. == created == The date this file was created. This value is not used by the compiler, but is perhaps useful information for future readers of the script. This value is accessible via {{function|reflect_pull}}. == description == A description of this file. This value is not used by the compiler, but is perhaps useful information for future readers of the script. This value is accessible via {{function|reflect_pull}}. == copyright == The copyright information for the file. This value is accessible via {{function|reflect_pull}}. == license == The license under which the code is released. This can be the full license text or just the name of the license, or perhaps a link to the full license file. Generally, proprietary code does not need a license. This value is accessible via {{function|reflect_pull}}. == requiredExtensions == A comma separated list of extensions that must be loaded in order to compile this file. While it is possible to be more granular by using {{function|function_exists}} and {{function|event_exists}}, if the file cannot be useful without a given extension, this directive is preferred. == compilerOptions == A comma separated list of compiler options. These options are considered to be unset if not present, and set if present. * AllowAmbiguousCommands - Disables compiler validation for ambiguous commands (only applicable to MSA files). (added 3.3.4) * UltraStrict - Provides an extra strict programming environment. Nitpicky details may be covered in ultra strict mode, and will turn almost all warnings into compiler errors. This will also apply all lint settings that would be warnings into errors as well, and is generally the most pedantic version of strict mode available. This is used in native code, but is not necessarily recommended, since it offers no flexibility, however, code that passes ultra strict mode will generally be considered "ideal" code, and enshrines the standard code layout. Warnings that are explicitly suppressed are not errors in this mode. (added 3.3.4)

Find a bug in this page? Edit this page yourself, then submit a pull request.