Image

head

code

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

unit module Doc::Executable;
use Doc::Executable::Parser;
use Distribution::Resources::Menu;

my $rsm = ResourceMenu.new(
        distribution => $?DISTRIBUTION,
        resources => %?RESOURCES
        );

sub execute is export {
    my @parsed = parse-file $rsm.execute.file-path;
    eval-file(@parsed);
}



Doc::Executable - executes a menu for selecting "executable" Raku tutorials in
this distribution which are parsed and executed as Raku code.


=begin code :lang<raku>
docexec
=end code


The goal of C<Doc::Executable> is to make it easy to write plain text Raku tutorials containing
code snippets with accompanying explanations.


The C<docexec> command displays a navigable menu on the command line to allow users to
select a parseable text file. The text file contains example Raku code along with explanations
accompanying each bit of code. Once parsed, the resultant file is run as Raku code with the output
showing the results of the code along with the descriptions for how the code works.


This module is in its early development stages and admittedly has limited use, allowing
only for the execution of an entire code example file at once. Also, it can only
load and execute files packaged in this distribution.


Anyone who has looked at code documentation has seen embedded code examples like this to
illustrate how code works:


=begin code :lang<raku>

(1, 2, 3).shift;      # Error Cannot call 'shift' on an immutable 'List'
(1, 2, 3).unshift(0); # Error Cannot call 'unshift' on an immutable 'List'

=end code


Often you want to fiddle with the code so you have to break out the electronic
scissors and tediously copy and paste the code into a file and then execute it.


So the idea behind a executable doc is to allow you to easily place your collection
of code snippets into a single file and easily edit them with less hassle.


A single executable doc example looks like this:


=begin code :lang<raku>

##
say 1, 2;
say (1, 2);
#* To pass Lists to a function, be sure to use parentheses
#* Without parentheses, the two elements are treated as separate parameters to the 'say' function
# A List is passed with parentheses which gives a different output.
##

=end code


This plain text file is written with your favorite text editor.


After getting parsed and executed by this module, it outputs:


=begin code
To pass Lists to a function, be sure to use parentheses:

say 1, 2;
say (1, 2);

Output:
12
(1 2)

Without parentheses, the two elements are treated as separate parameters to the 'say' function
A List is passed with parentheses which gives a different output..
=end code


And now this output can be exported to your favorite online tutorial.


As mentioned, the module in it's current state is rather limited and is
more just a proof of concept. Future ideas for improving this distribution
include:


item

Other suggestion on how to make this module more useful are welcome.


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


Executable

use Menu::HashToMenu;
unit class Distribution::Resources::Menu;

class ResourceMenu is export {
    has CompUnit::Repository::Distribution $.distribution is required;
    has Distribution::Resources $.resources is required;
    has HashToMenu $.menu is rw;
    has Str @.paths;
    has $.file is rw;
    has Str $.file-content is rw;
    has Str $.file-path is rw;


    method build-menu($hash) {
        # following code may be useful in future versions
        #my &action = sub ($path) { $.resources{$path}.slurp };
        #my &processor = sub ($str) { flip $str };
        #self.menu = HashToMenu.new($hash, &action, &processor);
        #self.menu = HashToMenu.new($hash, &action);
        self.menu = HashToMenu.new($hash, :strip-leading-number);
    }

    method menu-populate() {
        my @paths;
        push @paths, (.split: '/').Array for self.paths;
        my %hash;
        for @paths {
            postcircumfix:<{; }>(%hash, $_) = $_.join('/');
        }
        self.build-menu: %hash;
    }

    method init() {
        self.paths = self.distribution.meta<resources>.sort;
        self.menu-populate;
    }

    method execute() {
        self.init if !self.menu;
        my $option = self.menu.execute;
        my $file = $.resources{$option.option-value};
        $.file = $file;
        $.file-content = $file.slurp;
        $.file-path = $file.absolute;
        return self;
    }
}



Distribution::Resources::Menu - Navigate the files in the resources directory
of your Raku distribution from the command line


Place something like the following code into a module in your distribution:


=begin code :lang<raku>
use Injector  # IMPORTANT
use Distribution::Resources::Menu;
unit module Your::Module;

my $rsm = ResourceMenu.new(distribution => $?DISTRIBUTION, resources => $%RESOURCES);

sub execute-the-menu-to-pick-a-file is export {
    $rsm.execute;
}

=end code


And now you can execute the menu with something like this:


=begin code :lang<raku>
use Your::Module;

my $resource = execute-the-menu-to-pick-a-file();
# This will display a menu on the command line and prompt the user
# to select a file from the "resources" directory of the distribution

say $resource.file-path;
say $resource.file-content;
my $content = $resource

=end code


Distribution::Resources::Menu generates and executes a menu
for navigating and selecting files located in a distribution's C<resources> directory.


Executes the interactive command-line menu for selecting a file from
the resources directory of the distribution.


Returns the string value of the content of the file.


Returns the string value of the path to the file contained in the C<$%RESOURCES>
variable.


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

DESCRIPTION

METHODS

execute

file-content

file-path

AUTHOR

COPYRIGHT AND LICENSE

Distribution::Resources::Menu v0.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation