txt: ## mu.md
  class Mu
  
  The root of the Raku type hierarchy.
  
  ```raku
  class Mu { }
  ```
  
  The root of the Raku type hierarchy. For the origin of the name, see [Mu (negative)](https://en.wikipedia.org/wiki/Mu_%28negative%29) on Wikipedia. One can also say that there are many undefined values in Raku, and `Mu` is the *most undefined* value.
  
  Note that most classes do not derive from `Mu` directly, but rather from [`Any`](/type/Any).
  
  # [Methods](#class_Mu "go to top of document")[§](#Methods "direct link")
  
  ## [method iterator](#class_Mu "go to top of document")[§](#method_iterator "direct link")
  
  ```raku
  method iterator(--> Iterator)
  ```
  
  Coerces the invocant to a `list` by applying its [`.list`](/routine/list) method and uses [`iterator`](/type/Iterable#method_iterator) on it.
  
  ```raku
  my $it = Mu.iterator;
  say $it.pull-one; # OUTPUT: «(Mu)␤»
  say $it.pull-one; # OUTPUT: «IterationEnd␤»
  ```
  
  ## [method defined](#class_Mu "go to top of document")[§](#method_defined "direct link")
  
  ```raku
  multi method defined(   --> Bool:D)
  ```
  
  Returns `False` on a type object, and `True` otherwise.
  
  ```raku
  say Int.defined;                # OUTPUT: «False␤»
  say 42.defined;                 # OUTPUT: «True␤»
  ```
  
  A few types (like [`Failure`](/type/Failure)) override `defined` to return `False` even for instances:
  
  ```raku
  sub fails() { fail 'oh noe' };
  say fails().defined;            # OUTPUT: «False␤»
  ```
  
  ## [routine defined](#class_Mu "go to top of document")[§](#routine_defined "direct link")
  
  ```raku
  multi defined(Mu --> Bool:D)
  ```
  
  invokes the `.defined` method on the object and returns its result.
  
  ## [routine isa](#class_Mu "go to top of document")[§](#routine_isa "direct link")
  
  ```raku
  multi method isa(Mu $type     --> Bool:D)
  multi method isa(Str:D $type  --> Bool:D)
  ```
  
  Returns `True` if the invocant is an instance of class `$type`, a subset type or a derived class (through inheritance) of `$type`. [`does`](/routine/does#(Mu)_routine_does) is similar, but includes roles.
  
  ```raku
  my $i = 17;
  say $i.isa("Int");   # OUTPUT: «True␤»
  say $i.isa(Any);     # OUTPUT: «True␤»
  role Truish {};
  my $but-true = 0 but Truish;
  say $but-true.^name;        # OUTPUT: «Int+{Truish}␤»
  say $but-true.does(Truish); # OUTPUT: «True␤»
  say $but-true.isa(Truish);  # OUTPUT: «False␤»
  ```
  
  ## [routine does](#class_Mu "go to top of document")[§](#routine_does "direct link")
  
  ```raku
  method does(Mu $type --> Bool:D)
  ```
  
  Returns `True` if and only if the invocant conforms to type `$type`.
  
  ```raku
  my $d = Date.new('2016-06-03');
  say $d.does(Dateish);             # OUTPUT: «True␤»    (Date does role Dateish)
  say $d.does(Any);                 # OUTPUT: «True␤»    (Date is a subclass of Any)
  say $d.does(DateTime);            # OUTPUT: «False␤»   (Date is not a subclass of DateTime)
  
  ```
  
  Unlike [`isa`](/routine/isa#(Mu)_routine_isa), which returns `True` only for superclasses, `does` includes both superclasses and roles.
  
  ```raku
  say $d.isa(Dateish); # OUTPUT: «False␤»
  
  ```
  
  Using the smartmatch operator [~~](/routine/~~) is a more idiomatic alternative.
  
  ```raku
  my $d = Date.new('2016-06-03');
  say $d ~~ Dateish;                # OUTPUT: «True␤»
  say $d ~~ Any;                    # OUTPUT: «True␤»
  say $d ~~ DateTime;               # OUTPUT: «False␤»
  ```
  
  ## [routine Bool](#class_Mu "go to top of document")[§](#routine_Bool "direct link")
  
  ```raku
  multi        Bool(Mu --> Bool:D)
  multi method Bool(   --> Bool:D)
  ```
  
  Returns `False` on the type object, and `True` otherwise.
  
  Many built-in types override this to be `False` for empty collections, the empty [string](/type/Str) or numerical zeros
  
  ```raku
  say Mu.Bool;                    # OUTPUT: «False␤»
  say Mu.new.Bool;                # OUTPUT: «True␤»
  say [1, 2, 3].Bool;             # OUTPUT: «True␤»
  say [].Bool;                    # OUTPUT: «False␤»
  say %( hash => 'full' ).Bool;   # OUTPUT: «True␤»
  say {}.Bool;                    # OUTPUT: «False␤»
  say "".Bool;                    # OUTPUT: «False␤»
  say 0.Bool;                     # OUTPUT: «False␤»
  say 1.Bool;                     # OUTPUT: «True␤»
  say "0".Bool;                   # OUTPUT: «True␤»
  ```
  
  ## [method Capture](#class_Mu "go to top of document")[§](#method_Capture "direct link")
  
  ```raku
  method Capture(Mu:D: --> Capture:D)
  ```
  
  Returns a [`Capture`](/type/Capture) with named arguments corresponding to invocant's public attributes:
  
  ```raku
  class Foo {
      has $.foo = 42;
      has $.bar = 70;
      method bar { 'something else' }
  }.new.Capture.say; # OUTPUT: «\(:bar("something else"), :foo(42))␤»
  ```
  
  ## [method Str](#class_Mu "go to top of document")[§](#method_Str "direct link")
  
  ```raku
  multi method Str(--> Str)
  ```
  
  Returns a string representation of the invocant, intended to be machine readable. Method [`Str`](/type/Str) warns on type objects, and produces the empty string.
  
  ```raku
  say Mu.Str;   # Use of uninitialized value of type Mu in string context.
  my @foo = [2,3,1];
  say @foo.Str  # OUTPUT: «2 3 1␤»
  ```
  
  ## [routine gist](#class_Mu "go to top of document")[§](#routine_gist "direct link")
  
  ```raku
  multi        gist(+args --> Str)
  multi method gist(   --> Str)
  ```
  
  Returns a string representation of the invocant, optimized for fast recognition by humans. As such lists will be truncated at 100 elements. Use `.raku` to get all elements.
  
  The default `gist` method in `Mu` re-dispatches to the [raku](/routine/raku) method for defined invocants, and returns the type name in parenthesis for type object invocants. Many built-in classes override the case of instances to something more specific that may truncate output.
  
  `gist` is the method that [say](/routine/say) calls implicitly, so `say $something` and `say $something.gist` generally produce the same output.
  
  ```raku
  say Mu.gist;        # OUTPUT: «(Mu)␤»
  say Mu.new.gist;    # OUTPUT: «Mu.new␤»
  ```
  
  ## [method perl](#class_Mu "go to top of document")[§](#method_perl "direct link")
  
  ```raku
  multi method perl(Mu:)
  ```
  
  Calls [`.raku`](/routine/raku) on the invocant. Since the change of the language name to Raku, this method is deprecated and might disappear in the near future. Use `.raku` instead.
  
  ## [method raku](#class_Mu "go to top of document")[§](#method_raku "direct link")
  
  ```raku
  multi method raku(Mu:U:)
  multi method raku(Mu:D:)
  ```
  
  For type objects, returns its name if `.raku` has not been redefined from `Mu`, or calls `.raku` on the name of the type object otherwise.
  
  ```raku
  say Str.raku;          # OUTPUT: «Str␤»
  ```
  
  For plain objects, it will conventionally return a representation of the object that can be used via [`EVAL`](/routine/EVAL) to reconstruct the value of the object.
  
  ```raku
  say (1..3).Set.raku;  # OUTPUT: «Set.new(1,2,3)␤»
  ```
  
  ## [method item](#class_Mu "go to top of document")[§](#method_item "direct link")
  
  ```raku
  method item(Mu \item:) is raw
  ```
  
  Forces the invocant to be evaluated in item context and returns the value of it.
  
  ```raku
  say [1,2,3].item.raku;          # OUTPUT: «$[1, 2, 3]␤»
  say %( apple => 10 ).item.raku; # OUTPUT: «${:apple(10)}␤»
  say "abc".item.raku;            # OUTPUT: «"abc"␤»
  ```
  
  ## [method self](#class_Mu "go to top of document")[§](#method_self "direct link")
  
  ```raku
  method self(--> Mu)
  ```
  
  Returns the object it is called on.
  
  ## [method clone](#class_Mu "go to top of document")[§](#method_clone "direct link")
  
  ```raku
  multi method clone(Mu:U: *%twiddles)
  multi method clone(Mu:D: *%twiddles)
  ```
  
  This method will clone type objects, or die if it's invoked with any argument.
  
  ```raku
  say Num.clone( :yes )
  # OUTPUT: «(exit code 1) Cannot set attribute values when cloning a type object␤  in block <unit>␤␤»
  
  ```
  
  If invoked with value objects, it creates a shallow clone of the invocant, including shallow cloning of private attributes. Alternative values for *public* attributes can be provided via named arguments with names matching the attributes' names.
  
  ```raku
  class Point2D {
      has ($.x, $.y);
      multi method gist(Point2D:D:) {
          "Point($.x, $.y)";
      }
  }
  
  my $p = Point2D.new(x => 2, y => 3);
  
  say $p;                     # OUTPUT: «Point(2, 3)␤»
  say $p.clone(y => -5);      # OUTPUT: «Point(2, -5)␤»
  
  ```
  
  Note that `.clone` does not go the extra mile to shallow-copy `@.` and `%.` sigiled attributes and, if modified, the modifications will still be available in the original object:
  
  ```raku
  class Foo {
      has $.foo is rw = 42;
      has &.boo is rw = { say "Hi" };
      has @.bar       = <a b>;
      has %.baz       = <a b c d>;
  }
  
  my $o1 = Foo.new;
  with my $o2 = $o1.clone {
      .foo = 70;
      .bar = <Z Y>;
      .baz = <Z Y X W>;
      .boo = { say "Bye" };
  }
  
  # Hash and Array attribute modifications in clone appear in original as well:
  say $o1;
  # OUTPUT: «Foo.new(foo => 42, bar => ["Z", "Y"], baz => {:X("W"), :Z("Y")}, …␤»
  say $o2;
  # OUTPUT: «Foo.new(foo => 70, bar => ["Z", "Y"], baz => {:X("W"), :Z("Y")}, …␤»
  $o1.boo.(); # OUTPUT: «Hi␤»
  $o2.boo.(); # OUTPUT: «Bye␤»
  
  ```
  
  To clone those, you could implement your own `.clone` that clones the appropriate attributes and passes the new values to `Mu.clone`, for example, via [`nextwith`](/language/functions#sub_nextwith).
  
  ```raku
  class Bar {
      has $.quux;
      has @.foo = <a b>;
      has %.bar = <a b c d>;
      method clone { nextwith :foo(@!foo.clone), :bar(%!bar.clone), |%_  }
  }
  
  my $o1 = Bar.new( :42quux );
  with my $o2 = $o1.clone {
      .foo = <Z Y>;
      .bar = <Z Y X W>;
  }
  
  # Hash and Array attribute modifications in clone do not affect original:
  say $o1;
  # OUTPUT: «Bar.new(quux => 42, foo => ["a", "b"], bar => {:a("b"), :c("d")})␤»
  say $o2;
  # OUTPUT: «Bar.new(quux => 42, foo => ["Z", "Y"], bar => {:X("W"), :Z("Y")})␤»
  
  ```
  
  The `|%_` is needed to slurp the rest of the attributes that would have been copied via shallow copy.
  
  ## [method new](#class_Mu "go to top of document")[§](#method_new "direct link")
  
  ```raku
  multi method new(*%attrinit)
  ```
  
  Default method for constructing (create + initialize) new objects of a class. This method expects only named arguments which are then used to initialize attributes with accessors of the same name.
  
  Classes may provide their own `new` method to override this default.
  
  `new` triggers an object construction mechanism that calls submethods named `BUILD` in each class of an inheritance hierarchy, if they exist. See [the documentation on object construction](/language/objects#Object_construction) for more information.
  
  ## [method bless](#class_Mu "go to top of document")[§](#method_bless "direct link")
  
  ```raku
  method bless(*%attrinit --> Mu:D)
  ```
  
  Low-level object construction method, usually called from within `new`, implicitly from the default constructor, or explicitly if you create your own constructor. `bless` creates a new object of the same type as the invocant, using the named arguments to initialize attributes and returns the created object.
  
  It is usually invoked within custom `new` method implementations:
  
  ```raku
  class Point {
      has $.x;
      has $.y;
      multi method new($x, $y) {
          self.bless(:$x, :$y);
      }
  }
  my $p = Point.new(-1, 1);
  
  ```
  
  In this example we are declaring this `new` method to avoid the extra syntax of using pairs when creating the object. `self.bless` returns the object, which is in turn returned by `new`. `new` is declared as a `multi method` so that we can still use the default constructor like this: `Point.new( x => 3, y => 8 )`.
  
  For more details see [the documentation on object construction](/language/objects#Object_construction).
  
  ## [method CREATE](#class_Mu "go to top of document")[§](#method_CREATE "direct link")
  
  ```raku
  method CREATE(--> Mu:D)
  ```
  
  Allocates a new object of the same type as the invocant, without initializing any attributes.
  
  ```raku
  say Mu.CREATE.defined;  # OUTPUT: «True␤»
  ```
  
  ## [method print](#class_Mu "go to top of document")[§](#method_print "direct link")
  
  ```raku
  multi method print(--> Bool:D)
  ```
  
  Prints value to `$*OUT` after stringification using `.Str` method without adding a newline at end.
  
  ```raku
  "abc\n".print;          # OUTPUT: «abc␤»
  ```
  
  ## [method put](#class_Mu "go to top of document")[§](#method_put "direct link")
  
  ```raku
  multi method put(--> Bool:D)
  ```
  
  Prints value to `$*OUT`, adding a newline at end, and if necessary, stringifying non-[`Str`](/type/Str) object using the `.Str` method.
  
  ```raku
  "abc".put;              # OUTPUT: «abc␤»
  ```
  
  ## [method say](#class_Mu "go to top of document")[§](#method_say "direct link")
  
  ```raku
  multi method say()
  ```
  
  Will [`say`](/type/IO/Handle#method_say) to [standard output](/language/variables#index-entry-$*OUT).
  
  ```raku
  say 42;                 # OUTPUT: «42␤»
  ```
  
  What `say` actually does is, thus, deferred to the actual subclass. In [most cases](/routine/say) it calls [`.gist`](/routine/gist) on the object, returning a compact string representation.
  
  In non-sink context, `say` will always return `True`.
  
  ```raku
  say (1,[1,2],"foo",Mu).map: so *.say ;
  # OUTPUT: «1␤[1 2]␤foo␤(Mu)␤(True True True True)␤»
  ```
  
  However, this behavior is just conventional and you shouldn't trust it for your code. It's useful, however, to explain certain behaviors.
  
  `say` is first printing out in `*.say`, but the outermost `say` is printing the `True` values returned by the `so` operation.
  
  ## [method ACCEPTS](#class_Mu "go to top of document")[§](#method_ACCEPTS "direct link")
  
  ```raku
  multi method ACCEPTS(Mu:U: $other)
  ```
  
  `ACCEPTS` is the method that smartmatching with the [infix ~~](/routine/~~) operator and given/when invokes on the right-hand side (the matcher).
  
  The `Mu:U` multi performs a type check. Returns `True` if `$other` conforms to the invocant (which is always a type object or failure).
  
  ```raku
  say 42 ~~ Mu;           # OUTPUT: «True␤»
  say 42 ~~ Int;          # OUTPUT: «True␤»
  say 42 ~~ Str;          # OUTPUT: «False␤»
  ```
  
  Note that there is no multi for defined invocants; this is to allow autothreading of [junctions](/type/Junction), which happens as a fallback mechanism when no direct candidate is available to dispatch to.
  
  ## [method WHICH](#class_Mu "go to top of document")[§](#method_WHICH "direct link")
  
  ```raku
  multi method WHICH(--> ObjAt:D)
  ```
  
  Returns an object of type [`ObjAt`](/type/ObjAt) which uniquely identifies the object. Value types override this method which makes sure that two equivalent objects return the same return value from `WHICH`.
  
  ```raku
  say 42.WHICH eq 42.WHICH;       # OUTPUT: «True␤»
  ```
  
  ## [method WHERE](#class_Mu "go to top of document")[§](#method_WHERE "direct link")
  
  ```raku
  method WHERE(Mu:)
  ```
  
  Returns an [`Int`](/type/Int) representing the memory address of the object. Please note that in the Rakudo implementation of Raku, and possibly other implementations, the memory location of an object is **NOT** fixed for the lifetime of the object. So it has limited use for applications, and is intended as a debugging tool only.
  
  ## [method WHY](#class_Mu "go to top of document")[§](#method_WHY "direct link")
  
  ```raku
  multi method WHY(Mu: --> Pod::Block::Declarator)
  ```
  
  Returns the attached Pod::Block::Declarator.
  
  For instance:
  
  ```raku
  #| Initiate a specified spell normally
  sub cast(Spell $s) {
    do-raw-magic($s);
  }
  #= (do not use for class 7 spells)
  say &cast.WHY;
  # OUTPUT: «Initiate a specified spell normally␤(do not use for class 7 spells)␤»
  
  ```
  
  See [Pod declarator blocks](/language/pod#Declarator_blocks) for details about attaching Pod to variables, classes, functions, methods, etc.
  
  ## [trait is export](#class_Mu "go to top of document")[§](#trait_is_export "direct link")
  
  ```raku
  multi trait_mod:<is>(Mu:U \type, :$export!)
  ```
  
  Marks a type as being exported, that is, available to external users.
  
  ```raku
  my class SomeClass is export { }
  ```
  
  A user of a module or class automatically gets all the symbols imported that are marked as `is export`.
  
  See [Exporting and Selective Importing Modules](/language/modules#Exporting_and_selective_importing) for more details.
  
  ## [method return](#class_Mu "go to top of document")[§](#method_return "direct link")
  
  ```raku
  method return()
  ```
  
  The method `return` will stop execution of a subroutine or method, run all relevant [phasers](/language/phasers#Block_phasers) and provide invocant as a return value to the caller. If a return [type constraint](/language/signatures#Constraining_return_types) is provided it will be checked unless the return value is [`Nil`](/type/Nil). A control exception is raised and can be caught with [CONTROL](/language/phasers#CONTROL).
  
  ```raku
  sub f { (1|2|3).return };
  say f(); # OUTPUT: «any(1, 2, 3)␤»
  ```
  
  ## [method return-rw](#class_Mu "go to top of document")[§](#method_return-rw "direct link")
  
  Same as method [`return`](/type/Mu#method_return) except that `return-rw` returns a writable container to the invocant (see more details here: [`return-rw`](/language/control#return-rw)).
  
  ## [method emit](#class_Mu "go to top of document")[§](#method_emit "direct link")
  
  ```raku
  method emit()
  ```
  
  Emits the invocant into the enclosing [supply](/language/concurrency#index-entry-supply_(on-demand)) or [react](/language/concurrency#react) block.
  
  ```raku
  react { whenever supply { .emit for "foo", 42, .5 } {
      say "received {.^name} ($_)";
  }}
  
  # OUTPUT:
  # received Str (foo)
  # received Int (42)
  # received Rat (0.5)
  ```
  
  ## [method take](#class_Mu "go to top of document")[§](#method_take "direct link")
  
  ```raku
  method take()
  ```
  
  Returns the invocant in the enclosing [gather](/language/control#gather/take) block.
  
  ```raku
  sub insert($sep, +@list) {
      gather for @list {
          FIRST .take, next;
          take slip $sep, .item
      }
  }
  
  say insert ':', <a b c>;
  # OUTPUT: «(a : b : c)␤»
  ```
  
  ## [routine take](#class_Mu "go to top of document")[§](#routine_take "direct link")
  
  ```raku
  sub take(\item)
  ```
  
  Takes the given item and passes it to the enclosing `gather` block.
  
  ```raku
  #| randomly select numbers for lotto
  my $num-selected-numbers = 6;
  my $max-lotto-numbers = 49;
  gather for ^$num-selected-numbers {
      take (1 .. $max-lotto-numbers).pick(1);
  }.say;    # six random values
  ```
  
  ## [routine take-rw](#class_Mu "go to top of document")[§](#routine_take-rw "direct link")
  
  ```raku
  sub take-rw(\item)
  ```
  
  Returns the given item to the enclosing `gather` block, without introducing a new container.
  
  ```raku
  my @a = 1...3;
  sub f(@list){ gather for @list { take-rw $_ } };
  for f(@a) { $_++ };
  say @a;
  # OUTPUT: «[2 3 4]␤»
  ```
  
  ## [method so](#class_Mu "go to top of document")[§](#method_so "direct link")
  
  ```raku
  method so()
  ```
  
  Evaluates the item in Boolean context (and thus, for instance, collapses Junctions), and returns the result. It is the opposite of `not`, and equivalent to the [`?` operator](/language/operators#prefix_?).
  
  One can use this method similarly to the English sentence: "If that is **so**, then do this thing". For instance,
  
  ```raku
  my @args = <-a -e -b -v>;
  my $verbose-selected = any(@args) eq '-v' | '-V';
  if $verbose-selected.so {
      say "Verbose option detected in arguments";
  } # OUTPUT: «Verbose option detected in arguments␤»
  ```
  
  The `$verbose-selected` variable in this case contains a [`Junction`](/type/Junction), whose value is `any(any(False, False), any(False, False), any(False, False), any(True, False))`. That is actually a *truish* value; thus, negating it will yield `False`. The negation of that result will be `True`. `so` is performing all those operations under the hood.
  
  ## [method not](#class_Mu "go to top of document")[§](#method_not "direct link")
  
  ```raku
  method not()
  ```
  
  Evaluates the item in Boolean context (leading to final evaluation of Junctions, for instance), and negates the result. It is the opposite of `so` and its behavior is equivalent to the [`!` operator](/language/operators#prefix_!).
  
  ```raku
  my @args = <-a -e -b>;
  my $verbose-selected = any(@args) eq '-v' | '-V';
  if $verbose-selected.not {
      say "Verbose option not present in arguments";
  } # OUTPUT: «Verbose option not present in arguments␤»
  ```
  
  Since there is also a [prefix version of `not`](/language/operators#prefix_not), this example reads better as:
  
  ```raku
  my @args = <-a -e -b>;
  my $verbose-selected = any(@args) eq '-v' | '-V';
  if not $verbose-selected {
      say "Verbose option not present in arguments";
  } # OUTPUT: «Verbose option not present in arguments␤»
  ```
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Mu`
  
  
  
  raku-type-graph
  
  
  
  Mu
  Mu
  
  
  Any
  Any
  
  
  Any->Mu
  
  
  
  Junction
  Junction
  
  
  Junction->Mu
  
  [Expand chart above](/assets/typegraphs/Mu.svg)
  