git-md-snippet

#!/usr/bin/env perl

=head1 NAME

git-md-snippet - translate markdown links to embedded code snippets

=head1 SYNOPSIS

  git-md-snippet < FILE1 > FILE2

=head1 DESCRIPTION

Read an input and translate links to the files of the repository to the
code blocks and embed them replacing the links with codes.

=head1 FORMAT

While parsing a file the script looks for the links formatted as follows:

  [code=TITLE;url;lang=LANG;numbers;lines=LINES;fence=FENCE;ellipsis](path)

The C<code> is mandatory as it marks the link specified to be replaced
with the content of the specified file.

The code link MUST be stick to the beginning of the line (no any white
spaces are permitted).

=over 4

=item *

B<code>[=I<TITLE>]

Marks the special link. The optional parameter I<TITLE> is a text to
be used as a text under link. If it is not specified, the original link
will be used.

=item *

B<url>

Outputs the link to the original file.

=item *

B<lang>=I<LANG>

Triggers the markdown system to colorize the embedded code accordingly
the specified language.

=item *

B<numbers>

Prints the line numbers in the beginning of each line.

=item *

B<lines>=I<LINES>

Specifies the lines to be printed. This parameter can be either a list
separated by comma and/or a range of lines separated by dash.

=item *

B<fence>=I<backtick | tilde>

Use backtick characters B<`> (ASCII 96) or tildes B<~> (ASCII 126) for
fencing code blocks. It can be useful, when for some reason you need to
fence a code already containing fencing within. Defaults to backtick.

=item *

B<ellipsis>

Print ellipsis (B<...>) to show gaps between different fragments of
one snippet.

=back

Another way to turn on the line range and numbering:

  [code...](path#LLINE1-LLINE2)

where C<LINE1> and C<LINE2> are define the range of line numbers to be
extracted. This feature is compatible with GitHub's way for creating a
permanent link to a code snippet. This format overrides inlined B<numbers>
and B<lines> and turns on the line numbering implicitly.

=head1 EXAMPLES

=head2 Example 1

Assume the following two links:

  [code;lang=perl;numbers;lines=3-14;fence=tilde](git-md-snippet)

and

  [code;lang=perl;fence=tilde](git-md-snippet#L3-L14)

Both will be translated into the following code:

  ~~~perl
   3: =head1 NAME
   4:
   5: git-md-snippet - translate markdown links to embedded code snippets
   6:
   7: =head1 SYNOPSIS
   8:
   9:   git-md-snippet < FILE1 > FILE2
  10:
  11: =head1 DESCRIPTION
  12:
  13: Read an input and translate links to the files of the repository to the
  14: code blocks and embed them replacing the links with codes.

  ~~~

=head1 AUTHORS

Ildar Shaimordanov E<lt>F<ildar.shaimordanov@gmail.com>E<gt>

=head1 COPYRIGHT

Copyright (c) 2019-2021 Ildar Shaimordanov. All rights reserved.

  MIT License

=cut

use strict;
use warnings;

use Getopt::Long;
use Pod::Usage;

pod2usage({ -verbose => 2, -noperldoc => 1 }) if ! @ARGV && -t 0;

# =========================================================================

sub parse_range {
	my $ranges = shift;
	my @r = ();
	my @ranges = split /,/, $ranges // '';
	foreach ( @ranges ) {
		m/^(?:(\d+)-(\d+)|(\d+))$/ and do {
			push @r, [ int $1, int $2 ] if $1;
			push @r, [ int $3, int $3 ] if $3;
		}
	}
	return sort { $a->[0] <=> $b->[0] } @r;
}

my %fence_list = qw( backtick ``` tilde ~~~ );
my $default_fence = "backtick";

sub parse_options {
	my $opts = shift;
	my %opts = ();
	foreach ( split ";", $opts ) {
		my ( $k, $v ) = split "=";
		$opts{$k} = $v // '';
	}
	$opts{fence} = $fence_list{ $opts{fence} || $default_fence } || $fence_list{$default_fence};
	$opts{ranges} = [ parse_range $opts{lines} ];
	$opts{len} = 0;
	foreach ( @{ $opts{ranges} } ) {
		my $len = length $_->[1];
		$opts{len} = $len if $opts{len} < $len;
	}
	return %opts;
}

# =========================================================================

sub number_1 { sprintf "%$_[2]d: %s", $_[0], $_[1] }
sub number_0 { $_[1] }
sub ranges_1 { grep { $. >= $_->[0] && $. <= $_->[1] } @{ $_[0] } }
sub ranges_0 { 1 }

sub prepare_code {
	my $file = shift;
	my %opts = @_;

	my $number = exists $opts{numbers} ? \&number_1 : \&number_0;
	my $ranges = @{ $opts{ranges} } ? \&ranges_1 : \&ranges_0;

	if ( $file =~ m/
		([^#]+)
		\#L(\d+)(?:-L(\d+))?
	/x ) {
		$file = $1;
		my $L1 = $2;
		my $L2 = $3 // $L1;
		$opts{ranges} = [ [ $L1, $L2 ] ];
		$number = \&number_1;
		$ranges = \&ranges_1;
	}

	my @lines = ();
	my $last_line_number = 0;

	open FILE, "$file" or warn "Unable to open file: $file\n" and return;
	while ( <FILE> ) {
		next unless $ranges->($opts{ranges});

		push @lines, "...\n"
			if exists $opts{ellipsis}
			&& $last_line_number
			&& $. - $last_line_number > 1;

		$last_line_number = $.;

		push @lines, $number->($., $_, $opts{len});
	}
	close FILE;

	my $text = $opts{code} || $file;

	return sprintf("%s\n$opts{fence}%s\n%s\n$opts{fence}\n",
		exists $opts{url} ? "[$text]($file)" : "",
		$opts{lang} || "",
		join "", @lines) if @lines;
}

# =========================================================================

while ( <> ) {
	m/^\[(code\b.*)\]\(([^()]+)\)\s*$/ and do {
		my %opts = parse_options $1;
		my $code = prepare_code $2, %opts;
		$_ = $code if $code;
	};
	print;
}

# =========================================================================

# EOF