On Nov 25, 2022, at 9:21 PM, ToddAndMargo via perl6-users
<perl6-users@perl.org> wrote:
Hi All,
I am confused!
The documentation at https://github.com/salortiz/NativeHelpers-Blob would
certainly benefit from example code!
No examples in the t/ directory use the `blob-from-pointer` sub.
The main doc for NativeCall,
https://docs.raku.org/language/nativecall#Buffers_and_blobs
, *does* contain a single example, but it uses a too-clever-to-be-helpful
shortcut for a named argument, so I will rephrase it as:
my $esponja = blob-from-pointer( $inter, elems => 2, type => Blob[int8] );
or:
my $esponja = blob-from-pointer( $inter, :elems(2), :type(Blob[int8]) );
sub blob-from-pointer(Pointer:D \ptr, Int :$elems!, Blob:U :$type = Buf) is
export {
What is `Pointer:D \ptr`?
Why the `\`?
Defining a variable with a backslash-where-the-sigil-should-go creates a "sigilless
variable":
https://docs.raku.org/language/variables#Sigilless_variables
The original coder's choice to use this should not be relevant to the caller,
and the distinction is not mentioned in the docs at
https://github.com/salortiz/NativeHelpers-Blob#sub-blob-from-pointerpointerd-int-elems-blobu-type--buf
,
which document the sub as:
sub blob-from-pointer(Pointer:D, Int :$elems!, Blob:U :$type = Buf)
You can ignore the confusing backslash; just be sure to pass an defined object
of type Pointer (or a sub-class of Pointer).
What is `:$elems!`?
Why the `:`?
Why the `!`?
The colon is the standard way to define a *named* parameter.
https://docs.raku.org/type/Signature#Positional_vs._named_arguments
Named params default to being optional, and the exclamation point changes the
parameter to be required.
This is an unusual choice for the API (since it could have been specified as 3 positional
parameters), but this API forces more "clues to the reader" to be embedded in
each call, providing more clarity in a problem domain prone to pitfalls.
What is `Blob:U :$type = Buf`
What does `Blob:U` mean?
:D means "Must be defined"
:U means "Must be undefined"
:_ means "can be defined or undefined" and is the default.
SomeObjectType:U means that the parameter must be undefined, and be of the type
SomeObjectType, or a *subclass* of SomeObjectType.
That part of the API looks *very* weird (Why pass a undefined value???), until
we observe that Blob and Buf have *sized* subclasses via parameterized role!
What does `:type` mean?
You are missing the `$` in that question.
`:$type` means that the caller can pass this datum in a named argument style, like
`type => SomeTypename` or `:type(SomeTypename)`,
and the called sub will receive the argument in the `$type` variable.
In other words, it is a *named* parameter like the mandatory `:$elems` above,
but `:$type` is optional.
Is `$type` being assigned the type of `Buf`
The equals-sign in a Parameter list defines a default value. `$type` gets
assigned the undefined-but-still-useful type-object of `Buf` only if no `type`
argument is passed.
So, a real-life call might look like:
my $q = blob-from-pointer( $p, elems => 10, type => Blob[uint8] );
:'(
Yours in confusion,
-T
