## operators.md
## Chunk 4 of 6
 infix:<ne>(Mu,    Mu)
multi infix:<ne>(Str:D, Str:D)
```

String inequality operator.

Coerces both arguments to [`Str`](/type/Str) (if necessary); returns `False` if both are equal.

Mnemonic: *not equal*

## [infix `gt`](#Operators "go to top of document")[§](#infix_gt "direct link")

```raku
multi infix:<gt>(Mu,    Mu)
multi infix:<gt>(Str:D, Str:D)
```

String greater than operator.

Coerces both arguments to [`Str`](/type/Str) (if necessary); returns `True` if the first is larger than the second, as determined by lexicographic comparison.

Mnemonic: *greater than*

## [infix `ge`](#Operators "go to top of document")[§](#infix_ge "direct link")

```raku
multi infix:<ge>(Mu,    Mu)
multi infix:<ge>(Str:D, Str:D)
```

String greater than or equal to operator.

Coerces both arguments to [`Str`](/type/Str) (if necessary); returns `True` if the first is equal to or larger than the second, as determined by lexicographic comparison.

Mnemonic: *greater or equal*

## [infix `lt`](#Operators "go to top of document")[§](#infix_lt "direct link")

```raku
multi infix:<lt>(Mu,    Mu)
multi infix:<lt>(Str:D, Str:D)
```

String less than operator.

Coerces both arguments to [`Str`](/type/Str) (if necessary); returns `True` if the first is smaller than the second, as determined by lexicographic comparison.

Mnemonic: *less than*

## [infix `le`](#Operators "go to top of document")[§](#infix_le "direct link")

```raku
multi infix:<le>(Mu,    Mu)
multi infix:<le>(Str:D, Str:D)
```

String less than or equal to operator.

Coerces both arguments to [`Str`](/type/Str) (if necessary); returns `True` if the first is equal to or smaller than the second, as determined by lexicographic comparison.

Mnemonic: *less or equal*

## [infix `before`](#Operators "go to top of document")[§](#infix_before "direct link")

```raku
multi infix:<before>(Any,       Any)
multi infix:<before>(Real:D,    Real:D)
multi infix:<before>(Str:D,     Str:D)
multi infix:<before>(Version:D, Version:D)
```

Generic ordering, uses the same semantics as [cmp](/routine/cmp). Returns `True` if the first argument is smaller than the second.

## [infix `after`](#Operators "go to top of document")[§](#infix_after "direct link")

```raku
multi infix:<after>(Any,       Any)
multi infix:<after>(Real:D,    Real:D)
multi infix:<after>(Str:D,     Str:D)
multi infix:<after>(Version:D, Version:D)
```

Generic ordering, uses the same semantics as [cmp](/routine/cmp). Returns `True` if the first argument is larger than the second.

## [infix `eqv`](#Operators "go to top of document")[§](#infix_eqv "direct link")

```raku
sub infix:<eqv>(Any, Any)
```

This could be called an equivalence operator, and it will return `True` if the two arguments are structurally the same, i.e. from the same type and (recursively) contain equivalent values.

```raku
say [1, 2, 3] eqv [1, 2, 3];    # OUTPUT: «True␤»
say Any eqv Any;                # OUTPUT: «True␤»
say 1 eqv 2;                    # OUTPUT: «False␤»
say 1 eqv 1.0;                  # OUTPUT: «False␤»
```

Lazy [`Iterable`](/type/Iterable)s cannot be compared, as they're assumed to be infinite. However, the operator will do its best and return `False` if the two lazy [`Iterable`](/type/Iterable)s are of different types or if only one [`Iterable`](/type/Iterable) is lazy.

```raku
say (1…∞) eqv (1…∞).List; # Both lazy, but different types;   OUTPUT: «False␤»
say (1…∞) eqv (1…3);      # Same types, but only one is lazy; OUTPUT: «False␤»
(try say (1…∞) eqv (1…∞)) # Both lazy and of the same type. Cannot compare; throws.
    orelse say $!.^name;  # OUTPUT: «X::Cannot::Lazy␤»
```

In some cases, it will be able to compare lazy operands, as long as they can be iterated

```raku
my $a = lazy ^2;
my $b = $a;
$a.cache;
say $a eqv $b; # OUTPUT: «True␤»

```

When cached, the two lazy [`Seq`](/type/Seq)s can be iterated over, and thus compared.

The default `eqv` operator even works with arbitrary objects. E.g., `eqv` will consider two instances of the same object as being structurally equivalent:

```raku
my class A {
    has $.a;
}
say A.new(a => 5) eqv A.new(a => 5);  # OUTPUT: «True␤»
```

Although the above example works as intended, the `eqv` code might fall back to a slower code path in order to do its job. One way to avoid this is to implement an appropriate infix `eqv` operator:

```raku
my class A {
    has $.a;
}
multi infix:<eqv>(A $l, A $r) { $l.a eqv $r.a }
say A.new(a => 5) eqv A.new(a => 5);            # OUTPUT: «True␤»
```

Note that `eqv` does not work recursively on every kind of container type, e.g. [`Set`](/type/Set):

```raku
my class A {
    has $.a;
}
say Set(A.new(a => 5)) eqv Set(A.new(a => 5));  # OUTPUT: «False␤»
```

Even though the contents of the two sets are `eqv`, the sets are not. The reason is that `eqv` delegates the equality check to the [`Set`](/type/Set) object which relies on element-wise `===` comparison. Turning the class `A` into a value type ([`ValueObjAt`](/type/ValueObjAt)) by giving it a `WHICH` method produces the expected behavior:

```raku
my class A {
    has $.a;
    method WHICH {
        ValueObjAt.new: "A|$!a.WHICH()"
    }
}
say Set(A.new(a => 5)) eqv Set(A.new(a => 5));  # OUTPUT: «True␤»
```

You can call a single-argument version of the operator by using its full name; it will always return true.

```raku
say infix:<eqv>(33);    # OUTPUT: «True␤»
say infix:<eqv>(False); # OUTPUT: «True␤»

```

## [infix `===`](#Operators "go to top of document")[§](#infix_=== "direct link")

```raku
sub infix:<===>(Any, Any)
```

The ASCII equivalent of [`⩶`](#infix_⩶), the value identity operator.

Before Rakudo version 2021.07, the ASCII variant was the *only* variant.

## [infix `⩶`](#Operators "go to top of document")[§](#infix_⩶ "direct link")

```raku
sub infix:<⩶>(Any, Any)
```

⩶ Value identity operator. Returns `True` if both arguments are the same object, disregarding any containerization.

```raku
my class A { };
my $a = A.new;
say $a ⩶ $a;              # OUTPUT: «True␤»
say A.new ⩶ A.new;        # OUTPUT: «False␤»
say A ⩶ A;                # OUTPUT: «True␤»
```

For value types, `⩶` behaves like `eqv`:

```raku
say 'a' ⩶ 'a';            # OUTPUT: «True␤»
say 'a' ⩶ 'b';            # OUTPUT: «False␤»

my $b = 'a';
say $b ⩶ 'a';             # OUTPUT: «True␤»

# different types
say 1 ⩶ 1.0;              # OUTPUT: «False␤»
```

`⩶` uses the [WHICH](/routine/WHICH) method to obtain the object identity.

If you want to create a class that should act as a value type, then that class must create an instance method `WHICH`, that should return a [`ValueObjAt`](/type/ValueObjAt) object that won't change for the lifetime of the object.

The ASCII equivalent of this operator is [`===`](#infix_===).

## [infix `=:=`](#Operators "go to top of document")[§](#infix_=:= "direct link")

```raku
multi infix:<=:=>(Mu \a, Mu \b)
```

Container identity operator. Returns `True` if both arguments are bound to the same container. If it returns `True`, it generally means that modifying one will also modify the other.

```raku
my ($a, $b) = (1, 3);
say $a =:= $b;      # OUTPUT: «False␤»
$b = 2;
say $a;             # OUTPUT: «1␤»
$b := $a;
say $a =:= $b;      # OUTPUT: «True␤»
$a = 5;
say $b;             # OUTPUT: «5␤»
```

The single argument version, called as a routine, will always return True:

```raku
say infix:<=:=>(42);    # OUTPUT: «True␤»
say infix:<=:=>(False); # OUTPUT: «True␤»

```

## [infix `~~`](#Operators "go to top of document")[§](#infix_~~ "direct link")

The smartmatch operator aliases the left-hand side to `$_`, then evaluates the right-hand side and calls `.ACCEPTS($_)` on it. The semantics are left to the type of the right-hand side operand.

Here is a partial list of some of the built-in smartmatching functionality. For full details, see [ACCEPTS](/routine/ACCEPTS) documentation for the type on the right-hand side of the operator.

| Right-hand side | Comparison semantics |
| --- | --- |
| Mu:U | type check |
| Str | string equality |
| Numeric | numeric equality |
| Regex | regex match |
| Callable | Boolean result of invocation |
| Set/Bag | equal element values |
| Any:D | object identity |

## [infix `=~=`](#Operators "go to top of document")[§](#infix_=~= "direct link")

The ASCII equivalent of [`≅`](#infix_≅), the approximately-equal operator.

## [infix `≅`](#Operators "go to top of document")[§](#infix_≅ "direct link")

```raku
multi infix:<≅>(Any, Any)
multi infix:<≅>(Int:D, Int:D)
multi infix:<≅>(Num:D, Num:D)
multi infix:<≅>(Rational:D, Rational:D)
multi infix:<≅>(Real:D, Real:D)
multi infix:<≅>(Complex:D, Complex:D)
multi infix:<≅>(Numeric:D, Numeric:D)
```

The approximately-equal operator `≅` calculates the [relative percentage difference](https://en.wikipedia.org/wiki/Relative_change) between the left-hand and right-hand sides and returns `True` if the difference is less than `$*TOLERANCE` (which defaults to `1e-15`). However, if either side is zero then it checks that the absolute difference between the sides is less than `$*TOLERANCE`.

The ASCII equivalent of this operator is [`=~=`](#infix_=~=).

Note that this operator is not arithmetically symmetrical (doesn't do ± Δ):

```raku
my $x = 1;
say ($x + $*TOLERANCE) ≅ $x;   # OUTPUT: «False␤»
say ($x - $*TOLERANCE) ≅ $x;   # OUTPUT: «True␤»
```

You can change `$*TOLERANCE` lexically:

```raku
{
    my $*TOLERANCE = .1;
    say 11 ≅ 10;        # OUTPUT: «True␤»
}
```

Note that setting `$*TOLERANCE = 0` will cause all comparisons to fail.

```raku
{
    my $*TOLERANCE = 0;
    say 1 ≅ 1;        # OUTPUT: «False␤»
}
```

## [infix (elem), infix ∈](#Operators "go to top of document")[§](#infix_(elem),_infix_∈ "direct link")

```raku
multi infix:<(elem)>($a,$b --> Bool:D)
```

Membership operator.

Returns `True` if `$a` is an **element** of `$b`.

```raku
say 2 (elem) (1, 2, 3); # OUTPUT: «True␤»
say 4 ∈ (1, 2, 3);      # OUTPUT: «False␤»

