package RakuAST::Name

Represent an identifier name

class RakuAST::Name { }

The RakuAST::Name class represents a name (usually an identifier, but not necessarily so), which consists of zero or more parts, and may have additional colonpair (adverb) specification(s).

Object introspection

RakuAST::Name objects are typically created when parsing Raku Programming Language code. So most developers will only need to know how to introspect the objects created.

These introspection methods are available (in alphabetical order):

base-name

dd $name.base-name;

The base-name method returns a clone of the given RakuAST::Name object, but with the last part removed if the last part is empty.

canonicalize

say $name.canonicalize;

The canonicalize returns a string representing the given RakuAST::Name object, or dies when it is impossible to create a string because there are still unresolved parts.

colonpairs

.say for $name.colonpairs;

The colonpairs method returns the "colonpairs" (aka "adverbs") of the RakuAST::Name object as RakuAST::ColonPair objects. For an identifier such as JSON::Fast:ver<0.21>:auth<zef:timo>, it would return RakuAST::ColonPair objects for :ver<0.21> and :auth<zef:timo>.

first-colonpair

dd $name.first-colonpair("ver");

The first-colonpair method returns the first RakuAST::ColonPair::xxx object that matches the given name. Else it returns False.

first-part

say $name.first-part;

The first-part method returns the first "name" part of the RakuAST::Name object as a RakuAST::Name::Part object. For an identifier such as "IO::Path", it would return a RakuAST::Name::Part::Simple object representing "IO".

has-colonpair

say $name.has-colonpair("ver");  # True or False

The has-colonpair method returns True if there is at least one colonpair that has the given name. Else it returns False.

has-colonpairs

say $name.has-colonpairs;  # True or False

The has-colonpairs method returns True if there either are any colonpairs in the RakuAST::Name object. Else it returns False.

is-anonymous

say $name.is-anonymous;  # True or False

The is-anonymous method returns True if there either are two parts and both are empty. Else it returns False.

is-empty

say $name.is-empty;  # True or False

The is-empty method returns True if there either are no parts, or the only part is empty. Else it returns False.

is-global-lookup

say $name.is-global-lookup;  # True or False

The is-global-lookup method returns True if the first part is a RakuAST::Name::Part::Simple object, and its name is "GLOBAL". Else it returns False.

is-identifier

say $name.is-identifier;  # True or False

The is-identifier method returns True if the name can be considered a valid identifier. Else it returns False.

is-indirect-lookup

say $name.is-indirect-lookup;  # True or False

The is-indirect-lookup method returns True if any part of the RakuAST::Name object is a RakuAST::Name::Part::Expression object. Else it returns False.

is-installable

say $name.is-installable;  # True or False

The is-installable method returns True if the name can be considered a valid, installable identifier. Else it returns False.

is-multi-part

say $name.is-multi-part;  # True or False

The is-multi-part method returns True if there is more than one non-empty part in the RakuAST::Name object. Else it returns False.

is-package-lookup

say $name.is-package-lookup;  # True or False

The is-package-lookup method returns True if the last part is a RakuAST::Name::Part::EmptyEdge part. Else it returns False.

is-package-search

say $name.is-package-search;  # True or False

The is-package-search method returns True if the first part is a RakuAST::Name::Part::EmptyEdge part. Else it returns False.

is-pseudo-package

say $name.is-pseudo-package;  # True or False

The is-pseudo-package method returns True if the RakuAST::Name object represents a pseudo-package. Else it returns False.

is-simple

say $name.is-simple;  # True or False

The is-simple method returns False if there is any non-RakuAST::Name::Part::Simple part. Else it returns True.

last-part

say $name.last-part;

The last-part method returns the last "name" part of the RakuAST::Name object as a RakuAST::Name::Part object. For an identifier such as "IO::Path", it would return a RakuAST::Name::Part::Simple object representing "Path".

parts

.say for $name.parts;

The parts method returns the "name" parts of the RakuAST::Name object as RakuAST::Name::Part objects. For an identifier such as "IO::Path", it would return RakuAST::Name::Part::Simple objects for "IO" and "Path".

