para

use v6.d;
unit module RKDS:api<2>;

###############################################
## RAKU DEPLOYMENT SYSTEM - Companion Module ##
###############################################



head

code

=begin code
<% use RKDS -%>
This is my template!
I want it to be writable. <%- make-writable %>
I want to know where it’ll be outputted: <%= (get-output-dir) ~ (get-output) %>
And I want it deployed up until 2026.
<% don't-deploy unless DateTime.now.year == 2025 -%>
=end code


RKDS (RaKu Deployment System) is a tool that takes a directory filled with
L<ERK:https://raku.land/zef:ulisesb/ERK> templates and I<deploys> them to
another directory. Supports including raku modules defined in a C<.rkds/lib>
directory and customizing the deployment of templates individually.


This module can be used inside those templates for communicating with the rkds
binary running them. The subroutines get and set certain values, specific to
the current template or input and output directories. They return "OK" unless
otherwise noted.



#----------#
#  ERRORS  #
#----------#

role X::RKDS is Exception { }

#| Thrown if not running inside an RKDS instance
class X::RKDS::NoInstanceRunning does X::RKDS {
	method message() {
		'No RKDS instance is running';
	}
}

#| Thrown if an error is received
class X::RKDS::ReceivedError does X::RKDS {
	has Str $.error;
	method message() {
		'Received error through socket' ~
			($!error.defined ?? ": $!error" !! '');
	}
}

#| Thrown if a malformed message is received
class X::RKDS::MalformedMessage does X::RKDS {
	has Str $.msg;
	method message() {
		'Received malformed message through socket' ~
		($!msg.defined ?? ": $!msg" !! '');
	}
}

#---------------------------------#
#  SOCKET CONNECT AND DISCONNECT  #
#---------------------------------#

my IO::Socket::INET $conn;

INIT {
	X::RKDS::NoInstanceRunning.new.throw unless %*ENV<RKDS_PORT>:exists;

	$conn = IO::Socket::INET.new( :host<localhost>, :port(%*ENV<RKDS_PORT>) );
}

END {
	$conn.close;
}

#-------------#
#  FUNCTIONS  #
#-------------#

my sub send-message(Str:D() $message --> Str:D) {
	$conn.put: $message;

	given $conn.recv.chomp {
		when / ^ 'ok ' .+ / {
			return .subst: / ^ 'ok ' /;
		}

		when / ^ 'err ' .+ / {
			my $error = .subst: / ^ 'err ' /;
			X::RKDS::ReceivedError.new(:$error).throw;
			return $error;
		}

		default {
			X::RKDS::MalformedMessage.new(msg => $_).throw;
			return $_;
		}
	}

	CATCH { default {
		$*ERR.put: "RKDS: Error sending message '$message': { .message }";
	} }
}

#| Mark the template to be deployed (the default)
my sub do-deploy(--> Str:D) is export {
	send-message 'set to-deploy true'
}

#| Mark the template to not be deployed
my sub don't-deploy(--> Str:D) is export {
	send-message 'set to-deploy false'
}

#| Alias for don't-deploy
my sub dont-deploy(--> Str:D) is export {
	don't-deploy
}

#| Mark the template output to be readable by the user (the default)
my sub make-readable(--> Str:D) is export {
	send-message 'set readable true'
}

#| Mark the template output to not be readable by the user
my sub make-not-readable(--> Str:D) is export {
	send-message 'set readable false'
}

#| Mark the template output to be writable by the user
my sub make-writable(--> Str:D) is export {
	send-message 'set writable true'
}

#| Mark the template output to be not writable by the user (the default)
my sub make-not-writable(--> Str:D) is export {
	send-message 'set writable false'
}

#| Mark the template output to be executable by the user
my sub make-executable(--> Str:D) is export {
	send-message 'set executable true'
}

#| Mark the template output to be not executable by the user (the default)
my sub make-not-executable(--> Str:D) is export {
	send-message 'set executable false'
}

#| Change the template’s output file to another (relative to the output
#| directory). Throws X::RKDS::ReceivedError if the path is not valid. Returns
#| "OK" or the error.
my sub set-output(Str:D() $path --> Str:D) is export {
	send-message 'set output ' ~ $path
}

#| Returns the absolute path to the input directory
my sub get-input-dir(--> IO::Path:D) is export {
	(send-message 'get input-dir').IO
}

#| Returns the absolute path to the output directory
my sub get-output-dir(--> IO::Path:D) is export {
	(send-message 'get output-dir').IO
}

#| Returns the template’s input file (relative to the input directory)
my sub get-input(--> IO::Path:D) is export {
	(send-message 'get input').IO
}

#| Returns the template’s output file (relative to the output directory)
my sub get-output(--> IO::Path:D) is export {
	(send-message 'get output').IO
}


root

README

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<AI|file:../mcp/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=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<Download | file:../download/index.podlite>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>

=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>
    =item2 L<Hand these documents to an AI assistant|file:../mcp/index.podlite>

=end nested
=begin nested :!nested
=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/>

=end nested
=end React


Built with L<Podlite|https://podlite.org> — the markup and publishing tools behind this site.


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


RKDS

NAME

SYNOPSIS

DESCRIPTION

RKDS v2.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation