blib/lib/Polyglot.pm

filter: Statementstmt 25.4% 26 / 102 Branchbran 0.0% 0 / 26 Conditioncond 20.0% 1 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 33.3% 8 / 24 Podpod 100% 9 / 9 totaltotal 26.0% 44 / 169 CC 15 SCAR 32.7
CC
15
Cov
20%
run
90.0
value
20.0
__ANON__
20.0
CRAP 26.4
↑ Summary
1 2 ▶use 5.008;
Subroutine BEGIN: called CC=1 SCAR=0.0
2  
3 package Polyglot;
4 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use vars qw($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 ▶no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 =encoding utf8
11  
12 =head1 NAME
13  
14 Polyglot - a little language interpreter
15  
16 =head1 SYNOPSIS
17  
18 # THIS IS ALPHA SOFTWARE
19  
20 use Polyglot;
21  
22 my $interpreter = Polyglot->new();
23  
24 $polyglot->add_action( ... );
25  
26 $interpreter->run();
27  
28 =head1 DESCRIPTION
29  
30 This module implements a simple, little language interpreter to
31 describe the language.
32  
33 For this interpreter, a program is a series of lines with one
34 directive perl line. The first group of non-whitespace characters in
35 the line is a the I<directive> and the remainder of the line becomes
36 its arguments. The interpreter reads one line, does what it says,
37 then moves to the next line until it reaches the end of the file. If
38 the interpreter does not read from a file, it prompts for standard
39 input.
40  
41 A small program to control an CD player may look like:
42  
43 VOLUME 5
44 PLAY
45 SLEEP 50
46 STOP
47 EJECT
48  
49 The interpreter does not support loops, conditionals, or other fancy
50 things, and I do not have plans to add those things.
51  
52 The interpret provides a few commands, but I expect other people to
53 create their own little languages specialized for their task. Most of
54 the methods deal with creating the language description at the
55 interpreter level. I plan on creating another layer above this to
56 make the language description even more simple.
57  
58 =cut
59  
60 2 ▶use autouse 'Data::Dumper' => 'Dumper';
Subroutine BEGIN: called CC=1 SCAR=0.0
61  
62 2 ▶use Carp qw(carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
63 2 ▶use Text::ParseWords qw( quotewords );
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 2 our $VERSION = '1.008';
66  
67 2 ▶my $Debug = $ENV{DEBUG} || 0;
Condition50%1/2
$ENV{'DEBUG'} || 0
l!l
02
MC/DC0%0/1
$ENV{'DEBUG'} || 0
$ENV{'DEBUG'}
Truth table50%1/2
A
A= $ENV{'DEBUG'}
Aresult
11
00
68  
69 =head2 Methods
70  
71 =over 4
72  
73 =item new
74  
75 Creates a new Polyglot object and returns it.
76  
77 =cut
78  
79 0 ▶sub new {
Subroutine new: not called CC=1 SCAR=6.9
Pod documented
80 0 my( $class, @args ) = @_;
81  
82 0 my $self = bless {}, $class;
83  
84 $self->add_action( 'POLYGLOT',
85 0 ▶ sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
86 0 my( $self, $package ) = @_;
87 0 eval{ eval "require $package" };
88 0 } );
89 0 ▶ $self->add_action( 'HELP', sub { my $self = shift; $self->help( @_ ) } );
Subroutine __ANON__: not called CC=1 SCAR=6.9
90 0 ▶ $self->add_action( 'EXIT', sub { exit } );
Subroutine __ANON__: not called CC=1 SCAR=6.9
91 0 ▶ $self->add_action( 'REFLECT', sub { print Dumper( $_[0] ) } );
Subroutine __ANON__: not called CC=1 SCAR=6.9
92 0 ▶ $self->add_action( 'SHOW', sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
93 0 my( $self, $name ) = ( shift, uc shift );
94 0 print "$name = ", $self->value($name), "\n";
95 0 $self; } );
96 }
97  
98 =item run
99  
100 Start the interpreter. It will read lines from the file names in
101 @ARGV or from standard input using the diamond operator. It splits
102 lines on whitespace and assumes the first element of that list is
103 the directive name. If the directive does not exist, it prints a
104 warning and continues.
105  
106 This method uses the diamond operator and assumes that nothing else
107 has mucked with it.
108  
109 =cut
110  
111 0 ▶sub run {
Subroutine run: not called CC=9 SCAR=45.0
Pod documented
112 0 my $self = shift;
113  
114 0 my $prompt = "$0> ";
115  
116 0 ▶ print "H: Waiting for commands on standard input\n$prompt"
Branch: 1 branch
BranchTrueFalseTotal
unless @ARGV 0 0 0
117 unless @ARGV;
118  
119 0 ▶ while( <> ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline ARGV)) 0 0 0
120 0 print "$ARGV\[$.]: $_";
121 0 chomp;
122 0 ▶ next if /^\s*#?$/;
Branch: 1 branch
BranchTrueFalseTotal
if /^\s*#?$/ 0 0 0
123 0 my( $directive, $string ) = split /\s+/, $_, 2;
124  
125 0 $directive = uc $directive;
126 0 ▶ carp "DEBUG: directive is $directive\n" if $Debug;
Branch: 1 branch
BranchTrueFalseTotal
if $Debug 0 0 0
127  
128 0 my @arguments = quotewords( '\s+', 0, $string );
129 0 ▶ carp "DEBUG: arguments are @arguments\n" if $Debug;
Branch: 1 branch
BranchTrueFalseTotal
if $Debug 0 0 0
130  
131 0 eval {
132 0 ▶ die "Undefined subroutine" unless exists $self->{$directive};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{$directive} 0 0 0
133 0 $self->{$directive}[1]( $self, @arguments );
134 };
135  
136 0 ▶ warn "Not a valid directive: [$directive] at $ARGV line $.\n"
Branch: 1 branch
BranchTrueFalseTotal
if $@ =~ /Undefined subroutine/ 0 0 0
137 if $@ =~ m/Undefined subroutine/;
138  
139 0 ▶ print "$prompt" if $ARGV eq '-';
Branch: 1 branch
BranchTrueFalseTotal
if $ARGV eq "-" 0 0 0
140 }
141  
142 0 print "\n";
143 }
144  
145 =item state
146  
147 Returns the string used to mark a directive that affects the program
148 state.
149  
150 =cut
151  
152 sub state () { 'state' }
153  
154 =item action
155  
156 Returns the string used to mark a directive that performs an action.
157  
158 =cut
159  
160 sub action () { 'action' }
161  
162  
163 =item add( DIRECTIVE, TYPE, CODEREF, INITIAL_VALUE, HELP )
164  
165 Adds DIRECTIVE to the little language with TYPE (state or action).
166 The value of the directive (for those that represent program state) is
167 INITIAL_VALUE or undef. The CODEREF is executed when the interpreter
168 encounters the directive. The built-in HELP directive returns the
169 HELP string for this DIRECTIVE.
170  
171 =cut
172  
173 0 ▶sub add {
Subroutine add: not called CC=1 SCAR=6.9
Pod documented
174 0 my( $self, $name, $state, $sub, $value, $help ) = @_;
175  
176 0 $self->{$name} = [ $state, $sub, $help ];
177  
178 0 $self;
179 }
180  
181 =item value( DIRECTIVE [, VALUE ] )
182  
183 Returns the value for DIRECTIVE, or sets it if you specify VALUE.
184  
185 =cut
186  
187 0 ▶sub value {
Subroutine value: not called CC=4 SCAR=30.0
Pod documented
188 0 my( $self, $name, $value ) = @_;
189 0 ▶ carp "Setting $name with $value\n" if $Debug;
Branch: 1 branch
BranchTrueFalseTotal
if $Debug 0 0 0
190  
191 0 ▶ return unless exists $self->{ $name };
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{$name} 0 0 0
192  
193 0 ▶ return $self->{$name}[2] unless defined $value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 0 0 0
194  
195 0 $self->{$name}[2] = $value;
196  
197 }
198  
199 =item add_action( DIRECTIVE, CODEREF, INITIAL_VALUE, HELP )
200  
201 Like add(), but without TYPE which is automatically filled in. Use
202 this for a directive that does something other than setting a value.
203  
204 The CODEREF can be anything. The first argument is always the
205 interpreter object, and the rest of the arguments are from the current
206 line.
207  
208 =cut
209  
210 0 ▶sub add_action {
Subroutine add_action: not called CC=1 SCAR=6.9
Pod documented
211 0 my $self = shift;
212 0 my $name = uc shift;
213 0 my( $sub, $value, $help ) = @_;
214  
215 0 $self->{$name} = [ $self->action, $sub, $value, $help ];
216  
217 0 $self;
218 }
219  
220 =item add_state( DIRECTIVE, INITIAL_VALUE, HELP )
221  
222 Like add(), but without TYPE and CODEREF which is automatically filled in.
223 Use this for a directive that can set a value.
224  
225 =cut
226  
227 0 ▶sub add_state {
Subroutine add_state: not called CC=1 SCAR=6.9
Pod documented
228 0 my $self = shift;
229 0 my $name = uc shift;
230 0 my( $value, $help ) = @_;
231  
232 $self->{$name} = [ $self->state,
233 0 ▶ sub{ my $self = shift; $self->value( $name, @_ ) }, $value, $help ];
Subroutine __ANON__: not called CC=1 SCAR=6.9
234  
235 0 $self;
236 }
237  
238 =item add_toggle( DIRECTIVE, INITIAL_VALUE, HELP )
239  
240 Like add(), but without TYPE and CODEREF which is automatically filled in.
241 Use this for a value that can be either "on" or "off".
242  
243 =cut
244  
245 0 ▶sub add_toggle {
Subroutine add_toggle: not called CC=1 SCAR=6.9
Pod documented
246 0 my $self = shift;
247 0 my $name = uc shift;
248 0 my( $value, $help ) = @_;
249  
250 0 ▶ my $code = sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
251 0 my $self = shift;
252  
253 0 ▶ return $self->{$name}[2] unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 0 0 0
254 0 my $value = lc shift;
255 0 warn "saw $name with value [$value]\n";
256  
257 0 ▶ unless( $value eq 'on' or $value eq 'off' ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($value eq "on" or $value eq "off") 0 0 0
Condition0%0/3
$value eq "on" or $value eq "off"
l!l&&r!l&&!r
000
MC/DC0%0/2
$value eq "on" or $value eq "off"
$value eq "on" $value eq "off"
Truth table0%0/3
A or B
A= $value eq "on"B= $value eq "off"
ABresult
1X1
011
000
258 0 warn "$name can be only 'on' or 'off', line $.\n";
259 return
260 0 }
261  
262 0 $self->{$name}[2] = $value;
263  
264 0 print "$name is [$$self{$name}[2]]\n";
265 0 };
266  
267 0 $self->{$name} = [ $self->state, $code, $value, $help ];
268  
269 0 $self;
270 }
271  
272 =item help
273  
274 Returns a help message: you want to override this.
275  
276 =cut
277  
278 0 ▶sub help {
Subroutine help: not called CC=1 SCAR=6.9
Pod documented
279 0 my $self = shift;
280 0 my $name = uc shift;
281  
282 0 print "This is a help message for [$name]\n";
283  
284 0 $self;
285 }
286  
287 =item directives
288  
289 Returns a list of directives.
290  
291 =cut
292  
293 0 ▶sub directives {
Subroutine directives: not called CC=1 SCAR=6.9
Pod documented
294 0 my $self = shift;
295  
296 0 return sort keys %$self;
297 }
298  
299 =back
300  
301 =head1 POLYGLOT LANGUAGES
302  
303 At the moment you are stuck with the examples and examining
304 the source.
305  
306 =head2 Built in directives
307  
308 The Polyglot module provides some basic directives.
309  
310 =over 4
311  
312 =item POLYGLOT PACKAGE
313  
314 Load a Perl package.
315  
316 =item SHOW DIRECTIVE
317  
318 Displays the value of DIRECTIVE
319  
320 =item DUMP
321  
322 Displays all of the "state" DIRECTIVES with their values
323  
324 =item REFLECT
325  
326 Displays the Polyglot object
327  
328 =item HELP DIRECTIVE
329  
330 Displays the help message for DIRECTIVE
331  
332 =back
333  
334 =head1 TO DO
335  
336 * I should really make all of these methods class methods that
337 access a Singleton object stored as class data.
338  
339 =head1 SOURCE AVAILABILITY
340  
341 The source is in GitHub:
342  
343 https://github.com/briandfoy/polyglot
344  
345 =head1 AUTHOR
346  
347 brian d foy, C<< <briandfoy@pobox.com> >>.
348  
349 =head1 COPYRIGHT AND LICENSE
350  
351 Copyright © 2002-2025, brian d foy <briandfoy@pobox.com>. All rights reserved.
352  
353 This program is free software; you can redistribute it and/or modify
354 it under the same terms as Perl itself.
355  
356 =cut
357  
358 2 "ein";
↑ Summary