```

Since release 2020.05, ∊ is an alias for this operator.

## [infix `∉`](#Operators "go to top of document")[§](#infix_∉ "direct link")

```raku
multi infix:<∉>($a,$b --> Bool:D)
```

Non-membership operator.

Returns `True` if `$a` is **not** an **element** of `$b`. Equivalent to `!(elem)`.

```raku
say 4 ∉ (1, 2, 3);       # OUTPUT: «True␤»
say 2 !(elem) (1, 2, 3); # OUTPUT: «False␤»

```

## [infix `(==)`, infix `≡`](#Operators "go to top of document")[§](#infix_(==),_infix_≡ "direct link")

```raku
multi infix:<(==)>($a,$b --> Bool:D)
```

Set equality operator.

Returns `True` if `$a` and `$b` are **identical**.

```raku
say (1, 2, 3) (==) (1, 3, 2); # OUTPUT: «True␤»
say (1, 2, 3) ≡ (1, 2, 4); # OUTPUT: «False␤»

```

## [infix `≢`](#Operators "go to top of document")[§](#infix_≢ "direct link")

```raku
multi infix:<≢>($a,$b --> Bool:D)
```

Set inequality operator.

Returns `True` if `$a` and `$b` are **not identical**. Equivalent to `!(==)`.

```raku
say (1, 2, 3) ≢ (1, 2, 4); # OUTPUT: «True␤»
say (1, 2, 3) ≢ (1, 3, 2); # OUTPUT: «False␤»

```

## [infix (cont), infix ∋](#Operators "go to top of document")[§](#infix_(cont),_infix_∋ "direct link")

```raku
multi infix:<(cont)>($a,$b --> Bool:D)
```

Membership operator.

Returns `True` if `$a` **contains** `$b` as an element.

```raku
say (1,2,3) (cont) 2; # OUTPUT: «True␤»
say (1, 2, 3) ∋ 4;    # OUTPUT: «False␤»

```

Since release 2020.05, ∍ is an alias for this operator.

## [infix `∌`](#Operators "go to top of document")[§](#infix_∌ "direct link")

```raku
multi infix:<∌>($a,$b --> Bool:D)
```

Non-membership operator.

Returns `True` if `$a` does **not** **contain** `$b`. Equivalent to `!(cont)`.

```raku
say (1,2,3) ∌ 4;       # OUTPUT: «True␤»
say (1,2,3) !(cont) 2; # OUTPUT: «False␤»

```

## [infix `(<)`, infix `⊂`](#Operators "go to top of document")[§](#infix_(<),_infix_⊂ "direct link")

```raku
multi infix:«(<)»($a,$b --> Bool:D)
```

Subset of operator.

Returns `True` if `$a` is a **strict subset** of `$b`, i.e., that all the elements of `$a` are elements of `$b` but `$a` is a smaller set than `$b`.

```raku
say (1,2,3) (<) (2,3,1); # OUTPUT: «False␤»
say (2,3) (<) (2,3,1);   # OUTPUT: «True␤»
say 4 ⊂ (1,2,3);         # OUTPUT: «False␤»

```

## [infix `⊄`](#Operators "go to top of document")[§](#infix_⊄ "direct link")

```raku
multi infix:<⊄>($a,$b --> Bool:D)
```

Not a subset of operator.

Returns `True` if `$a` is **not** a `strict subset` of `$b`. Equivalent to `!(<)`.

```raku
say (1,2,3) ⊄ (2,3,1); # OUTPUT: «True␤»
say (2,3) ⊄ (2,3,1);   # OUTPUT: «False␤»
say 4 !(<) (1,2,3);    # OUTPUT: «True␤»

```

## [infix `(<=)`, infix `⊆`](#Operators "go to top of document")[§](#infix_(<=),_infix_⊆ "direct link")

```raku
multi infix:«(<=)»($a,$b --> Bool:D)
```

Subset of or equal to operator.

Returns `True` if `$a` is a **subset** of `$b`, i.e., that all the elements of `$a` are elements of `$b` but `$a` is a smaller or equal sized set than `$b`.

```raku
say (1,2,3) (<=) (2,3,1); # OUTPUT: «True␤»
say (2,3) (<=) (2,3,1);   # OUTPUT: «True␤»
say 4 ⊆ (1,2,3);          # OUTPUT: «False␤»

```

## [infix `⊈`](#Operators "go to top of document")[§](#infix_⊈ "direct link")

```raku
multi infix:<⊈>($a,$b --> Bool:D)
```

Not a subset of nor equal to operator.

Returns `True` if `$a` is **not** a `subset` of `$b`. Equivalent to `!(<=)`.

```raku
say (1,2,3) ⊈ (2,3,1); # OUTPUT: «False␤»
say (2,3) ⊈ (2,3,1);   # OUTPUT: «False␤»
say 4 !(<=) (1,2,3);   # OUTPUT: «True␤»

```

## [infix `(>)`, infix `⊃`](#Operators "go to top of document")[§](#infix_(>),_infix_⊃ "direct link")

```raku
multi infix:«(>)»($a,$b --> Bool:D)
```

Superset of operator.

Returns `True` if `$a` is a **strict superset** of `$b`, i.e., that all the elements of `$b` are elements of `$a` but `$a` is a larger set than `$b`.

```raku
say (1,2,3) (>) (2,3,1); # OUTPUT: «False␤»
say (1,2,3) (>) (2,3);   # OUTPUT: «True␤»
say 4 ⊃ (1,2,3);         # OUTPUT: «False␤»

```

## [infix `⊅`](#Operators "go to top of document")[§](#infix_⊅ "direct link")

```raku
multi infix:<⊅>($a,$b --> Bool:D)
```

Not a superset of operator.

Returns `True` if `$a` is **not** a `strict superset` of `$b`. Equivalent to `!(>)`.

```raku
say (1,2,3) ⊅ (2,3,1); # OUTPUT: «True␤»
say (1,2,3) ⊅ (2,3);   # OUTPUT: «False␤»
say 4 !(>) (1,2,3);    # OUTPUT: «True␤»

```

## [infix `(>=)`, infix `⊇`](#Operators "go to top of document")[§](#infix_(>=),_infix_⊇ "direct link")

```raku
multi infix:«(>=)»($a,$b --> Bool:D)
```

Superset of or equal to operator.

Returns `True` if `$a` is a **superset** of `$b`, i.e., that all the elements of `$b` are elements of `$a` but `$a` is a larger or equal sized set than `$b`.

```raku
say (1,2,3) (>=) (2,3,1); # OUTPUT: «True␤»
say (1,2,3) (>=) (2,3);   # OUTPUT: «True␤»
say 4 ⊇ (1,2,3);          # OUTPUT: «False␤»

```

## [infix `⊉`](#Operators "go to top of document")[§](#infix_⊉ "direct link")

```raku
multi infix:<⊉>($a,$b --> Bool:D)
```

Not a superset of nor equal to operator.

Returns `True` if `$a` is **not** a `superset` of `$b`. Equivalent to `!(>=)`.

```raku
say (1,2,3) ⊉ (2,3,1); # OUTPUT: «False␤»
say (1,2,3) ⊉ (2,3);   # OUTPUT: «False␤»
say 4 !(>=) (1,2,3);   # OUTPUT: «True␤»

```

## [infix `≼`, infix `≽`](#Operators "go to top of document")[§](#infix_≼,_infix_≽ "direct link")

Deprecated. These were removed in v6.d, please use ⊆ and ⊇ operators instead.

# [Tight AND precedence](#Operators "go to top of document")[§](#Tight_AND_precedence "direct link")

## [infix `&&`](#Operators "go to top of document")[§](#infix_&& "direct link")

Returns the first argument that evaluates to `False` in Boolean context, otherwise returns the last argument.

Note that this short-circuits, i.e. if one of the arguments evaluates to a false value, the arguments to the right are never evaluated.

```raku
sub a { 1 }
sub b { 0 }
sub c { die "never called" };
say a() && b() && c();      # OUTPUT: «0␤»
```

# [Tight OR precedence](#Operators "go to top of document")[§](#Tight_OR_precedence "direct link")

## [infix `||`](#Operators "go to top of document")[§](#infix_|| "direct link")

Returns the first argument that evaluates to `True` in Boolean context, otherwise returns the last argument.

Note that this short-circuits; i.e., if one of the arguments evaluates to a true value, the remaining arguments are not evaluated.

```raku
sub a { 0 }
sub b { 1 }
sub c { die "never called" };
say a() || b() || c();      # OUTPUT: «1␤»
```

## [infix `^^`](#Operators "go to top of document")[§](#infix_^^ "direct link")

Short-circuit exclusive-or. Returns the true argument if there is one (and only one). Returns the last argument if all arguments are false. Returns [`Nil`](/type/Nil) when more than one argument is true.

This operator short-circuits in the sense that it does not evaluate any arguments after a 2nd true result.

```raku
say 0 ^^ 42;                             # OUTPUT: «42␤»
say '' ^^ 0;                             # OUTPUT: «0␤»
say 0 ^^ 42 ^^ 1 ^^ die "never called";  # OUTPUT: «Nil␤»
```

Note that the semantics of this operator may not be what you assume: infix `^^` flips to the first true value it finds and then flips to Nil *forever* after the second, no matter how many more true values there are. (In other words, it has "find the one true value" semantics, not "Boolean parity" semantics.)

## [infix `//`](#Operators "go to top of document")[§](#infix_// "direct link")

The defined-or operator or infix // returns the first defined operand, or else the last operand. Short-circuits.

```raku
say Any // 0 // 42;         # OUTPUT: «0␤»
```

## [infix `min`](#Operators "go to top of document")[§](#infix_min "direct link")

Returns the smallest of the arguments, as determined by [cmp](/routine/cmp) semantics.

```raku
my $foo = 42;
$foo min= 0   # read as: $foo decreases to 0
```

