doc/LPC/pragma

NAME
        pragma

DESCRIPTION
        The preprocessor directive #pragma can be used to select
        several compilation options. Multiple options can be selected
        in one #pragma directive by separating them with commas.

        no_inherit: The program can't be inherited.
        no_shadow: The program can't be shadowed (similar to declaring
                all functions as 'nomask').

        clone: The blueprint object can be cloned (default, implies
                no_lightweight).
        no_clone: The blueprint object can't be cloned.

        lightweight: Lightweight objects may be created from the
                blueprint (implies no_clone and warn_lightweight).
        no_lightweight: Lightweight object cannot be created from it
                (default).

        init_variables: Clone variables are initialized by __INIT().
        share_variables: Clone variables are initialized from the
                blueprint.

        no_simul_efuns: Disable the use of simul-efuns. This pragma
                raises a privilege_violation("no_simul_efuns").
        simul_efuns: Enables the use of simul-efuns (this is the
                default for all objects except the master).

        weak_types: no type checking (this is the default).
        strict_types: all functions must be declared with argument
                prototypes, and the return values of call_other() must
                be casted.
        strong_types: all functions must be declared with complete
                types of return value and parameters.
        save_types: the declaration data is kept after compilation and
                checked at runtime. This is important for type-safe
                inheritance.
        no_bytes_type: removes the keyword 'bytes', also 'string' then
                denotes the type <string|bytes>.
        bytes_type: reactivates the keyword 'bytes' and distinguishes
                between the 'bytes' and 'string' type.

        rtt_checks: runtime checks during execution of this program will be
                enabled. The interpreter will check for correct datatypes in
                the following circumstances:
                  - arguments on function calls,
                  - return values of functions,
                  - assignment to variables,
                  - declarative type casts,
                  - restoration of values to variables or struct members.
                Don't confuse this with strong/strict_types, they only
                check at compile time.
                strong_types/strict_types is seriously recommended.
                This pragma implicitly enables save_types as well.
        warn_rtt_checks: runtime checks are enabled, just like rtt_checks,
                but errors will be shown as warnings only.
        no_rtt_checks: disable runtime type checks for this program (default).

        pedantic: Certain warnings are treated as errors:
                  - failure to pass enough arguments to simul efuns
                  - type casts with no effect
                  - inconsistent declarations
                  - inconsistent overloads
                  - double inherits
        sloppy: Turns off pedantic (the default).

        range_check: Use of questionable ranges (ranges of negative sizes,
                or with bounds beyond the array's size) cause a runtime
                warning.
        no_range_check: Turns off range_check (the default).

        warn_deprecated: Use of deprecated efuns or indexing operations
                causes the compiler to issue a warning (the default).
        no_warn_deprecated: Turns off warn_deprecated.

        warn_empty_casts: A cast of a value to its own type generates
                a warning. Also casting a value of mixed/unknown type or
                casting to mixed will generate a warning (the default).
        no_warn_empty_casts: Turns off warn_empty_casts.

        warn_missing_return: Warn if a value-returning function is missing
                a return statement (the default). If possible, the driver
                will try to detect this at compile time; otherwise a runtime
                warning will be generated when the function is executed.
                The check applies only to functions with a declared return
                type other than 'void'.
        no_warn_missing_return: Turn off warn_missing_return.

        warn_dead_code: Warn about dead code. Code is considered dead if
                it can never be executed. The driver has only limited
                analysis capabilities and cannot detect all instances
                of dead code.
        no_warn_dead_code: Turn off warn_dead_code (the default).

        warn_function_inconsistent: If an inherited function is
                overloaded with inconsistent return types or arguments,
                a warning is generated; or if pragma_pedantic is in effect,
                an error. By default this is active.
        no_warn_function_inconsistent: An inherited function can
                be overloaded with inconsistent return types or arguments,
                as long as pragma_pedantic is not in effect.

                This pragma is meant to easen the adaption of legacy
                mudlib code - in general one should fix the warnings,
                not turn them off.

        warn_applied_functions: If a function is known to be an applied
                lfun, warn if its declaration differs from the specification.
        no_warn_applied_functions: Turn of warn_applied_functions
                (the default).

        warn_unused_variables: Warn about variables that are not used.
                It will warn about variables never written to, variables
                never read from or variables never used at all.
                This applies to local variables and private global variables.
        no_warn_unused_variables: Turn off warn_unused_variables
                (the default).

        warn_unused_values: Warn about values that are not used.
                It will warn about values that are created without
                side-effects (eg. a literal value or created by some
                operation) and are not used afterwards.
        no_warn_unused_values: Turn off warn_unused_values (the default).

        warn_lightweight: Warn about efuns that are not suitable for
                lightweight objects.
        no_warn_lightweight: Turn off warn_lightweight.

        save_local_names: When activated the name of local variables
                are saved for debugging purposes. This increases the
                size of the program.
        no_save_local_names: Turn off save_local_names (the default).

        When an object is compiled with type testing (#pragma
        strict_types), all types are saved of the arguments for that
        function during compilation.  If the #pragma save_types is
        specified, then the types are saved even after compilation, to
        be used when the object is inherited.

        The following two pragmas are available if the driver was
        compiled with DEBUG and TRACE_CODE options:

        set_code_window: Sets an offset to the current program writing
                position. Use this BEFORE a piece of code where you
                want to check to what bytecodes it is compiled.
        show_code_window: shows some bytes starting at or near the
                last point set_code_window was called.

EXAMPLES
        #pragma strict_types
        #pragma no_clone, no_inherit

HISTORY
        LDMud 3.2.7 added local_scopes, no_local_scopes, no_clone
        and no_inherit.
        LDMud 3.2.8 added weak_types, pedantic and sloppy.
        LDMud 3.2.9 allowed to specify multiple pragmas in one directive.
        LDMud 3.2.9 added (no_)warn_deprecated.
        LDMud 3.2.10 added (no_)warn_empty_casts.
        Starting with LDMud 3.2.10, #pragma xxx_types in an included file are
          no longer valid only until the end of the file, but remain active
          when processing returns to the including file.
        LDMud 3.2.11 added (no_)warn_function_inconsistent.
        LDMud 3.3.378 added init_variables, share_variables.
        LDMud 3.3.357 added (no_)warn_missing_return.
        LDMud 3.3.646 added (no_)range_check.
        LDMud 3.5.0 removed combine_strings and no_combine_strings.
        LDMud 3.5.0 removed local_scopes and no_local_scopes.
        LDMud 3.5.0 removed verbose_errors (making its behaviour mandatory).
        LDMud 3.5.0 enabled warn_deprecated by default.

SEE ALSO
        inheritance(LPC), initialisation(LPC), objects(C),
        operators(LPC)