file format extensions

[Richard Hainsworth]

I'm revising how I name files that are included in my modules. With the 
name change to Raku, the file extensions also changed for script and 
module files.


In addition Jonathan has defined some format extensions for Cro files, 
and I am sure there would be other developers who would like to claim 
unique extension names for files.


This is not a post intended to start a war about file extensions, that 
is whether they should exist in a modern file system. For whatever 
reason they came into being, a significant number of users, such as 
myself, find them useful, if only as a mnemonic for their files' 
probable contents.


It seems to me a short page in the docs.raku.org would be useful with 
the various file extensions, and so if a developer wanted for a custom 
file extension to be primarily applied to some new module, the way to do 
would be to create a PR on the documentation file.


If this post gets some positive responses, then I'll write the POD6 file 
for inclusion in docs.raku.org and create a PR for inclusion.


[Another naming question would be the name of the markup language - as 
distinct from the file extension - for documentation. For Perl it is 
POD, for Perl6 it was natural to use POD6. POD stands for Plain Old 
Documentation, but I think that POD6 is neither Plain, nor Old. How 
about RDM for Raku documentation markup? ]


There is a wrinkle in that Raku best practice has evolved in line with 
the evolution of perl6 into Raku. So it seems reasonable to have 
previous file formats listed as well.


The following are what I think are the current best practices. Since I 
have been out of circulation for a while, the list is likely not 
exhaustive and may be wrong. I am certain there are other file types I 
have not included.


For each file type, extensions on the left are earlier, and the 
extension of the far right (after the TAB) is considered best practice


Perl6 / Raku script: .pl, .pl6,  .raku

Perl6 / Raku Module: .pm, .pm6,  .rakumod

Perl6 / Raku Standalone Documentation (POD6 can be included in a script 
or module file): .pm, .pm6, .pod, .pod6,  .rakudoc


NQP file:  .nqp

Cro template:  .crotmp

Re: file format extensions

[Elizabeth Mattijsen]

+1 from me.  Shouldn't that be a .rakudoc file ?  :-)

> On 30 Dec 2021, at 12:20, Richard Hainsworth  wrote:
> 
> I'm revising how I name files that are included in my modules. With the name 
> change to Raku, the file extensions also changed for script and module files.
> 
> In addition Jonathan has defined some format extensions for Cro files, and I 
> am sure there would be other developers who would like to claim unique 
> extension names for files.
> 
> This is not a post intended to start a war about file extensions, that is 
> whether they should exist in a modern file system. For whatever reason they 
> came into being, a significant number of users, such as myself, find them 
> useful, if only as a mnemonic for their files' probable contents.
> 
> It seems to me a short page in the docs.raku.org would be useful with the 
> various file extensions, and so if a developer wanted for a custom file 
> extension to be primarily applied to some new module, the way to do would be 
> to create a PR on the documentation file.
> 
> If this post gets some positive responses, then I'll write the POD6 file for 
> inclusion in docs.raku.org and create a PR for inclusion.
> 
> [Another naming question would be the name of the markup language - as 
> distinct from the file extension - for documentation. For Perl it is POD, for 
> Perl6 it was natural to use POD6. POD stands for Plain Old Documentation, but 
> I think that POD6 is neither Plain, nor Old. How about RDM for Raku 
> documentation markup? ]
> 
> There is a wrinkle in that Raku best practice has evolved in line with the 
> evolution of perl6 into Raku. So it seems reasonable to have previous file 
> formats listed as well.
> 
> The following are what I think are the current best practices. Since I have 
> been out of circulation for a while, the list is likely not exhaustive and 
> may be wrong. I am certain there are other file types I have not included.
> 
> For each file type, extensions on the left are earlier, and the extension of 
> the far right (after the TAB) is considered best practice
> 
> Perl6 / Raku script: .pl, .pl6,  .raku
> 
> Perl6 / Raku Module: .pm, .pm6,  .rakumod
> 
> Perl6 / Raku Standalone Documentation (POD6 can be included in a script or 
> module file): .pm, .pm6, .pod, .pod6,  .rakudoc
> 
> NQP file:  .nqp
> 
> Cro template:  .crotmp
> 
> 
> 
> 
> 
> 

Implementation of documented POD6 behaviour

[Richard Hainsworth]

I plan to use the POD6 metadata functionality a lot in a new module. It 
would be far better to separate out the meta data into lines.


In https://docs.raku.org/language/pod I find

"In the future, the configuration section may be extended over 
subsequent lines by starting those lines with an |=| in the first 
(virtual) column followed by a whitespace character."


with a footnote that it is not implemented.

Is there some indication when it will be implemented?

I am willing to look at the the Rakudo code and create a PR to implement 
this functionality. Is there any reason not to do this, eg., planned 
changes such as changing to RakuAST.


Similar to the above, there are implied POD6 behaviours that do not 
work, in particular embedded POD6.


