What does this line mean?

[ToddAndMargo via perl6-users]

Hi All,


I am confused!


sub blob-from-pointer(Pointer:D \ptr, Int :$elems!, Blob:U :$type = Buf)
is export {

What is `Pointer:D \ptr`?

Why the `\`?


What is `:$elems!`?

Why the `:`?

Why the `!`?


What is `Blob:U :$type = Buf`

What does `Blob:U` mean?

What does `:type` mean?

Is `$type` being assigned the type of `Buf`


:'(


Yours in confusion,
-T

[ToddAndMargo via perl6-users]

On 11/25/22 21:06, Bruce Gray wrote:

>
>> On Nov 25, 2022, at 9:21 PM, ToddAndMargo via perl6-users <perl6...@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
>

Hi Bruce,

Thank you for the help.

I was looking for an explanation of each of
the question I specifically asked.

-T

[ToddAndMargo via perl6-users]

Hi All,

I figured all this out with some help from the
beginners chat line and a ton of research.

If anyone want to know the results, let me
know and I will fill in the answers.

-T