**Note:** Before 2022.06, in the cases of ties [`&min`](/type/Any#routine_min) would return the first argument with that value, whereas `&[min]` would return its RHS. After 2022.06, `&[min]` returns its LHS in the case of ties, and now both return the same value as dictated by their List associativity.

```raku
say min 0, False; # OUTPUT: «0␤»
say 0 min False;  # OUTPUT: «0␤»
say min False, 0; # OUTPUT: «False␤»
say False min 0;  # OUTPUT: «False␤»
```

## [infix `max`](#Operators "go to top of document")[§](#infix_max "direct link")

Returns the largest of the arguments, as determined by [cmp](/routine/cmp) semantics.

```raku
my $foo = -42;
$foo max= 0   # read as: $foo increases to 0
```

**Note:** Before 2022.06, in the cases of ties [`&max`](/type/Any#routine_max) would return the first argument with that value, whereas `&[max]` would return its RHS. After 2022.06, `&[max]` returns its LHS in the case of ties, and now both return the same value as dictated by their List associativity.

```raku
say max 0, False; # OUTPUT: «0␤»
say 0 max False;  # OUTPUT: «0␤»
say max False, 0; # OUTPUT: «False␤»
say False max 0;  # OUTPUT: «False␤»
```

## [infix `minmax`](#Operators "go to top of document")[§](#infix_minmax "direct link")

Returns the [`Range`](/type/Range) starting from the lowest to the highest of the values, as determined by the [cmp](/routine/cmp) semantics. For instance:

```raku
# numeric comparison
10 minmax 3;     # 3..10

# string comparison
'10' minmax '3'; # "10".."3"
'z' minmax 'k';  # "k".."z"

```

If the lowest and highest values coincide, the operator returns a [`Range`](/type/Range) made by the same value:

```raku
1 minmax 1;  # 1..1

```

When applied to [`List`](/type/List)s, the operator evaluates the lowest and highest values among all available values:

```raku
(10,20,30) minmax (0,11,22,33);       # 0..33
('a','b','z') minmax ('c','d','w');   # "a".."z"

```

Similarly, when applied to [`Hash`](/type/Hash)es, it performs a [cmp](/routine/cmp) way comparison:

```raku
my %winner = points => 30, misses => 10;
my %loser = points => 20, misses => 10;
%winner cmp %loser;      # More
%winner minmax %loser;
# ${:misses(10), :points(20)}..${:misses(10), :points(30)}

```

# [Conditional operator precedence](#Operators "go to top of document")[§](#Conditional_operator_precedence "direct link")

## [infix `?? !!`](#Operators "go to top of document")[§](#infix_??_!! "direct link")

Also called *ternary* or *conditional* operator, `$condition ?? $true !! $false` evaluates `$condition` and returns the expression right behind ??, in this case `$true` if it is `True`, otherwise evaluates and returns the expression behind !!, `$false` in this case.

## [infix `ff`](#Operators "go to top of document")[§](#infix_ff "direct link")

```raku
sub infix:<ff>(Mu $a, Mu $b)
```

Also called the *flipflop operator*, compares both arguments to `$_` (that is, `$_ ~~ $a` and `$_ ~~ $b`). Evaluates to `False` until the left-hand smartmatch is `True`, at which point it evaluates to `True` until the right-hand smartmatch is `True`.

In effect, the left-hand argument is the "start" condition and the right-hand is the "stop" condition. This construct is typically used to pick up only a certain section of lines. For example:

```raku
my $excerpt = q:to/END/;
Here's some unimportant text.
=begin code
    This code block is what we're after.
    We'll use 'ff' to get it.
=end code
More unimportant text.
END

my @codelines = gather for $excerpt.lines {
    take $_ if "=begin code" ff "=end code"
}
# this will print four lines, starting with "=begin code" and ending with
# "=end code"
say @codelines.join("\n");

```

After matching the start condition, the operator will then match the same `$_` to the stop condition and act accordingly if successful. In this example, only the first element is printed:

```raku
for <AB C D B E F> {
    say $_ if /A/ ff /B/;  # OUTPUT: «AB␤»
}
```

If you only want to test against a start condition and have no stop condition, `*` can be used as such.

```raku
for <A B C D E> {
    say $_ if /C/ ff *;    # OUTPUT: «C␤D␤E␤»
}
```

For the `sed`-like version, which does *not* try `$_` on the stop condition after succeeding on the start condition, see [fff](/routine/fff).

This operator cannot be overloaded, as it's handled specially by the compiler.

## [infix `^ff`](#Operators "go to top of document")[§](#infix_^ff "direct link")

```raku
sub infix:<^ff>(Mu $a, Mu $b)
```

Works like [ff](/routine/ff), except it does not return `True` for items matching the start condition (including items also matching the stop condition).

A comparison:

```raku
my @list = <X A B C Y>;
say $_ if /A/ ff /C/ for @list;    # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^ff /C/ for @list;   # OUTPUT: «B␤C␤»
```

The sed-like version can be found in [`^fff`](/routine/$CIRCUMFLEX_ACCENTfff).

This operator cannot be overloaded, as it's handled specially by the compiler.

## [infix `ff^`](#Operators "go to top of document")[§](#infix_ff^ "direct link")

```raku
sub infix:<ff^>(Mu $a, Mu $b)
```

Works like [ff](/routine/ff), except it does not return `True` for items matching the stop condition (including items that first matched the start condition).

```raku
my @list = <X A B C Y>;
say $_ if /A/ ff /C/ for @list;    # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ff^ /C/ for @list;   # OUTPUT: «A␤B␤»
```

The sed-like version can be found in [fff^](/routine/fff$CIRCUMFLEX_ACCENT).

This operator cannot be overloaded, as it's handled specially by the compiler.

## [infix `^ff^`](#Operators "go to top of document")[§](#infix_^ff^ "direct link")

```raku
sub infix:<^ff^>(Mu $a, Mu $b)
```

Works like [ff](/routine/ff), except it does not return `True` for items matching either the stop or start condition (or both).

```raku
my @list = <X A B C Y>;
say $_ if /A/ ff /C/ for @list;    # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^ff^ /C/ for @list;  # OUTPUT: «B␤»
```

The sed-like version can be found in [`^fff^`](/routine/$CIRCUMFLEX_ACCENTfff$CIRCUMFLEX_ACCENT).

This operator cannot be overloaded, as it's handled specially by the compiler.

## [infix `fff`](#Operators "go to top of document")[§](#infix_fff "direct link")

```raku
sub infix:<fff>(Mu $a, Mu $b)
```

Performs a sed-like flipflop operation, wherein it returns `False` until the left argument smartmatches against `$_`, then returns `True` until the right argument smartmatches against `$_`.

Works similarly to [ff](/routine/ff), except that it only tries one argument per invocation. That is, if `$_` smartmatches the left argument, `fff` will **not** then try to match that same `$_` against the right argument.

```raku
for <AB C D B E F> {
    say $_ if /A/ fff /B/;         # OUTPUT: «AB␤C␤D␤B␤»
}
```

The non-sed-like flipflop (which after successfully matching the left argument against `$_` will try that same `$_` against the right argument and act accordingly). See [ff](/routine/ff).

This operator cannot be overloaded, as it's handled specially by the compiler.

## [infix `^fff`](#Operators


## operators.md
## Chunk 5 of 6
 "go to top of document")[§](#infix_^fff "direct link")

```raku
sub infix:<^fff>(Mu $a, Mu $b)
```

Like [fff](/routine/fff), except it does not return true for matches to the left argument.

```raku
my @list = <X A B C Y>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^fff /C/ for @list;  # OUTPUT: «B␤C␤»
```

For the non-sed version, see [`^ff`](/routine/$CIRCUMFLEX_ACCENTff).

This operator cannot be overloaded, as it's handled specially by the compiler.

## [infix `fff^`](#Operators "go to top of document")[§](#infix_fff^ "direct link")

```raku
sub infix:<fff^>(Mu $a, Mu $b)
```

Like [fff](/routine/fff), except it does not return true for matches to the right argument.

```raku
my @list = <X A B C Y>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ fff^ /C/ for @list;  # OUTPUT: «A␤B␤»
```

For the non-sed version, see [ff^](/routine/ff$CIRCUMFLEX_ACCENT).

This operator cannot be overloaded, as it's handled specially by the compiler.

## [infix `^fff^`](#Operators "go to top of document")[§](#infix_^fff^ "direct link")

```raku
sub infix:<^fff^>(Mu $a, Mu $b)
```

Like [fff](/routine/fff), except it does not return true for matches to either the left or right argument.

```raku
my @list = <X A B C Y>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^fff^ /C/ for @list; # OUTPUT: «B␤»
```

For the non-sed version, see [`^ff^`](/routine/$CIRCUMFLEX_ACCENTff$CIRCUMFLEX_ACCENT).

This operator cannot be overloaded, as it's handled specially by the compiler.

# [Item assignment precedence](#Operators "go to top of document")[§](#Item_assignment_precedence "direct link")

## [infix `=` (item assignment)](#Operators "go to top of document")[§](#infix_=_(item_assignment) "direct link")

```raku
sub infix:<=>(Mu $a is rw, Mu $b)

```

Called the *item assignment operator*. It copies the value of the right-hand side into the Scalar container on the left-hand side.

The item assignment operator should be distinguished from the [list assignment operator](#infix_=_(list_assignment)), which uses the same operator symbol `=` but has a lower precedence. The context of the left-hand side of the `=` symbol determines whether it is parsed as item assignment or list assignment. See the section on [item and list assignment](/language/variables#Item_and_list_assignment) for a comparative discussion of the two assignment types.

## [infix `=>`](#Operators "go to top of document")[§](#infix_=> "direct link")

```raku
sub infix:«=>»($key, Mu $value --> Pair:D)
```

[`Pair`](/type/Pair) constructor.

Constructs a [`Pair`](/type/Pair) object with the left-hand side as the key and the right-hand side as the value.

Note that the `=>` operator is syntactically special-cased, in that it allows unquoted identifier on the left-hand side.

```raku
my $p = a => 1;
say $p.key;         # OUTPUT: «a␤»
say $p.value;       # OUTPUT: «1␤»
```

A [`Pair`](/type/Pair) within an argument list with an unquoted identifier on the left is interpreted as a named argument.

See [the Terms language documentation](/language/terms#Pair) for more ways to create [`Pair`](/type/Pair) objects.

# [Loose unary precedence](#Operators "go to top of document")[§](#Loose_unary_precedence "direct link")

## [prefix `not`](#Operators "go to top of document")[§](#prefix_not "direct link")

```raku
multi prefix:<not>(Mu $x --> Bool:D)
```

Evaluates its argument in Boolean context (and thus collapses [`Junction`](/type/Junction)s), and negates the result. Please note that `not` is easy to misuse. See [traps](/language/traps#Loose_Boolean_operators).

## [prefix `so`](#Operators "go to top of document")[§](#prefix_so "direct link")

```raku
multi prefix:<so>(Mu $x --> Bool:D)
```

Evaluates its argument in Boolean context (and thus collapses [`Junction`](/type/Junction)s), and returns the result.

# [Comma operator precedence](#Operators "go to top of document")[§](#Comma_operator_precedence "direct link")

## [infix `,`](#Operators "go to top of document")[§](#infix_, "direct link")

```raku
sub infix:<,>(*@a --> List:D) is assoc<list>
```

Constructs a higher-order [`Cool`](/type/Cool) from its arguments.

```raku
my @list = :god('Þor'), ['is',"mighty"];
say @list;      # OUTPUT: «[god => Þor [is mighty]]␤»
my %hash = :god('Þor'), :is("mighty");
say %hash.raku; # OUTPUT: «{:god("Þor"), :is("mighty")}␤»
my %a = :11a, :22b;
say %(%a, :33x);  # OUTPUT: «{a => 11, b => 22, x => 33}␤»
```

In the first case it returns a [`List`](/type/List), in the second case, since the arguments are [`Pair`](/type/Pair)s, it builds a [`Hash`](/type/Hash).

It can also be used for constructing variables from other variables, collating elements of different types, in this case a [`Hash`](/type/Hash) and a [`Pair`](/type/Pair):

```raku
my %features = %hash, :wields("hammer");
say %features;  # OUTPUT: «{god => Þor, is => mighty, wields => hammer}␤»

```

The comma is also used syntactically as the separator of arguments in calls.

## [infix `:`](#Operators "go to top of document")[§](#infix_: "direct link")

Used as an argument separator just like infix `,` and marks the argument to its left as the invocant. That turns what would otherwise be a function call into a method call.

```raku
substr('abc': 1);       # same as 'abc'.substr(1)
```

Infix `:` is only allowed after the first argument of a non-method call. In other positions, it's a syntax error.

# [List infix precedence](#Operators "go to top of document")[§](#List_infix_precedence "direct link")

## [infix `Z`](#Operators "go to top of document")[§](#infix_Z "direct link")

```raku
sub infix:<Z>(**@lists --> Seq:D) is assoc<list>
```

The Zip operator interleaves the lists passed to `Z` like a zipper, taking index-corresponding elements from each operand. The returned [`Seq`](/type/Seq) contains nested lists, each with a value from every operand in the chain. If one of the operands runs out of elements prematurely, the zip operator will stop.

```raku
say (1, 2 Z <a b c> Z <+ ->).raku;
# OUTPUT: «((1, "a", "+"), (2, "b", "-")).Seq␤»
for <a b c> Z <1 2 3 4> -> [$l, $r] {
    say "$l:$r"
}
# OUTPUT: «a:1␤b:2␤c:3␤»

```

The `Z` operator also exists as a metaoperator, in which case the inner lists are replaced by the value from applying the operator to the list:

```raku
say 100, 200 Z+ 42, 23;             # OUTPUT: «(142 223)␤»
say 1..3 Z~ <a b c> Z~ 'x' xx 3;    # OUTPUT: «(1ax 2bx 3cx)␤»
```

As any other infix operator, it can be used under its full name:

```raku
say infix:<Z>(<a b>,<c d>);             # OUTPUT: «((a c) (b d))␤»

```

If no argument is given, it will return an empty [`Seq`](/type/Seq)

```raku
say infix:<Z>();                        # OUTPUT: «()␤»

```

## [infix `X`](#Operators "go to top of document")[§](#infix_X "direct link")

```raku
multi infix:<X>(+lol, :&with! --> Seq:D)
multi infix:<X>(+lol --> Seq:D)
```

Creates a cross product from all the lists, ordered so that the rightmost elements vary most rapidly, and returns a [`Seq`](/type/Seq):

```raku
1..3 X <a b c> X 9
# produces ((1 a 9) (1 b 9) (1 c 9)
#           (2 a 9) (2 b 9) (2 c 9)
#           (3 a 9) (3 b 9) (3 c 9))
```

The `X` operator also exists as a metaoperator, in which case the inner lists are replaced by the value from applying the operator to the list:

```raku
1..3 X~ <a b c> X~ 9
# produces (1a9 1b9 1c9 2a9 2b9 2c9 3a9 3b9 3c9)
```

## [infix `...`](#Operators "go to top of document")[§](#infix_... "direct link")

```raku
multi infix:<...>(**@) is assoc<list>
multi infix:<...^>(**@) is assoc<list>
multi infix:<^...>(**@) is assoc<list>
multi infix:<^...^>(**@) is assoc<list>
```

The sequence operator, which can be written either as `...` or as `…`, with variants `...^`, `^...`, `^...^`, `…^`, `^…` and `^…^`, will produce (possibly lazy) generic sequences on demand. Such sequences are of the [`Seq`](/type/Seq) type.

The variants of the operator with an initial caret, `^...`, `^...^`, `^…` and `^…^`, produce sequences that do not contain the initial element.

The variants of the operator with a final caret, `...^`, `^...^`, `…^` and `^…^`, produce sequences that do not contain the final element.

Note: the variants `^...`, `^...^`, `^…` and `^…^` have been available in Rakudo compiler starting from 2020.05 release.

The left-hand side of the operator specify the initial elements; it may include a generator after the first element or elements. The right-hand side will have an endpoint, which can be `Inf` or `*` for "infinite" lists (that is, *lazy* lists whose elements are only produced on demand), an expression which will end the sequence when `True`, or other elements such as [`Junction`](/type/Junction)s.

The sequence operator invokes the generator with as many arguments as necessary. The arguments are taken from the initial elements and the already generated elements.

An endpoint of `*` ([`Whatever`](/type/Whatever)), `Inf` or `∞` generates on demand an infinite sequence, with a default generator of `*.succ`

```raku
say (1 ... *)[^5];  # OUTPUT: «(1 2 3 4 5)␤»
```

Custom generators need to be the last element of the list before the '...' operator. This one takes two arguments, and generates the eight first Fibonacci numbers

```raku
say (1, 1, -> $a, $b { $a + $b } ... *)[^8]; # OUTPUT: «(1 1 2 3 5 8 13 21)␤»
# same but shorter
say (1, 1, * + * ... *)[^8];                 # OUTPUT: «(1 1 2 3 5 8 13 21)␤»

```

The generator can also take only one argument.

```raku
say 5, { $_ * 2 } ... 40;                # OUTPUT: «5 10 20 40␤»
```

Or it can use the [anonymous state variable `$`](/language/variables#index-entry-$_(variable)) to skip one position in the sequence when computing the next one:

```raku
say (1, 1, 1, -> $a, $b, $ { $a + $b } … ∞)[3..10];
# OUTPUT: «(2 2 3 4 5 7 9 12)␤»
```

There must be at least as many initial elements as arguments to the generator.

If the endpoint is not `*`, it's smartmatched against each generated element and the sequence is terminated when the smartmatch succeeded. The final element is excluded of the sequence if a sequence operator variant with a final caret is used, it is included otherwise.

This allows you to write

```raku
say 1, 1, * + * ...^ *>= 100;
# OUTPUT: «(1 1 2 3 5 8 13 21 34 55 89)␤»
```

to generate all Fibonacci numbers up to but excluding 100.

The `...` operators consider the initial values as "generated elements" as well, so they are also checked against the endpoint:

```raku
my $end = 4;
say 1, 2, 4, 8, 16 ... $end;
# OUTPUT: «(1 2 4)␤»
```

If you do not provide a generator, the sequence operator tries to deduce the sequence. In most cases, this means using a default `*.`[succ](/routine/succ) or `*.`[pred](/routine/pred), depending on how the end points compare:

```raku
say 1 ... 4;        # OUTPUT: «(1 2 3 4)␤»
say 4 ... 1;        # OUTPUT: «(4 3 2 1)␤»
say 1 ^... 4;       # OUTPUT: «(2 3 4)␤»
say 1 ...^ 4;       # OUTPUT: «(1 2 3)␤»
say 1 ^...^ 4;      # OUTPUT: «(2 3)␤»
say 'a' ... 'e';    # OUTPUT: «(a b c d e)␤»
say 'e' ... 'a';    # OUTPUT: «(e d c b a)␤»
```

However, the sequence operator will deduce a different sequence in some special cases.

If you provide more than one initial element and all initial elements are numeric, the sequence operator tries find an arithmetic or geometric sequence that fits the pattern in the initial elements:

```raku
say 2, 4, 6 ... 12;     # OUTPUT: «(2 4 6 8 10 12)␤»
say 1, 2, 4 ... 32;     # OUTPUT: «(1 2 4 8 16 32)␤»
say 1, 2, 4 ^... 32;    # OUTPUT: «(2 4 8 16 32)␤»
say 1, 2, 4 ^...^ 32;   # OUTPUT: «(2 4 8 16)␤»
```

If you provide one [`Str`](/type/Str) initial element and a [`Str`](/type/Str) final element with the same number of characters, then the sequence operator will deduce a sequence of all strings where each letter is `le` the letter at the corresponding position in the final element:

```raku
say 'aa' … 'cc';          # OUTPUT: «(aa ab ac ba bb bc ca cb cc)␤»
# Which is the same as
say 'a'..'c' X~ 'a'..'c'; # OUTPUT: «(aa ab ac ba bb bc ca cb cc)␤»
```

# [List prefix precedence](#Operators "go to top of document")[§](#List_prefix_precedence "direct link")

## [infix `=` (list assignment)](#Operators "go to top of document")[§](#infix_=_(list_assignment) "direct link")

The list assignment operator generally copies values from its right-hand side into the container on its left-hand side. Its exact semantics are left to the left-hand side container type. See [`Array`](/type/Array) and [`Hash`](/type/Hash) for common cases.

The list assignment operator should be distinguished from the [item assignment operator](#infix_=_(item_assignment)), which uses the same operator symbol `=` but has a higher precedence. The context of the left-hand side of the `=` symbol determines whether it is parsed as item assignment or list assignment. See the section on [item and list assignment](/language/variables#Item_and_list_assignment) for a comparative discussion of the two assignment types.

## [infix `:=`](#Operators "go to top of document")[§](#infix_:= "direct link")

Binding operator. Whereas `$x = $y` puts the value in `$y` into `$x`, `$x := $y` makes `$x` and `$y` the same thing.

```raku
my $a = 42;
my $b = $a;
$b++;
say $a;
```

This will output 42, because `$a` and `$b` both contained the number `42`, but the [containers](/language/containers#Binding) were different.

```raku
my $a = 42;
my $b := $a;
$b++;
say $a;
```

This will output 43, since `$b` and `$a` both represented the same object.

If type constrains on variables or containers are present a type check will be performed at runtime. On failure `X::TypeCheck::BindingType` will be thrown.

Please note that `:=` is a compile time operator. As such it can not be referred to at runtime and thus can't be used as an argument to metaoperators.

## [infix `::=`](#Operators "go to top of document")[§](#infix_::= "direct link")

Read-only binding operator, not yet implemented in Rakudo. See [`infix :=`](/routine/:=).

## [listop `...`](#Operators "go to top of document")[§](#listop_... "direct link")

Called the *yada, yada, yada* operator or *stub* operator, if it's the only statement in a routine or type, it marks that routine or type as a stub (which is significant in the context of pre-declaring types and composing roles).

If the `...` statement is executed, it calls [fail](/routine/fail), with the default message `Stub code executed`.

This operator can be used for forward declarations of classes:

```raku
class Foo {...}
class Bar {
    has Foo $.foo;
}
class Foo {
    say "This is a Foo object";
}

```

or routines, such as this [`Sub`](/type/Sub):

```raku
sub a() { ... }
say a;           # OUTPUT: «42␤»
sub a() { 42 }

```

Please note that, in this case, it's not really necessary, and it will work the same without that forward declaration.

## [listop `!!!`](#Operators "go to top of document")[§](#listop_!!! "direct link")

If it's the only statement in a routine or type, it marks that routine or type as a stub (which is significant in the context of pre-declaring types and composing roles).

If the `!!!` statement is executed, it calls [die](/routine/die), with the default message `Stub code executed`.

## [listop `???`](#Operators "go to top of document")[§](#listop_??? "direct link")

If it's the only statement in a routine or type, it marks that routine or type as a stub (which is significant in the context of pre-declaring types and composing roles).

If the `???` statement is executed, it calls [warn](/routine/warn), with the default message `Stub code executed`.

## [Reduction operators](#Operators "go to top of document")[§](#Reduction_operators "direct link")

Any infix operator (except for non-associating operators) can be surrounded by square brackets in term position to create a list operator that reduces using that operation.

```raku
say [+] 1, 2, 3;      # 1 + 2 + 3 = 6
my @a = (5, 6);
say [*] @a;           # 5 * 6 = 30
```

Reduction operators have the same associativity as the operators they are based on.

```raku
say [-] 4, 3, 2;      # 4-3-2 = (4-3)-2 = -1
say [**] 4, 3, 2;     # 4**3**2 = 4**(3**2) = 262144
```

Applying [+] to a single element will return that element

```raku
say [+] 42;           # OUTPUT: «42␤»

```

# [Loose AND precedence](#Operators "go to top of document")[§](#Loose_AND_precedence "direct link")

## [`and`](#Operators "go to top of document")[§](#infix_and "direct link")

Same as [infix &&](#infix_%26%26), except with looser precedence.

Short-circuits so that it returns the first operand that evaluates to `False`, otherwise returns the last operand. Note that `and` is easy to misuse, see [traps](/language/traps#Loose_Boolean_operators).

## [`andthen`](#Operators "go to top of document")[§](#infix_andthen "direct link")

The `andthen` operator returns [`Empty`](/type/Slip#constant_Empty) upon encountering the first [undefined](/routine/defined) argument, otherwise the last argument. Last argument is returned as-is, without being checked for definedness at all. Short-circuits. The result of the left side is bound to `$_` for the right side, or passed as arguments if the right side is a [`Callable`](/type/Callable), whose [count](/routine/count) must be `0` or `1`.

A handy use of this operator is to alias a routine's return value to `$_` and to do additional manipulation with it, such as printing or returning it to caller. Since the `andthen` operator short-circuits, statements on the right-hand side won't get executed, unless left-hand side is defined (tip: [`Failure`](/type/Failure)s are never defined, so you can handle them with this operator).

```raku
sub load-data {
    rand  > .5 or return; # simulated load data failure; return Nil
    (rand > .3 ?? 'error' !! 'good data') xx 10 # our loaded data
}
load-data.first: /good/ andthen say "$_ is good";
# OUTPUT: «(good data is good)␤»

load-data() andthen .return; # return loaded data, if it's defined
die "Failed to load data!!";
```

The above example will print `good data is good` only if the subroutine returned any items that match `/good/` and will die unless loading data returned a defined value. The aliasing behavior lets us pipe the values across the operator.

The `andthen` operator is a close relative of the [`with` statement modifier](/language/control#with_orwith_without), and some compilers compile `with` to `andthen`, meaning these two lines have equivalent behavior:

```raku
.say with 42;
42 andthen .say;
```

## [`notandthen`](#Operators "go to top of document")[§](#infix_notandthen "direct link")

The `notandthen` operator returns [`Empty`](/type/Slip#constant_Empty) upon encountering the first [defined](/routine/defined) argument, otherwise the last argument. Last argument is returned as-is, without being checked for definedness at all. Short-circuits. The result of the left side is bound to `$_` for the right side, or passed as arguments if the right side is a [`Callable`](/type/Callable), whose [count](/routine/count) must be `0` or `1`.

At first glance, [notandthen](/routine/notandthen) might appear to be the same thing as the [orelse](/routine/orelse) operator. The difference is subtle: [notandthen](/routine/notandthen) returns [`Empty`](/type/Slip#constant_Empty) when it encounters a [defined](/routine/defined) item (that isn't the last item), whereas [orelse](/routine/orelse) returns that item. In other words, [notandthen](/routine/notandthen) is a means to act when items aren't defined, whereas [orelse](/routine/orelse) is a means to obtain the first defined item:

```raku
sub all-sensors-down     { [notandthen] |@_, True             }
sub first-working-sensor { [orelse]     |@_, 'default sensor' }

all-sensors-down Nil, Nil, Nil
  and say 'OMG! All sensors are down!'; # OUTPUT:«OMG! All sensors are down!␤»
say first-working-sensor Nil, Nil, Nil; # OUTPUT:«default sensor␤»

all-sensors-down Nil, 42, Nil
  and say 'OMG! All sensors are down!'; # No output
say first-working-sensor Nil, 42, Nil;  # OUTPUT:«42␤»

```

The `notandthen` operator is a close relative of the [`without` statement modifier](/language/control#with_orwith_without), and some compilers compile `without` to `notandthen`, meaning these two lines have equivalent behavior:

```raku
sub good-things { fail }

'boo'.say without good-things;
good-things() notandthen 'boo'.say;

```

# [Loose OR precedence](#Operators "go to top of document")[§](#Loose_OR_precedence "direct link")

## [infix `or`](#Operators "go to top of document")[§](#infix_or "direct link")

Same as [infix `||`](/routine/||), except with looser precedence.

Returns the first argument that evaluates to `True` in Boolean context, or otherwise the last argument, it short-circuits. Please note that `or` is easy to misuse. See [traps](/language/traps#Loose_Boolean_operators).

## [infix `orelse`](#Operators "go to top of document")[§](#infix_orelse "direct link")

The `orelse` operator is similar to `infix //`, except with looser precedence and `$_` aliasing.

Returns the first defined argument, or else the last argument. Last argument is returned as-is, without being checked for definedness at all. Short-circuits. The result of the left side is bound to `$_` for the right side, or passed as an argument if the right side is a [`Callable`](/type/Callable), whose [count](/routine/count) must be `0` or `1`.

This operator is useful for handling [`Failure`](/type/Failure)s returned by routines since the expected value is usually [defined](/routine/defined) and [`Failure`](/type/Failure) never is:

```raku
sub meows { ++$ < 4 ?? fail 'out of meows!' !! '🐱' }

sub meows-processor1 { meows() orelse .return } # return handled Failure
sub meows-processor2 { meows() orelse fail $_ } # return re-armed Failure
sub meows-processor3 {
    # Use non-Failure output, or else print a message that stuff's wrong
    meows() andthen .say orelse ‘something's wrong’.say;
}

say "{.^name}, {.handled}"  # OUTPUT: «Failure, True␤»
    given meows-processor1;
say "{.^name}, {.handled}"  # OUTPUT: «Failure, False␤»
    given meows-processor2;
meows-processor3;           # OUTPUT: «something's wrong␤»
meows-processor3;           # OUTPUT: «🐱␤»
```

## [infix `xor`](#Operators "go to top of document")[§](#infix_xor "direct link")

Same as [infix `^^`](/routine/$CIRCUMFLEX_ACCENT$CIRCUMFLEX_ACCENT), except with looser precedence.

Returns the operand that evaluates to `True` in Boolean context, if and only if the other operand evaluates to `False` in Boolean context. If both operands evaluate to `False`, returns the last argument. If both operands evaluate to `True`, returns [`Nil`](/type/Nil).

When chaining, returns the operand that evaluates to `True`, if and only if there is one such operand. If more than one operand is true, it short-circuits after evaluating the second and returns [`Nil`](/type/Nil). If all operands are false, returns the last one.

# [Sequencer precedence](#Operators "go to top of document")[§](#Sequencer_precedence "direct link")

## [infix `==>`](#Operators "go to top of document")[§](#infix_==> "direct link")

This feed operator takes the result from the left and passes it to the next (right) routine as the last parameter.

```raku
my @array = (1, 2, 3, 4, 5);
@array ==> sum() ==> say();   # OUTPUT: «15␤»
```

This simple example, above, is the equivalent of writing:

```raku
my @array = (1, 2, 3, 4, 5);
say(sum(@array));             # OUTPUT: «15␤»
```

Or if using methods:

```raku
my @array = (1, 2, 3, 4, 5);
@array.sum.say;               # OUTPUT: «15␤»
```

The precedence is very loose so you will need to use parentheses to assign the result or you can even just use another feed operator! In the case of routines/methods that take a single argument or where the first argument is a block, it's often required that you call with parentheses (though this is not required for the very last routine/method).

This "traditional" structure, read bottom-to-top, with the last two lines creating the data structure that is going to be processed

```raku
my @fractions = <TWO THREE FOUR FIVE SEVEN> »~» " " X~ <FIFTHS SIXTHS EIGHTHS>;
my @result = map { .uniparse },                    # (3) Converts to unicode
    grep { .uniparse },                            # (2) Checks if it parses
    map( {"VULGAR FRACTION " ~ $^þ }, @fractions); # (1) Adds string to input

# @result is [⅖ ⅗ ⅜ ⅘ ⅚ ⅝ ⅞]
```

Now we use the feed operator (left-to-right) with parentheses, read top-to-bottom

```raku
my @result = (
    <TWO THREE FOUR FIVE SEVEN> »~» " " X~ <FIFTHS SIXTHS EIGHTHS> # (1) Input
    ==> map( {"VULGAR FRACTION " ~ $^þ } )                         # (2) Converts to Unicode name
    ==> grep({ .uniparse })                                        # (3) Filters only real names
    ==> map( { .uniparse} );                                       # (4) Converts to unicode
);
```

For illustration, method chaining equivalent, read top-to-bottom, using the same sequence as above

```raku
my @result = ( <TWO THREE FOUR FIVE SEVEN> »~» " " X~ <FIFTHS SIXTHS EIGHTHS>)
    .map( {"VULGAR FRACTION " ~ $^þ } )
    .grep({ .uniparse })
    .map({ .uniparse });
```

Although in this particular case the result is the same, the feed operator `==>` more clearly shows intent with arrow pointing in the direction of the data flow. To assign without the need of parentheses use another feed operator

```raku
<people of earth>
    ==> map({ .tc })
    ==> grep /<[PE]>/
    ==> sort()
    ==> my @result;
```

It can be useful to capture a partial result, however, unlike the leftward feed operator, it does require parentheses or a semicolon

```raku
<people of earth>
    ==> map({ .tc })
    ==> my @caps; @caps   # also could wrap in parentheses: (my @caps)
    ==> grep /<[PE]>/
    ==> sort()
    ==> my @result;
```

The feed operator lets you construct method-chaining-like patterns out of routines and the results of methods on unrelated data. In method-chaining, you are restricted to the methods available on the data or the result of previous method call. With feed operators, that restriction is gone. The resulting code could also be seen to be more readable than a series of method calls broken over multiple lines.

Note: In the future, this operator will see some change as it gains the ability to run list operations in parallel. It will enforce that the **left** operand is enclosable as a closure (that can be cloned and run in a subthread).

## [infix `<==`](#Operators "go to top of document")[§](#infix_<== "direct link")

This leftward feed operator takes the result from the right and passes it to the previous (left) routine as the last parameter. This elucidates the right-to-left dataflow for a series of list manipulating functions.

```raku
# Traditional structure, read bottom-to-top
my @result =
    sort                   # (4) Sort, result is <Earth People>
    grep { /<[PE]>/ },     # (3) Look for P or E
    map { .tc },           # (2) Capitalize the words
    <people of earth>;     # (1) Start with the input

# Feed (right-to-left) with parentheses, read bottom-to-top
my @result = (
    sort()                 # (4) Sort, result is <Earth People>
    <== grep({ /<[PE]>/ }) # (3) Look for P or E
    <== map({ .tc })       # (2) Capitalize the words
    <== <people of earth>  # (1) Start with the input
);

# To assign without parentheses, use another feed operator
my @result
    <== sort()              # (4) Sort, result is <Earth People>
    <== grep({ /<[PE]>/ })  # (3) Look for P or E
    <== map({ .tc })        # (2)


## operators.md
## Chunk 6 of 6
 Capitalize the words
    <== <people of earth>;  # (1) Start with the input

# It can be useful to capture a partial result
my @result
    <== sort()
    <== grep({ /<[PE]>/ })
    <== my @caps            # unlike ==>, there's no need for additional statement
    <== map({ .tc })
    <== <people of earth>;
```

Unlike the rightward feed operator, the result is not closely mappable to method-chaining. However, compared to the traditional structure above where each argument is separated by a line, the resulting code is more demonstrative than commas. The leftward feed operator also allows you to "break into" the statement and capture an intermediary result which can be extremely useful for debugging or to take that result and create another variation on the final result.

Note: In the future, this operator will see some change as it gains the ability to run list operations in parallel. It will enforce that the **right** operand is enclosable as a closure (that can be cloned and run in a subthread).

# [Identity](#Operators "go to top of document")[§](#Identity "direct link")

In general, infix operators can be applied to a single or no element without yielding an error, generally in the context of a [reduce](/routine/reduce) operation.

```raku
say [-] ()  # OUTPUT: «0␤»
```

The design documents specify that this should return [an identity value](https://en.wikipedia.org/wiki/Identity_element), and that an identity value [must be specified for every operator](http://design.raku.org/S03.html#Reduction_operators). In general, the identity element returned should be intuitive. However, here is a table that specifies how it is defined for operator classes in Raku, which corresponds to the table in the above definition in the types and operators defined by the language:

| Operator class | Identity value |
| --- | --- |
| Equality | True |
| Arithmetic + | 0 |
| Arithmetic \* | 1 |
| Comparison | True |
| Bitwise | 0 |
| Stringy | '' |
| Sets | Empty set or equivalent |
| Or-like Bool | False |
| And-like Bool | True |

For instance, union of an empty list will return an empty set:

```raku
say [∪];  # OUTPUT: «Set()␤»
```

This only applies to operators where empty or 0 is always a valid operand. For instance, applying it to division will yield an exception.

```raku
say [%] ();  # OUTPUT: «(exit code 1) No zero-arg meaning for infix:<%>␤»

```


## dist_zef-raku-community-modules-PostCocoon-Url.md
[![Actions Status](https://github.com/raku-community-modules/PostCocoon-Url/actions/workflows/linux.yml/badge.svg)](https://github.com/raku-community-modules/PostCocoon-Url/actions) [![Actions Status](https://github.com/raku-community-modules/PostCocoon-Url/actions/workflows/macos.yml/badge.svg)](https://github.com/raku-community-modules/PostCocoon-Url/actions) [![Actions Status](https://github.com/raku-community-modules/PostCocoon-Url/actions/workflows/windows.yml/badge.svg)](https://github.com/raku-community-modules/PostCocoon-Url/actions)

# NAME

PostCocoon::Url - Some simple but useful URL utils

# SYNOPSIS

```
use PostCocoon::Url;

say url-encode("👌");           # %F0%9F%91%8C
say url-decode("%F0%9F%91%8C"); # 👌

```

# DESCRIPTION

A collection of functions that can be used for URL parsing, building and changing.

Also provides an loose URL tokenizer

### sub url-encode

```
sub url-encode(
    Str:D $data
) returns Str:D

```

Transforms a string into a percent encoded string

### sub url-decode

```
sub url-decode(
    Str:D $data
) returns Str:D

```

Transforms a percent encoded string into a plain string

### multi sub build-query-string

```
multi sub build-query-string(
    Hash:D $hash
) returns Str:D

```

Build a query string from a Hash

### multi sub build-query-string

```
multi sub build-query-string(
    *%hash
) returns Str:D

```

Build a query string from the named arguments

### sub parse-query-string

```
sub parse-query-string(
    Str:D $query-string
) returns Hash

```

Parse a query string

## class PostCocoon::Url::URL-Parser

Loose URL parser that doesn't follow RFC3986 not completely

### sub is-valid-url

```
sub is-valid-url(
    Str $uri
) returns Bool

```

Check if something is a valid URL according to the parser

### sub parse-url

```
sub parse-url(
    Str $uri
) returns Hash

```

Return a hash with all items of the URL

### multi sub build-url

```
multi sub build-url(
    Hash:D $hash
) returns Str:D

```

Build a URL from a given hash, this function does no error checking at all, it may result in an invalid URL

### multi sub build-url

```
multi sub build-url(
    *%hash
) returns Str

```

Build an url from given named parameters, this function does no error checking at all, it may result in an invalid url

# AUTHOR

eater

# COPYRIGHT AND LICENSE

Copyright 2017 eater

Copyright 2024 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-dwarring-PDF-Tags.md
[[Raku PDF Project]](https://pdf-raku.github.io)
/ [PDF::Tags](https://pdf-raku.github.io/PDF-Tags-raku)

# PDF-Tags-raku

A small DOM-like API for the creation of tagged PDF files for accessibility purposes.

This module enables PDF tagged content manipulation, construction,
XPath queries and basic XML serialization.

See also [PDF::Tags::Reader](https://pdf-raku.github.io/PDF-Tags-Reader-raku), which is designed to read
content from existing tagged PDF files.

## Synopsis

```
use PDF::Tags;
use PDF::Tags::Elem;

use PDF::API6;
use PDF::Page;
use PDF::XObject::Image;

my PDF::API6 $pdf .= new;
my PDF::Tags $tags .= create: :$pdf;
# create the document root
my PDF::Tags::Elem $doc = $tags.Document: :Lang<en-NZ>;

my PDF::Page $page = $pdf.add-page;
my $header-font = $page.core-font: :family<Helvetica>, :weight<bold>;
my $body-font = $page.core-font: :family<Helvetica>;

$page.graphics: -> $gfx {

    $doc.Header1: $gfx, {
        .say('Marked Level 1 Header',
             :font($header-font),
             :font-size(15),
             :position[50, 120]);
    };

    $doc.Paragraph: $gfx, {
        .say('Marked paragraph text', :position[50, 100], :font($body-font), :font-size(12));
    };

    # add a marked image
    my PDF::XObject::Image $img .= open: "t/images/lightbulb.gif";
    $doc.Figure: $gfx, $img, :Alt('Incandescent apparatus');

}

$pdf.save-as: "/tmp/synopsis.pdf"

```

## Description

A tagged PDF contains additional markup information describing the logical
document structure of PDF documents.

PDF tagging may assist PDF readers and other automated tools in reading PDF
documents and locating content such as text and images.

This module provides a DOM like interface for creating and traversing PDF structure and
content via tags. It also has an XPath like search capability. It is designed for use in
conjunction with PDF::Class or PDF::API6.

## Standard Tags

Elements may be constructed using their `Tag` name or `Mnemonic`, as listed below. For example:

```
$root.P: $gfx, { .say('Marked paragraph text') };

```

Can also be written as:

```
$root.Paragraph: $gfx, { .say('Marked paragraph text') };

```

Or as:

```
$root.add-kid(:name<P>).mark: $gfx, { .say('Marked paragraph text') };

```

### "Grouping" elements:

| Tag | Mnemonic | Description |
| --- | --- | --- |
| Document |  | Whole document; must be used if there are multiple parts or articles |
| Part |  | Large division of a document; may group smaller units of content together, such as Division, Article, or Section elements. |
| Art | Article | Self-contained body of text considered to be a single narrative. |
| Sect | Section | General container element type that is usually a component of a Part or Article element |
| Div | Division | Generic block element or group of element |
| BlockQuote |  | A large portion of text referencing content from another source |
| Caption |  | Description of a Figure or Table |
| TOC | TableOfContents | May be nested, and may be used for lists of figures, tables, etc. |
| TOCI | TableOfContentsItem | Table of contents (leaf) item |
| Index |  | An index of keywords and topics, usually at the end of the document (text with accompanying Reference content) |
| NonStruct | NonStructural | non-structural grouping element (element itself not intended to be exported to other formats like HTML, but 'transparent' to its content which is processed normally) |
| Private |  | Content only meaningful to the creator (element and its content not intended to be exported to other formats like HTML) |
| DocumentFragment |  | A partial document fragment (PDF 2.0) |
| Aside |  | Distinct side content (PDF 2.0) |
| Sub | Subdivision | A subdivision (PDF 2.0) |
| Title |  | Encloses a title of a document or section (PDF 2.0) |
| FENote |  | Used to markup end notes and footnotes (PDF 2.0) |

### "Block" elements:

Mnemonic | Tag | Description

| Tag | Mnemonic | Description |
| --- | --- | --- |
| H | Heading | Nested section heading (not recommended) |
| H1 - H6 | Heading1 - Heading6 | The title or heading of a section within the text content |
| P | Paragraph | A distinct section of a piece of writing, usually dealing with a single theme |
| L | LIST | A group of similar items that are related to each other. Should include optional Caption, and list items |
| LI | ListItem | A Single list element. Should contain Lbl and/or LBody |
| Lbl | Label | Bullet, number, or "dictionary headword" |
| LBody | ListBody | Description of the item; may have nested lists or other blocks |

### "Table" elements:

| Tag | Mnemonic | Description |
| --- | --- | --- |
| Table |  | Content arranged into rows and columns; should either contain TR, or THead, TBody and/or TFoot |
| TR | TableRow | A single row of cell elements within a table |
| TH | TableHeader | Description of column contents |
| TD | TableData | A cell element |
| THead | TableHead | A row of table headers |
| TBody | TableBody | Table body; may have more than one per table |
| TFoot | TableFoot | Table footer row group |

### "Inline" elements:

| Tag | Mnemonic | Description |
| --- | --- | --- |
| Span |  | Generic inline content. |
| Quote |  | Inline text referencing content from another source |
| Note |  | End-note or footnote; may have a Lbl (see "block" elements) |
| Reference |  | Content in a document that refers to other content (e.g. page number in an index) |
| BibEntry | BibliographyEntry | Text referring the user to source of cited text. May have a Lbl (see "block" elements) |
| Code | CODE | Computer code |
| Link |  | hyperlink; should contain a link annotation |
| Annot | Annotation | annotation (other than a link) |
| Ruby |  | Chinese/Japanese pronunciation/explanation |
| RB | RubyBaseText | Ruby base text |
| RT | RubyText | Ruby annotation text |
| RP | RubyPunctuation |  |
| Warichu |  | Japanese/Chinese longer description |
| WT | WarichuText |  |
| WP | WarichuPunctuation |  |
| Emphasis | Em | (PDF 2.0) |
| Strong |  | (PDF 2.0) |

### "Illustration" elements (should have Alt and/or ActualText set):

| Tag | Mnemonic | Description |
| --- | --- | --- |
| Figure |  | An image or graphic that is referenced by the text |
| Formula |  | A scientific or mathematical formula element |
| Form |  | An editable PDF field used to complete a form |

### Non-structure tags:

| Tag | Mnemonic | Description |
| --- | --- | --- |
| Artifact |  | Used to mark all content not part of the logical structure |
| ReversedChars |  | Every string of text has characters in reverse order for technical reasons (due to how fonts work for right-to-left languages); strings may have spaces at the beginning or end to separate words, but may not have spaces in the middle |

## Classes in this Distribution

* [PDF::Tags](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags) - Tagged PDF root node
* [PDF::Tags::Attr](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/Attr) - A single node attribute
* [PDF::Tags::Elem](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/Elem) - Structure Tree descendant node
* [PDF::Tags::Node](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/Node) - Abstract node
* [PDF::Tags::Node::Parent](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/Node/Parent) - Abstract parent node
* [PDF::Tags::Mark](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/Mark) - Leaf content marker node
* [PDF::Tags::Text](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/Text) - Text content node
* [PDF::Tags::ObjRef](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/ObjRef) - A reference to a PDF object (PDF::Annot, PDF::Field or PDF::XObject)
* [PDF::Tags::XML-Writer](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/XML-Writer) - XML Serializer
* [PDF::Tags::XPath](https://pdf-raku.github.io/PDF-Tags-raku/PDF/Tags/XPath) - XPath evaluation context

## Advanced Topics

### Form and Image XObjects

In the simple case, both [PDF::XObject::Form](https://pdf-raku.github.io/PDF-Class-raku/PDF/XObject/Form)'s and [PDF::XObject::Image](https://pdf-raku.github.io/PDF-Class-raku/PDF/XObject/Images)'s are inserted and externally
tagged as an atomic graphical element, typically tagged as `Figure` or `Form`:

```
my PDF::XObject::Image $img .= open: "t/images/lightbulb.gif";

my $figure = $doc.Figure: $gfx, $img, :position[50, 70], :Alt("A light-bulb");

```

A [PDF::XObject::Form](https://pdf-raku.github.io/PDF-Class-raku/PDF/XObject/Form) may be associated with a document fragment. The
form can then be rendered, and the fragment inserted into the document, by repeatedly calling `do` on the fragment, as demonstrated below:

```
use PDF::Tags;
use PDF::Tags::Elem;
use PDF::Class;
use PDF::XObject::Form;
my PDF::Class $pdf .= new;
my PDF::Tags $tags .= create: :$pdf;
my PDF::Tags::Elem $doc = $tags.Document;

my PDF::Page $page = $pdf.add-page;
$page.graphics: -> $gfx {
   $doc.Header1: $gfx, {
        .say('Header text');
   }

    my PDF::XObject::Form $form = $page.xobject-form: :BBox[0, 0, 200, 50];
    my PDF::Tags::Elem $form-frag = $doc.fragment;

    $form.text: {
        my $font-size = 12;
        .text-position = [10, 38];
        $form-frag.Header2: $_, {
            .say: "Tagged XObject header";
        };
        my $p = $form-frag.Paragraph: $_, {
            .say: "Some sample tagged text";
        };
    }

    # multiple rendering of the form, and insertion into the structure tree
    $doc.do($gfx, $form-frag, :position[150, 70]);
    $doc.do($gfx, $form-frag, :position[150, 20]);
}

```

### Links

Links are usually contained in a block element, such as a `Paragraph`. If
the link is internal, it should be further enclosed in a `Reference` element.

Furthermore, if the link is in flowing text, such as a paragraph, the
`mark` method may be needed to mark preceding text, the link, and
following text.

Please see [examples/link.raku](https://github.com/pdf-raku/PDF-Tags-raku/blob/master/examples/link.raku) which demonstrates adding an
tagged internal link to a PDF.

### Graphics Content Tags

As a rule, all content doesn't have to form part of the structure tree, but should be tagged to meet accessibility guidelines.

This sometimes requires tagging of incidental graphics. `PDF::Content` has a `tag()` method for this. The content is tagged, but does not appear in the structure tree.

Some of the commonly used content tags are:

#### Artifact

Artifact content forms part of the visual display, but does form part of the accessibility content.

Artifacts may either form part of the structure tree, or be tagged at the graphical level.

For example:

```
# Artifact in marked content and in the structure tree
$elem.Artifact, $gfx, {
    .say("Page $page-num", :$font, :position[ 250, 20 ]);
}

```

or

```
# Artifact in content stream only
$gfx.tag: Artifact, {
    .say("Page $page-num", :$font, :position[ 250, 20 ]);
}

```

#### Clipped

A clipped region encompasses additional graphics that are being
used as part of a clipping operation. The clipped area may include graphics that are part of the structure tree. For example:

```
use PDF::Class;
use PDF::Tags;
use PDF::Tags::Elem;
use PDF::Content::Tag :ContentTags, :ParagraphTags;

my PDF::Class $pdf .= new;
my PDF::Tags $tags .= create: :$pdf;
# create the document root
my PDF::Tags::Elem $doc = $tags.Document;

$pdf.add-page.graphics: {
    .tag: Clipped, {
        .Rectangle: 100, 100, 125, 20;
        .Clip;
        .EndPath;
        $doc.Paragraph: $_, {
            .say: 'Clip me', :position[98, 98];
        }
    }
}

```

The above example is setting up a clipping sequence. The clipped
text is being inserted as a paragraph in the structure tree.

#### Span

This tag may be used either in the structure tree, or at the content level to defined attributes of a graphics sequence. Its usage is similar to the XHTML `span` tag.

```
$gfx.tag: Span: :Lang<es-MX>, {
    .say('Hasta la vista', :position[50, 80]);
}

```

### Role Maps

The PDF standard allows user defined tags, which are mapped to
standard tags via a role-map table. `PDF::Tags` supports this
feature, via the `create` `:role-map` option. One declared,
role-map entries, can be called as standard construction
methods:

```
use PDF::Tags;
use PDF::Tags::Elem;
use PDF::Class;
use PDF::Page;

enum Roles ( :Book<Document>, :FootNote<Note> );
constant %role-map = Roles.enums.Hash;

my PDF::Class $pdf .= new;
my PDF::Tags $tags .= create: :$pdf, :%role-map;

my PDF::Tags::Elem $doc = $tags.Book;
my PDF::Page $page = $pdf.add-page;

$page.graphics: -> $gfx {

    $doc.Paragraph: $gfx, {
        .say: 'Some body text¹', :position[50, 150];
    };

    $doc.FootNote: $gfx, {
        .say: '¹With a foot-note', :position[50, 20];
    };

}

```

### Content Continuation

Content sometimes needs to be continued across graphics elements, such as a paragraph that
spans multiple pages. The `mark` method may be called repeatably to achieve this:

```
use PDF::Class;
use PDF::Tags;
use PDF::Tags::Elem;
use PDF::Page;
use PDF::Content::FontObj;

my PDF::Class $pdf .= new;
my PDF::Tags $tags .= create: :$pdf;
my PDF::Tags::Elem $doc = $tags.Document;
my PDF::Page $page = $pdf.add-page;
my PDF::Content::FontObj $font = $pdf.core-font: :family<Helvetica>;
my PDF::Tags::Elem $para = $doc.Paragraph;

$page.graphics: -> $gfx {

    $para.mark: $gfx, {
        .say('This paragraph starts on first page...',
             :$font,
             :font-size(15),
             :position[50, 600]);
    };

}

$page = $pdf.add-page;
$page.graphics: -> $gfx {

    $para.mark: $gfx, {
        .say('...and finishes on the second page',
             :$font,
             :font-size(15),
             :position[50, 600]);
    };

}

$pdf.save-as: "span.pdf";

```

### Tagging and Metadata

If a PDF document is tagged for accessibility, additional metadata usually also needs to be set-up; typically `Title`, `Author`, `Subject`, `Keywords` and language. For example:

```
use PDF::API6;
use PDF::Info;
my PDF::API6 $pdf .= open: "/tmp/synopsis.pdf";

my PDF::Info $info = $pdf.Info //= {};
$info.Title = 'PDF::Tags README Synopsis';
$info.Subject = 'Sample Output PDF';
$info.Author = 'David Warring';
$info.Keywords = 'accessibility,pdf,tags';
$pdf.catalog.Lang = 'en';
$pdf.update;

```

Note that `PDF::API6` automatically fills in `Producer`, `Creator` and `CreationDate`.

### Verification

The `pdf-tag-dump.raku` script from the [PDF::Tags::Reader](https://pdf-raku.github.io/PDF-Tags-Reader-raku) module
can be used to view the logical content of PDF files as XML, for example:

```
$ pdf-tag-dump.raku /tmp/synopsis.pdf

```

Produces

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Document SYSTEM "http://pdf-raku.github.io/dtd/tagged-pdf.dtd">
<?xml-stylesheet type="text/css" href="https://pdf-raku.github.io/css/tagged-pdf.css"?>
<Document>
  <H1>
    Marked Level 1 Header
  </H1>
  <P>
    Marked paragraph text
  </P>
  <Figure BBox="0 0 19 19">
  </Figure>
</Document>

```

The XML output from `pdf-tag-dump.raku` includes an [external DtD](http://pdf-raku.github.io/dtd/tagged-pdf.dtd) for basic validation purposes.

For example, it can be piped to `xmllint`, from the `libxml2` package, to check the structure of the tags:

$ pdf-tag-dump.raku /tmp/synopsis.pdf | xmllint --noout --valid -

## See Also

* [PDF::Tags::Reader](https://pdf-raku.github.io/PDF-Tags-Reader-raku) - for reading PDF files with existing tagged content

## Further Work

* Type-casting of PDF::StructElem.A to roles; as per 14.8.5. Possibly belongs in PDF::Class, however slightly complicated by the need to apply role-mapping.
* Develop a tag/accessibility checker. A low-level sanity checker that a tagged PDF meets PDF association recommendations `pdf-tag-checker.raku --ua`. See <https://www.pdfa.org/wp-content/uploads/2014/06/MatterhornProtocol_1-02.pdf> and Wikipedia Clause 7 guidelines:

  * Complete tagging of "real content" in logical reading order
  * Tags must correctly represent the document's semantic structures (headings, lists, tables, etc.)
  * Problematic content is prohibited, including illogical headings, the use of color/contrast to convey information, inaccessible JavaScript, and more
  * Meaningful graphics must include alternative text descriptions
  * Security settings must allow assistive technology access to the content
  * Fonts must be embedded, and text mapped to Unicode

A personal copy of the PDF accessibility standard [ISO 14289-1](https://pdfa.org/resource/iso-14289-pdfua/) is available from the [PDF Association Website](https://www.iso.org/).

* Editing. Currently the API doesn't readily support editing tags into existing content. More work is also
  needed in the PDF::Content module to support content editing.


## dist_zef-coke-App-Uni.md
# NAME

uni - command-line utility to find or display Unicode characters

# DESCRIPTION

```
$ uni ¶
¶ - U+0000B6 - PILCROW SIGN [Po]

```

`uni` will output information from the Unicode DB in Raku; The hex code, the character itself, the characters name, and the properties of the character(s) are output.

This verison of uni is *heavily* inspired by the Perl 5 module of the same name. H/T to RJBS.

Since it's in Raku - you get the latest Unicode DB in the compiler (15 in the upcoming release)
and regexes are Raku-style.

# MODES

## Default

If you pass a single character to `uni`, then details of that character are printed; Otherwise the codepoint names are searched.

## -s (Single Character)

A single character is processed.

```
$ uni -s •
• - U+002022 - BULLET [Po]

```

## -v (Verbose, Single Character)

Identical to the `-s` variant, except that additional information about the codepoint is also displayed.

```
$ uni -v 🚮
🚮 - U+01F6AE - PUT LITTER IN ITS PLACE SYMBOL [So]
    Properties:       Symbol, other
    Unicode Script:   Common
    Unicode Block:    Transport and Map Symbols
    Added in Unicode: 6.0
    White Space:      False
    Width:            W

```

## -n (Name Search)

The text following -n is used to search (case insensitively) through all the codepoints. Parameters that start and end with `/` are considered regular expressions.

```
$ uni -n modeﬆy # note the ﬆ ligature
䷎ - U+004DCE - HEXAGRAM FOR MODESTY [So]

$ uni -n stroke dotl modifier
ᶡ - U+001DA1 - MODIFIER LETTER SMALL DOTLESS J WITH STROKE [Lm]

$ uni -n /"rev".*"pilcr"/ # note, has to be one shell arg
⁋ - U+00204B - REVERSED PILCROW SIGN [Po]

```

## -w (Word Search)

Same as -n, except each parameter must match an entire word.

```
$ uni -w cat eyes
😸 - U+001F638 - GRINNING CAT FACE WITH SMILING EYES [So]
😻 - U+001F63B - SMILING CAT FACE WITH HEART-SHAPED EYES [So]
😽 - U+001F63D - KISSING CAT FACE WITH CLOSED EYES [So]

```

## -c (Multiple Characters)

Output multiple characters' information at once:

```
$ uni -c £¢…
£ - U+0000A3 - POUND SIGN [Sc]
¢ - U+0000A2 - CENT SIGN [Sc]
… - U+002026 - HORIZONTAL ELLIPSIS [Po]

```

## -u (Codepoint)

Search by hex codepoint:

```
$ uni -u 221E 00A7
∞ - U+00221E - INFINITY [Sm]
§ - U+0000A7 - SECTION SIGN [Po]

```

## -b (Bunny)

Given a character, generate a bunny holding the character:

```
# uni -b 221E

```

TODO

# ACKNOWLEDGEMENTS

This is a re-implementation of the Perl 5 module of the same name, by RJBS: Check out his module for the continued history.


## dist_zef-vrurg-WWW-GCloud-API-Storage.md
# NAME

`WWW::GCloud::API::Storage` - `WWW::GCloud` implementation of [Google Storage API](https://cloud.google.com/storage/docs/json_api)

# SYNOPSIS

```
use v6.e.PREVIEW;
use WWW::GCloud;
use WWW::GCloud::API::Storage;
use WWW::GCloud::R::Storage::Object;

my $gcloud = WWW::GCloud.new;
my $st = $gcloud.storage;

await $st.objects.get("bucket-name", "object-name.ext", :media)
        .andthen({ .result.send-to("output-file.ext", :!override) });

```

# DESCRIPTION

This module lacks complete documentation due to me not currently able to write it. Please, see some notes for [`WWW::GCloud`](https://raku.land/zef:vrurg/WWW::GCloud) framework. And look into *exmaples/* where I tried to provide meaningful code to follow.

## Status

This module is pre-beta, pre-anything. It is incomplete and likely not well thought out at places. But it already lets you do a lot with your storages.

If there is anything you need but it is missing then, please, consider implementing it and submitting a PR. Any other approach would barely proces any outcome for what I do apologize!

Either way, this module can be used as a reference implementation for a `WWW::GGCloud` API.

Do not hesitate to get in touch with me would you need any help. I know it could be annoying when a complex module has little to none docs. I'll do my best to fix the situation. But until then feel free to open an issue in the [GitHub repository](https://github.com/vrurg/raku-WWW-GCloud-API-Storage/issues), even if it's just a question.

## Uploading

Contrary to a typical convention about API resource methods returning either a [`Promise`](https://docs.raku.org/type/Promise) or a [`Supply`](https://docs.raku.org/type/Supply), when an upload is requested with `insert` method of `objects` resource an uploader object is given back to the user. The object would be implementing `WWW::GCloud::API::Storage::Upload` role.

There are two kinds of uploads are currently implemented: simple and resumable. The former is preferable for smaller files, the latter is better be used for huge ones. Where is the edge between 'small' and 'large' is determined by the bandwidth and quality of one's connection.

Either implementation of the uploader tries to optimize memory usage by reading data in chunks and submitting each chunk to the network immediately. But using `:!segemnted` flag to create the uploader object turns this behavior off for the simple uploads.

The uploader can feed data directly from a handle without knowing what lays behind the handle. The only requirement is imposed by resumable upload as it has to be able to seek within the stream in case it needs to resend a chunk.

The upload process can be monitored by subscribiting to a [`Supply`](https://docs.raku.org/type/Supply) provided by uploader's `progress` method which emits upload events like "buffer read", "retry requested", "done".

Since the actual REST calls are done by the uploader its `upload` method is the one which complies to the convention of API resource methods returning [`Promise`](https://docs.raku.org/type/Promise).

See *exmaples/bucket-upload.raku* for a reference implementation.

# COPYRIGHT

(c) 2023, Vadim Belman [vrurg@cpan.org](mailto:vrurg@cpan.org)

# LICENSE

Artistic License 2.0

See the [*LICENSE*](LICENSE) file in this distribution.


## alreadystarted.md
class X::Proc::Async::AlreadyStarted

Error due to calling start on an already started Proc::Async object

```raku
class X::Proc::Async::AlreadyStarted is Exception {}
```

When you call `start` twice on the same [`Proc::Async`](/type/Proc/Async) object, the second invocation will die with an `X::Proc::Async::AlreadyStarted` exception.

```raku
my $proc = Proc::Async.new("echo");
$proc.start;
$proc.start;
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Proc::Async::AlreadyStarted: Process has already been started␤»
```


## dist_zef-tony-o-Digest-FNV.md
# Digest::FNV

Fowler–Noll–Vo hash function in pure perl6.

## Exports

### `fnv0`

If you want to use this, you must import with the `:DEPRECATED` flag.

### `fnv1`

Performs the FNV1 hash.

### `fnv1a`

The alternate FNV1 hash (XOR, then multiply)

## Signatures

All of the exports have the signature of `($data, :bits(32|64|128|256|512|1024))`

The tests only use 32|64, use the others at your own peril.

## Usage

```
use Digest::FNV;

my $x = fnv1a('some str');
# $x = 651763969055412538

```