root-part

say $name.root-part;

The root-part method returns the root "name" part of the RakuAST::Name object as a RakuAST::Name::Part object. It only differs from first-part if the first part of the name is empty. For an identifier such as "::Foo", it would return a RakuAST::Name::Part::Simple object representing "Foo".

simple-identifier

if $name.simple-identifier -> $identifier {
    say $identifier;
}
else {
    say "not a simple identifier";
}

The simple-identifier method returns the string of a simple one-part identifier, or the empty string.

without-colonpair

my $without = $name.without-colonpair("ver");

The without-colonpair method returns a clone of the given RakuAST::Name object without any RakuAST::ColonPair::xxx object that matches the given name.

without-first-part

my $without = $name.without-first-part;

The without-colonpair method returns a clone of the given RakuAST::Name object without the first part.

first-part

say $name.first-part;

has-colonpair

say $name.has-colonpair("ver");  # True or False

The has-colonpair method returns True if there is at least one colonpair that has the given name. Else it returns False.

has-colonpairs

say $name.has-colonpairs;  # True or False

The has-colonpairs method returns True if there either are any colonpairs in the RakuAST::Name object. Else it returns False.

is-anonymous

say $name.is-anonymous;  # True or False

The is-anonymous method returns True if there either are two parts and both are empty. Else it returns False.

is-empty

say $name.is-empty;  # True or False

The is-empty method returns True if there either are no parts, or the only part is empty. Else it returns False.

is-identifier

say $name.is-identifier;  # True or False

The is-identifier method returns True if the name can be considered a valid identifier. Else it returns False.

is-indirect-lookup

say $name.is-indirect-lookup;  # True or False

The is-indirect-lookup method returns True if any part of the RakuAST::Name object is a RakuAST::Name::Part::Expression object. Else it returns False.

is-installable

say $name.is-installable;  # True or False

The is-installable method returns True if the name can be considered a valid, installable identifier. Else it returns False.

is-multi-part

say $name.is-multi-part;  # True or False

The is-multi-part method returns True if there is more than one non-empty part in the RakuAST::Name object. Else it returns False.

is-package-lookup

say $name.is-package-lookup;  # True or False

=head2 Object creation

There are several ways to create a C<RakuAST::Name> object.  For simple
identifiers (without adverbs, aka "colonpairs") it is recommended to use
the alternate C<.from-identifier> and C<.from-identifier-parts> methods
to create a C<RakuAST::Name> object.  Otherwise one can use the standard
C<.new> method.

=head3 new

=begin code
my $name = RakuAST::Name.new(
  RakuAST::Name::Part::Simple.new("Foo"),
  colonpairs => (
    RakuAST::ColonPair::Value.new(
      key   => "ver",
      value => RakuAST::StrLiteral.new("1.1")
    ),
  )
);
dd $name;  # Foo:ver("1.1")

Creates a RakuAST::Name object from the given positional arguments (the name parts, which should be RakuAST::Name::Part::xxx objects) and an optional list of RakuAST::ColonPair::xxx objects (which represent the "adverbs" on the name).

from-identifier

my $name = RakuAST::Name.from-identifier('$foo');
dd $name;  # $foo

Creates a RakuAST::Name object from the given simple identifier string (which may not contain any :: separators).

from-identifier-parts

my $name = RakuAST::Name.from-identifier-parts('IO','Path');
dd $name;  # IO::Path

Creates a RakuAST::Name object from the given simple identifier string parts (which may not contain any :: separators).

Object modifiers

These methods can be used to change an existing RakuAST::Name object.

add-colonpair

my $name = RakuAST::Name.from-identifier("Foo");
$name.add-colonpair(
  RakuAST::ColonPair::Value.new(
    key   => "ver",
    value => RakuAST::StrLiteral.new("1.1")
  )
);
dd $name;  # Foo:ver("1.1")

Adds a RakuAST::ColonPair::xxx object to the list of colonpairs.