txt: ## pragmas.md
  Pragmas
  
  Special modules that define certain aspects of the behavior of the code
  
  In Raku, **pragmas** are directive used to either identify a specific version of Raku to be used or to modify the compiler's normal behavior in some way. The `use` keyword enables a pragma (similar to how you can `use` a module). To disable a pragma, use the `no` keyword:
  
  ```raku
  use v6.c;   # use 6.c language version
  no worries; # don't issue compile time warnings
  
  ```
  
  Following is a list of pragmas with a short description of each pragma's purpose or a link to more details about its use.
  
  ## [v6.x](#Pragmas "go to top of document")[§](#v6.x "direct link")
  
  This pragma states the version of the compiler that is going to be used, and turns on its features if they are optional.
  
  Since these pragmas turn on the compiler version, they should be the first statement in the file (preceding comments and Pod are fine).
  
  ```raku
  use v6;           # Load latest supported version (non-PREVIEW).
  
  ```
  
  Historically, `use v6;` was intended to signal to Perl interpreters to error out and warn the user to use Perl 6. This is no longer a consideration, so this statement has therefore become meaningless.
  
  ```raku
  use v6.c;         # Use the "Christmas" version of Raku
  
  ```
  
  ```raku
  use v6.d;         # Use the "Diwali" version of Raku
  
  ```
  
  From 2018.11, which implemented 6.d, this pragma does not do anything.
  
  ```raku
  use v6.d.PREVIEW; # On 6.d-capable compilers, enables 6.d features,
                    # otherwise enables the available experimental
                    # preview features for 6.d language
  
  ```
  
  ```raku
  use v6.e.PREVIEW; # Enables the available experimental preview features
                    # for 6.e language
  
  ```
  
  ```raku
  use v6.*;         # Enables the available experimental preview features
                    # for the language version currently in development
  
  ```
  
  ## [MONKEY-GUTS](#Pragmas "go to top of document")[§](#MONKEY-GUTS "direct link")
  
  This pragma is not currently part of any Raku specification, but is present in Rakudo as a synonym to `use nqp` (see below).
  
  ## [MONKEY-SEE-NO-EVAL](#Pragmas "go to top of document")[§](#MONKEY-SEE-NO-EVAL "direct link")
  
  [EVAL](/routine/EVAL)
  
  ## [MONKEY-TYPING](#Pragmas "go to top of document")[§](#MONKEY-TYPING "direct link")
  
  [augment](/syntax/augment)
  
  ## [MONKEY](#Pragmas "go to top of document")[§](#MONKEY "direct link")
  
  `use MONKEY;`
  
  Turns on all available `MONKEY` pragmas, equivalent to
  
  ```raku
  use MONKEY-TYPING;
  use MONKEY-SEE-NO-EVAL;
  use MONKEY-GUTS;
  ```
  
  ## [dynamic-scope](#Pragmas "go to top of document")[§](#dynamic-scope "direct link")
  
  Applies the [is dynamic](/type/Variable#trait_is_dynamic) trait to variables in the pragma's lexical scope. The effect can be restricted to a subset of variables by listing their names as arguments. By default applies to *all* variables.
  
  ```raku
  # Apply `is dynamic` only to $x, but not to $y
  use dynamic-scope <$x>;
  
  sub poke {
      say $CALLER::x;
      say $CALLER::y;
  }
  
  my $x = 23;
  my $y = 34;
  poke;
  
  # OUTPUT:
  # 23
  # Cannot access '$y' through CALLER, because it is not declared as dynamic
  
  ```
  
  This pragma is not currently part of any Raku specification and was added in Rakudo 2019.03.
  
  ## [experimental](#Pragmas "go to top of document")[§](#experimental "direct link")
  
  Allows use of [experimental features](/language/experimental)
  
  ## [fatal](#Pragmas "go to top of document")[§](#fatal "direct link")
  
  A lexical pragma that makes [Failures](/type/Failure) returned from routines fatal. For example, prefix `+` on a [`Str`](/type/Str) coerces it to [`Numeric`](/type/Numeric), but will return a [`Failure`](/type/Failure) if the string contains non-numeric characters. Saving that [`Failure`](/type/Failure) in a variable prevents it from being sunk, and so the first code block below reaches the `say $x.^name;` line and prints [`Failure`](/type/Failure) in output.
  
  In the second block, the `use fatal` pragma is enabled, so the `say` line is never reached because the [`Exception`](/type/Exception) contained in the [`Failure`](/type/Failure) returned from prefix `+` gets thrown and the `CATCH` block gets run, printing the `Caught...` line. Note that both blocks are the same program and `use fatal` only affects the lexical block it was used in:
  
  ```raku
  {
      my $x = +"a";
      say $x.^name;
      CATCH { default { say "Caught {.^name}" } }
  } # OUTPUT: «Failure␤»
  
  {
      use fatal;
      my $x = +"a";
      say $x.^name;
      CATCH { default { say "Caught {.^name}" } }
  } # OUTPUT: «Caught X::Str::Numeric␤»
  ```
  
  Inside [`try` blocks](/language/exceptions#try_blocks), the `fatal` pragma is enabled by default, and you can *disable* it with `no fatal`:
  
  ```raku
  try {
      my $x = +"a";
      say $x.^name;
      CATCH { default { say "Caught {.^name}" } }
  } # OUTPUT: «Caught X::Str::Numeric␤»
  
  try {
      no fatal;
      my $x = +"a";
      say $x.^name;
      CATCH { default { say "Caught {.^name}" } }
  } # OUTPUT: «Failure␤»
  ```
  
  ## [isms](#Pragmas "go to top of document")[§](#isms "direct link")
  
  `[2018.09 and later]`
  
  Allow for some other language constructs that were deemed to be a trap that warranted a warning and/or an error in normal Raku programming. Currently, `Perl` and `C++` are allowed.
  
  ```raku
  sub abs() { say "foo" }
  abs;
  # Unsupported use of bare "abs"; in Raku please use .abs if you meant
  # to call it as a method on $_, or use an explicit invocant or argument,
  # or use &abs to refer to the function as a noun
  
  ```
  
  In this case, providing an `abs` sub that doesn't take any arguments, did not make the compilation error go away.
  
  ```raku
  use isms <Perl5>;
  sub abs() { say "foo" }
  abs;   # foo
  ```
  
  With this, the compiler will allow the offending Perl construct, allowing the code to actually be executed.
  
  If you do not specify any language, all known language constructs are allowed.
  
  ```raku
  use isms;   # allow for Perl and C++ isms
  ```
  
  ## [lib](#Pragmas "go to top of document")[§](#lib "direct link")
  
  This pragma adds subdirectories to the library search path so that the interpreter can [find the modules](/language/modules#Finding_installed_modules).
  
  ```raku
  use lib <lib /opt/lib /usr/local/lib>;
  
  #or a mixed list of IO::Path and Str
  use lib ('.', '.'.IO, './lib'.IO);
  
  ```
  
  This will search the directories passed in a list. Please check [the modules documentation](/language/modules#use) for more examples.
  
  ## [newline](#Pragmas "go to top of document")[§](#newline "direct link")
  
  Set the value of the [$?NL](/language/variables#Compile-time_variables) constant in the scope it is called. Possible values are `:lf` (which is the default, indicating Line Feed), `:crlf` (indicating Carriage Return, Line Feed) and `:cr` (indicating Carriage Return).
  
  ## [nqp](#Pragmas "go to top of document")[§](#nqp "direct link")
  
  Use at your own risk.
  
  This is a Rakudo-specific pragma. With it, Rakudo provides access to the [nqp opcodes](https://github.com/Raku/nqp/blob/master/docs/ops.markdown) in a top level namespace:
  
  ```raku
  use nqp;
  nqp::say("hello world");
  ```
  
  This uses the underlying nqp `say` opcode instead of the Raku routine. This pragma may make your code rely on a particular version of nqp, and since that code is not part of the Raku specification, it's not guaranteed to be stable. You may find a large number of usages in the Rakudo core, which are used to make the core functionality as fast as possible. Future optimizations in the code generation of Rakudo may obsolete these usages.
  
  ## [precompilation](#Pragmas "go to top of document")[§](#precompilation "direct link")
  
  The default allows precompilation of source code, specifically if used in a module. If for whatever reason you do not want the code (of your module) to be precompiled, you can use `no precompilation`. This will prevent the entire compilation unit (usually a file) from being precompiled.
  
  ## [soft](#Pragmas "go to top of document")[§](#soft "direct link")
  
  [Re-dispatching](/language/functions#Re-dispatching), [inlining](/language/functions#index-entry-use_soft_(pragma))
  
  ## [strict](#Pragmas "go to top of document")[§](#strict "direct link")
  
  `strict` is the default behavior, and requires that you declare variables before using them. You can relax this restriction with `no`.
  
  ```raku
  no strict; $x = 42; # OK
  
  ```
  
  ## [trace](#Pragmas "go to top of document")[§](#trace "direct link")
  
  When `use trace` is activated, any line of code executing will be written to STDERR. You can use `no trace` to switch off the feature, so this only happens for certain sections of code.
  
  ## [v6](#Pragmas "go to top of document")[§](#v6 "direct link")
  
  [Writing Tests](/language/testing#Writing_tests)
  
  ## [variables](#Pragmas "go to top of document")[§](#variables "direct link")
  
  [Defined Variables Pragma](/language/variables#Default_defined_variables_pragma)
  
  ## [worries](#Pragmas "go to top of document")[§](#worries "direct link")
  
  Lexically controls whether compile-time warnings generated by the compiler get shown. Enabled by default.
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  $ raku -e 'say :foo<>.Pair'
  Potential difficulties:
    Pair with <> really means an empty list, not null string; use :foo('') to represent the null string,
      or :foo() to represent the empty list more accurately
    at -e:1
    ------> say :foo<>⏏.Pair
  foo => Nil
  
  $ raku -e 'no worries; say :foo<>.Pair'
  foo => Nil
  
  
  ```
  
  
  ```
  