Net::DB...Iterator(3)

💅 Net::DBus::Test::MockIterator — the Net::DB...Iterator(3) page, but make it make sense 🎀

okay bestie, so this whole page is about Net::DBus::Test::MockIterator — an iterator over a mock message. yes it's a real module, yes it's in the Net::DBus::Test::MockMessage fam, and yes I'm gonna walk you through every single method. no skipping, no cap. ✨

---

🌸 NAME 🌸

Net::DBus::Test::MockIterator — Iterator over a mock message. that's it, that's the whole vibe. 💖

---

🦋 SYNOPSIS 🦋

🎀 Creating a new message

my $msg = new Net::DBus::Test::MockMessage
my $iterator = $msg->iterator;

$iterator->append_boolean(1);
$iterator->append_byte(123);

🎀 Reading from a message

my $msg = ...get it from somewhere...
my $iter = $msg->iterator();

my $i = 0;
while ($iter->has_next()) {
  $iter->next();
  $i++;
  if ($i == 1) {
     my $val = $iter->get_boolean();
  } elsif ($i == 2) {
     my $val = $iter->get_byte();
  }
}

see how that works? append stuff on one side, walk it back on the other. iconic behavior honestly. 🔥

---

⭐ DESCRIPTION ⭐

So this module is literally the "mock" counterpart to the Net::DBus::Binding::Iterator object, and it's capable of iterating over mock message objects. very demure, very mindful. 🧚

big important note: you do not create instances of this module directly. nope. you get them via the "iterator" method on the Net::DBus::Test::MockMessage module. periodt. 💅

---

👑 METHODS 👑

💜 $res = $iter->has_next()

Determines if there are any more fields in the message itertor to be read. Returns a positive value if there are more fields, zero otherwise. basically a little vibe check before you keep going. 🫶

💜 $success = $iter->next()

Skips the iterator onto the next field in the message. Returns a positive value if the current field pointer was successfully advanced, zero otherwise. hit it and quit it. ⭐

---

🌈 the read/write pairs — boolean, byte, string & friends 🌈

okay so these all come in little getter/setter duos, and honestly? obsessed with the symmetry. 💖

• my $val = $iter->get_boolean() / $iter->append_boolean($val); — Read or write a boolean value from/to the message iterator
• my $val = $iter->get_byte() / $iter->append_byte($val); — Read or write a single byte value from/to the message iterator.
• my $val = $iter->get_string() / $iter->append_string($val); — Read or write a UTF-8 string value from/to the message iterator
• my $val = $iter->get_object_path() / $iter->append_object_path($val); — Read or write a UTF-8 string value, whose contents is a valid object path, from/to the message iterator
• my $val = $iter->get_signature() / $iter->append_signature($val); — Read or write a UTF-8 string, whose contents is a valid type signature, value from/to the message iterator
• my $val = $iter->get_int16() / $iter->append_int16($val); — Read or write a signed 16 bit value from/to the message iterator
• my $val = $iter->get_uint16() / $iter->append_uint16($val); — Read or write an unsigned 16 bit value from/to the message iterator
• my $val = $iter->get_int32() / $iter->append_int32($val); — Read or write a signed 32 bit value from/to the message iterator
• my $val = $iter->get_uint32() / $iter->append_uint32($val); — Read or write an unsigned 32 bit value from/to the message iterator
• my $val = $iter->get_int64() / $iter->append_int64($val); — Read or write a signed 64 bit value from/to the message iterator. An error will be raised if this build of Perl does not support 64 bit integers 😭
• my $val = $iter->get_uint64() / $iter->append_uint64($val); — Read or write an unsigned 64 bit value from/to the message iterator. An error will be raised if this build of Perl does not support 64 bit integers 😭
• my $val = $iter->get_double() / $iter->append_double($val); — Read or write a double precision floating point value from/to the message iterator
• my $val = $iter->get_unix_fd() / $iter->append_unix_fd($val); — Read or write a unix_fd value from/to the message iterator

