txt: ## slangs.md
  Slangs
  
  Slangs in Raku
  
  The term "Slang" is used two different ways within the Raku community:
  
  * To refer to sublanguages within Raku, such as the quoting sublanguage or the regex sublanguage.
  * To refer to variants of Raku that are created by adding in a slang module that modifies the grammar of the language.
  
  # [Sublanguages within Raku](#Slangs "go to top of document")[§](#Sublanguages_within_Raku "direct link")
  
  The `~` twigil is for referring to sublanguages (called slangs). The following are useful:
  
  |  |  |
  | --- | --- |
  | $~MAIN | the current main language (e.g., Raku statements) |
  | $~Quote | the current root of quoting language |
  | $~Quasi | the current root of quasiquoting language |
  | $~Regex | the current root of regex language |
  | $~Trans | the current root of transliteration language |
  | $~P5Regex | the current root of the Perl regex language |
  
  You `augment` these languages in your current lexical scope.
  
  ```raku
  use MONKEY-TYPING;
  augment slang Regex {  # derive from $~Regex and then modify $~Regex
      token backslash:std<\Y> { YY };
  }
  
  ```
  
  The `MONKEY-TYPING` pragma is a necessary prerequisite to using the `augment` keyword. It can be thought of as a reminder that the following code is of a type that's usually discouraged. More documentation on `augment` is at [the augment declarator](/language/variables#The_augment_declarator).
  
  # [Slangs that Modify the Language](#Slangs "go to top of document")[§](#Slangs_that_Modify_the_Language "direct link")
  
  ## [Existing Slangs](#Slangs "go to top of document")[§](#Existing_Slangs "direct link")
  
  Many slangs are made available as modules through zef. These are useful for:
  
  * Using directly, so you don't have to write your own slang
  * As examples, for inspiration in writing your own slangs
  
  To see the existing Slang modules, we can look at:
  
  * [Everything tagged Slang](https://raku.land/tags/slang)
  * [A search for slang](https://raku.land/?q=slang)
  
  ## [Prerequisites for Understanding Slangs](#Slangs "go to top of document")[§](#Prerequisites_for_Understanding_Slangs "direct link")
  
  If all you wish to do is use existing Slangs, you can stop reading now. However, if you wish to understand better how to make or modify Slangs, then the recommended reading before continuing is:
  
  * [Grammar tutorial](/language/grammar_tutorial)
  * [Grammars](/language/grammars)
  * Not required, but helpful: [class Grammar](/type/Grammar)
  
  ## [A Slang Example](#Slangs "go to top of document")[§](#A_Slang_Example "direct link")
  
  To get a good view of a nice, simple Slang, the best candidate would be the source for [Slang::Lambda](https://raku.land/zef:lizmat/Slang::Lambda).
  
  Slang::Lambda modifies the Raku grammar to make it possible to use the `λ` (lambda) symbol as the starter symbol of a pointy block (which is usually `->`). The source is so short we can include it here:
  
  ```raku
  my role RakuLambda {
      token pointy-block-starter { '->' | '→' | '<->' | '↔' | 'λ' }
  }
  
  my role LegacyLambda {
      token lambda { '->' | '<->' | 'λ' }
  }
  
  use Slangify:ver<0.0.4+>:auth<zef:lizmat> RakuLambda, Mu, LegacyLambda;
  
  ```
  
  Then to use it, we do:
  
  ```raku
  use Slang::Lambda;
  
  say (1,2,3).map: λ $x { $x+1 }  # (2 3 4)
  
  
  ```
  
  The code is self-evident to those familiar with Raku's grammars. This is all well and good, but sometimes there's a large gap between being able to read code, and being able to write it. How did Elizabeth (the author of Slang::Lambda) know to use Slangify? How did she know what token names to declare? In her case, it was through extensive study of Raku and how it works, but in order to avoid this, we're going to step through some of these things now.
  
  ## [Slangify](#Slangs "go to top of document")[§](#Slangify "direct link")
  
  To ease the process of creating Slangs, Elizabeth Mattijsen also created the [Slangify](https://raku.land/zef:lizmat/Slangify) module (that's how she knew about it!) The Slangify module is a module intended for slang developers.
  
  It abstracts the internals of slang creation and activation so that module developers of slangs have a consistent interface they can work with across current and future versions of the Raku Programming Language.
  
  To use it you do the following:
  
  ```raku
  use Slangify Foo::Grammar, Foo::Actions;
  
  ```
  
  Either the Grammar or the Actions can be replaced with `Mu` to indicate that they should remain unchanged.
  
  Two additional parameters, for legacy grammars and legacy actions, are also accepted.
  
  While using Slangify is logically the last step in your code, it's worth understanding it somewhat before you begin, so that you can align your code with it. For further details, read the documentation for [Slangify](https://raku.land/zef:lizmat/Slangify).
  
  ## [The Raku Grammar](#Slangs "go to top of document")[§](#The_Raku_Grammar "direct link")
  
  This is the point where you need to do the most digging. The Raku grammar is not small, and nor is it simple; its extensive error messages, which are great when programming, hinder the readability.
  
  The sources for the Raku grammar are:
  
  * [The new AST grammar](https://github.com/rakudo/rakudo/blob/main/src/Raku/Grammar.nqp)
  * [The old, pre-AST grammar](https://github.com/rakudo/rakudo/blob/main/src/Perl6/Grammar.nqp)
  
  Unfortunately there's no substitute for digging through the grammar and locating the tokens/rules which you wish to override.
  
  ## [The Slang Grammar](#Slangs "go to top of document")[§](#The_Slang_Grammar "direct link")
  
  Now you need to write the slang grammar, much like Slang::Lambda. The links above to the grammar documentation should help here.
  
  ## [The Slang Actions](#Slangs "go to top of document")[§](#The_Slang_Actions "direct link")
  
  Many slangs will also need an Actions class backing them. This is also documented in the grammar documentation linked above.
  
  ## [Publishing the module](#Slangs "go to top of document")[§](#Publishing_the_module "direct link")
  
  You'll want to get your module published too. To do this, follow the instructions under [Upload your module to zef ecosystem](/language/modules#Upload_your_module_to_zef_ecosystem).
  