Two examples:

- Pod6 tables. A cell of a POD6 table may not contain a POD6 table. Thus 
a table of tables is not possible.


Note that there is a test in the Pod::To::HTML test suite that tests for 
this behaviour. It is TODO'd because it does not work, but it is 
expected it should work.


The current behaviour is to treat the embedded table as an unknown block 
type.


- Definition lists.

It is not possible to include embedded POD6 in the contents part of a 
definition.


More detail on these.

The following program:

=begin pod

=for head1 :attr('key') :battr
This is a working header

=for head1
= attr('key) :battr
This is what is being tested

=defn Bad boy
When you Bto include formating.

Outside a definition list Bis treated differently.

=end pod
say $=pod;

Produces the following output:

[Pod::Block::Named{:name("pod")}
  Pod::Heading{:config("\$\{:attr(\"key\"), :battr(\"key2\")}"), :level("1")}
Pod::Block::Para
  This is a working header
  Pod::Heading{:level("1")}
Pod::Block::Para
  = attr('key) :battr This is what is being tested
  Pod::Defn{:term("Bad boy")}
Pod::Block::Para
  When you B to include formating.
  Pod::Block::Para
Outside a definition list
Pod::FormattingCode{:type("B")}
  formating
 is treated differently.
]

From the above, it can be seen that
(1) the config part of the second header does not contain extra key/value pairs.
This is consistent with the footnote in the documentation.
(2) the contents part (which is shown by say as being indented from the 
Pod:Block line) of a Pod::Defn
is treated differently from the contents part of a Pod::Block::Para. This is 
not documented and is unexpected.

I have not shown the POD6 table behaviour, but its similar to the Pod::Defn 
behaviour.

Re: file format extensions

[Vadim Belman]

I also agree that a page on docs would be helpful. But my point for this reply 
is about renaming POD6. I don't think this makes much sense and barely would 
ever happen. It is a legacy name, like NQP. 

Best regards,
Vadim Belman

> On Dec 30, 2021, at 6:26 AM, Elizabeth Mattijsen  wrote:
> 
> +1 from me.  Shouldn't that be a .rakudoc file ?  :-)
> 
>> On 30 Dec 2021, at 12:20, Richard Hainsworth  wrote:
>> 
>> I'm revising how I name files that are included in my modules. With the name 
>> change to Raku, the file extensions also changed for script and module files.
>> 
>> In addition Jonathan has defined some format extensions for Cro files, and I 
>> am sure there would be other developers who would like to claim unique 
>> extension names for files.
>> 
>> This is not a post intended to start a war about file extensions, that is 
>> whether they should exist in a modern file system. For whatever reason they 
>> came into being, a significant number of users, such as myself, find them 
>> useful, if only as a mnemonic for their files' probable contents.
>> 
>> It seems to me a short page in the docs.raku.org would be useful with the 
>> various file extensions, and so if a developer wanted for a custom file 
>> extension to be primarily applied to some new module, the way to do would be 
>> to create a PR on the documentation file.
>> 
>> If this post gets some positive responses, then I'll write the POD6 file for 
>> inclusion in docs.raku.org and create a PR for inclusion.
>> 
>> [Another naming question would be the name of the markup language - as 
>> distinct from the file extension - for documentation. For Perl it is POD, 
>> for Perl6 it was natural to use POD6. POD stands for Plain Old 
>> Documentation, but I think that POD6 is neither Plain, nor Old. How about 
>> RDM for Raku documentation markup? ]
>> 
>> There is a wrinkle in that Raku best practice has evolved in line with the 
>> evolution of perl6 into Raku. So it seems reasonable to have previous file 
>> formats listed as well.
>> 
>> The following are what I think are the current best practices. Since I have 
>> been out of circulation for a while, the list is likely not exhaustive and 
>> may be wrong. I am certain there are other file types I have not included.
>> 
>> For each file type, extensions on the left are earlier, and the extension of 
>> the far right (after the TAB) is considered best practice
>> 
>> Perl6 / Raku script: .pl, .pl6,  .raku
>> 
>> Perl6 / Raku Module: .pm, .pm6,  .rakumod
>> 
>> Perl6 / Raku Standalone Documentation (POD6 can be included in a script or 
>> module file): .pm, .pm6, .pod, .pod6,  .rakudoc
>> 
>> NQP file:  .nqp
>> 
>> Cro template:  .crotmp
>> 
>> 
>> 
>> 
>> 
>> 
> 

Re: file format extensions

[Daniel Sockwell]

+1 from me too.  I'd also add test files to the list, which have at least .t 
and .rakutest 
(with the latter being preferred AFAK, so that GitHub will start highlighting 
them correctly).
I'm not sure if there are other acceptable extensions for test files, though?

Re: file format extensions

[Tom Browder]

On Thu, Dec 30, 2021 at 06:26 Elizabeth Mattijsen  wrote:

> +1 from me.  Shouldn't that be a .rakudoc file ?  :-)


Or .rakupod?

Re: file format extensions

[Vadim Belman]

rakudoc has been chosen as the official extension long ago.

Best regards,
Vadim Belman

> On Dec 30, 2021, at 11:13 AM, Tom Browder  wrote:
> 
> On Thu, Dec 30, 2021 at 06:26 Elizabeth Mattijsen  > wrote:
> +1 from me.  Shouldn't that be a .rakudoc file ?  :-)
> 
> Or .rakupod?

Re: Implementation of documented POD6 behaviour

[Tom Browder]

On Thu, Dec 30, 2021 at 07:17 Richard Hainsworth 
wrote:

> I plan to use the POD6 metadata functionality a lot in a new module. It
> would be far better to separate out the meta data into lines.
>
Richard, there are many pod things that haven’t been implemented yet. I
have planned for a long time to do some more, but I think it’s best to wait
until the Rakuast branch is implemented on the master branch.

FYI, my early efforts were not as good as they should have been because of
my tiny knowledge of the grammar, and I know of many places where things
could be improved. Some of those places require, IMHO, a major redo of some
pod constructs. Not many folks were interested in pod, but that is changing
as Raku is maturing and getting new blood and interest.

You should feel free to work on anything that interests you.

Happy New Year!

Re: file format extensions

[Ralph Mellor]

On Thu, Dec 30, 2021 at 11:20 AM Richard Hainsworth
 wrote:
>
> It seems to me a short page in the docs.raku.org would
> be useful with the various file extensions

I'm +1 for this.

I'm also +1 for recommending `.rakudoc` instead of `.pod6`.
At least, for documentation files related to raku; what I mean
by that caveat will become clear if you consider Pod6Lite, as
discussed in the reddit comment I link below.

> I think that POD6 is neither Plain, nor Old. How about RDM?

Please read this related reddit comment (and, optionally, the
earlier reddit comment it then links to):

https://www.reddit.com/r/rakulang/comments/qwqpag/
podlite_ver_020_autocomplete_and_pod6_snippets/hlzbtfq/

(This latest reddit comment was written in the context of discussing
Pod6Lite's name, but it's mostly about Raku's use of Pod6, not Pod6Lite's.)

As you'll see, I propose we suitably backronym "Pod". In other
words, stick with "Pod", but switch to new words for the P, o, and d.

And I strawman propose "Package of docks" for reasons that will
become apparent if you read the reddit comment(s) I've linked.

--
love, raiph

Re: Implementation of documented POD6 behaviour

[Ralph Mellor]

On Thu, Dec 30, 2021 at 12:18 PM Richard Hainsworth
 wrote:
>
> "In the future..."
>
> with a footnote that it is not implemented.
>
> I am willing to look at the Rakudo code and create a PR to
> implement this functionality. Is there any reason not to do this

I recommend you take into consideration the tremendous energy
being applied to Pod by zagap, the author of Pod6Lite, and align
any Rakunian effort with their effort. (As per the reddit thread I
linked to in my previous reply to you in the file format thread.)

> a POD6 table may not contain a POD6 table.

This is a great example. Regardless of whether zagap does or
does not intend to implement nested tables, simply *discussing*
this issue with them should be very valuable.

--
love, raiph

Re: about binary protocol porting

[Jon Smart]

On 30.12.2021 06:41, Ralph Mellor wrote:

On Wed, Dec 29, 2021 at 1:32 AM Jon Smart  wrote:


I plan to port a binary protocol client to perl6/raku.
I have zero experience on this. Where should I get started?


How well do you know programming, and Raku, and is the
protocol a standard one you can link to with several existing
implementations?



Thanks for the answer. I know perl6 a bit well.
I was thinking maybe perl6/raku need a killer app, such as ruby for 
rails, and python for data science.

This app will help expand the users of perl6 language.

regards,
Jon

Last day for FOSDEM submission

[Marc Chantreux]

hello people,

I just discovered this this morning:

https://www.reddit.com/r/rakulang/comments/rrcp4c/steal_these_ideas_for_raku_fosdem_talks/

I don't remember if there was a previous annoucement in this list but
it's still possible to jump in.

I just submitted one on "Replacing Bash scripts with Raku"

* features and way of doing things i love from zsh
* the raku way [1]
* getting started with raku ecosystem (raku.land, zef, Ddt, fez, rakudoc, 
prove6, ...)

gather/take=while read, Seq vs Pipes, ...) and ideas of modules

1: the raku way are things like

*sh│ raku
───┼─
|  │ Seq.map
xargs -P   │ .race
while read │ gather/take

At some point it could become an Intro section on the Raku documentation
site.

If a native/fluent english speaker want to take over it: i'll be more
than happy to co-author the talk as well (i really feel like i'm a disaster as
speaker).

Regards
marc