heads up bestie: those two 64-bit ones will raise an error if your Perl build doesn't support 64 bit integers. not a drill. 💀

---

💜 my $value = $iter->get() / my $value = $iter->get($type)

Get the current value pointed to by this iterator. If the optional $type parameter is supplied, the wire type will be compared with the desired type & a warning output if their differ. The $type value must be one of the "Net::DBus::Binding::Message::TYPE*" constants. ✨

💜 my $hashref = $iter->get_dict()

If the iterator currently points to a dictionary value, unmarshalls and returns the value as a hash reference.

💜 my $hashref = $iter->get_array()

If the iterator currently points to an array value, unmarshalls and returns the value as a array reference.

💜 my $hashref = $iter->get_variant()

If the iterator currently points to a variant value, unmarshalls and returns the value contained in the variant.

💜 my $hashref = $iter->get_struct()

If the iterator currently points to an struct value, unmarshalls and returns the value as a array reference. The values in the array correspond to members of the struct.

---

💜 $iter->append($value) / $iter->append($value, $type)

Appends a value to the message associated with this iterator. The value is marshalled into wire format, according to the following rules 🎀

1. If the $value is an instance of Net::DBus::Binding::Value, the embedded data type is used.
2. If the $type parameter is supplied, that is taken to represent the data type. The type must be one of the "Net::DBus::Binding::Message::TYPE_*" constants.
3. Otherwise, the data type is chosen to be a string, dict or array according to the perl data types SCALAR, HASH or ARRAY.

three rules, no ambiguity, slay. 💅

💜 my $type = $iter->guess_type($value)

Make a best guess at the on the wire data type to use for marshalling $value. If the value is a hash reference, the dictionary type is returned; if the value is an array reference the array type is returned; otherwise the string type is returned. she's guessing but she's right. 🌸

💜 my $sig = $iter->format_signature($type)

Given a data type representation, construct a corresponding signature string

💜 $iter->append_array($value, $type)

Append an array of values to the message. The $value parameter must be an array reference, whose elements all have the same data type specified by the $type parameter. matching types or it's not happening bestie. 🦋

💜 $iter->append_struct($value, $type)

Append a struct to the message. The $value parameter must be an array reference, whose elements correspond to members of the structure. The $type parameter encodes the type of each member of the struct.

💜 $iter->append_dict($value, $type)

Append a dictionary to the message. The $value parameter must be an hash reference. The $type parameter encodes the type of the key and value of the hash.

💜 $iter->append_variant($value)

Append a value to the message, encoded as a variant type. The $value can be of any type, however, the variant will be encoded as either a string, dictionary or array according to the rules of the "guess_type" method. main character energy, flexible but predictable. 👑

💜 my $type = $iter->get_arg_type

Retrieves the type code of the value pointing to by this iterator. The returned code will correspond to one of the constants "Net::DBus::Binding::Message::TYPE_*" 🌈

💜 my $type = $iter->get_element_type

If the iterator points to an array, retrieves the type code of array elements. The returned code will correspond to one of the constants "Net::DBus::Binding::Message::TYPE_*" 🌈

---

🙈 BUGS 🙈

It doesn't completely replicate the API of Net::DBus::Binding::Iterator, merely enough to make the high level bindings work in a test scenario. so like… it's a mock. adjust expectations accordingly. 💀

---

🎀 AUTHOR 🎀

Daniel P. Berrange

---

💖 COPYRIGHT 💖

Copyright (C) 2005-2009 Daniel P. Berrange

---

🧚 SEE ALSO 🧚

Net::DBus::Test::MockMessage, Net::DBus::Binding::Iterator, <http://www.mockobjects.com/Faq.html>

---

okay that's the whole page, you ate that bestie 💅✨ — brought to you by perl v5.42.0 and dated 2019-12-17, so go forth and mock those iterators 🦋🎀