view release on metacpan or  search on metacpan

lib/Graphics/Asymptote.pm  view on Meta::CPAN

unrecognized command and pass the function name straight to Asymptote by name.
For example,

 $asy->size(0, 100);                # set's canvas size
 $asy->send("size(0, 100);");       # equivalent send command
 
 $asy->write("my_asy_var");         # writes contents of my_asy_var
 $asy->send('write(my_asy_var);');  # equivalent send command
 
 $asy->write('"Hello!"');           # write's Hello!
 $asy->send('write("Hello!");');    # equivalent send command

This can be handy if you have a single command you want to pass to the
interpreter, in which case a C<send> command can get somewhat noisy.  It is
particularly clean if the function you need to call only needs numeric
arguments, such as the C<size> command above.  The second and third examples
show the quoting and double-quoting needed for C<AUTOLOAD>ed commands; the
double quoting is annoying, but as you can see it's better than keeping track
of all your semicolons and quotes (which each of the equivalent C<send>
commands demonstrate).

Note that you cannot use C<AUTOLOAD> for the Asymptote C<import> command.
First, asymptote's command is just that - a command, not a function.  The
C<AUTOLOAD> command would try to wrap its arguments in parentheses, which
Asymptote wouldn't like.  Second, Perl objects have an C<import> function
defined, so C<AUTOLOAD> would never actually be called, anyway.

=head1 DEBUGGING

Life being what it is, you will have bugs in your code, which inclues the code
you send to Asymptote!  One way to root them out is to increase the verbosity,
to actually see what is being sent down the pipe to Asymptote.

=head2 Changing the verbosity setting

You can set the verbosity setting at any time.  For example, if you know that
a particular set of commands is giving you trouble, you can increase the
verbosity in the vicinity of that command:

 # ... good code (verbosity is 0)
 
 # Not sure about the asy code that follows:
 $asy++;
 # ... troublesome code here
 
 # OK, what follows should be fine
 $asy--;

An important example of changing the verbosity on
the fly is to have the pipe NOT tell us when it is closing when we
expect it to close.  Here's what I mean:

 #!/usr/bin/perl
 use Graphics::Asymptote;
 $asy = Graphics::Asymptote->new(verbose => 1);
 undef $asy;

This (complete) script simply creates and destroys the pipe.  On my machine,
the output of this looks like:

 david@davids-desktop:~$ ./asytest.pl 
 ********** To Asymptote **********
 //Quitting Asymptote
 **********************************
 
 david@davids-desktop:~$ 

The business about quitting is useful, especially if you find your interpreter
quits unexpectedly, but suppose you know when your pipe is going away and want
to remove the extra line noise.  To avoid that, set the verbosity to 0
before C<undef>ing your pipe or letting it go out of scope, like this:

 #!/usr/bin/perl
 use Graphics::Asymptote;
 $asy = Graphics::Asymptote->new(verbose => 1);
 
 # asymptote code will eventaully go here.
 
 $asy->set_verbosity();

=head2 Using verbosity for debugging

Consider this snippet, which should print 'Hello!' using Asymptote's write
command:

 $asy->write('Hello!');

This doesn't do what I expect:

 -: 1.12: syntax error
 error: could not load module '-'

Let's go through this message bit by bit.  First, C<-:> means, "I (Asymptote)
am reading from the standard input (not a file)."  In other words, the problem
is with what we sent to the Asymptote pipe.  If the problem was in a script we
told C<asy> to import, the "-" would be replaced with the file name.  This is
echoed in the second line, stating it C<could not load module '-'>, which means
it couldn't parse the standard input.

OK, next we have C<1.12: syntax error>, which means that on the
first line, 12th character, we have a problem.  What could it be?
To help find out, set the verbosity higher and
see what we're actually sending to the Asymptote interpreter:

 $asy++;
 $asy->write('Hello!');
 $asy--;

The resulting message looks like this:

 ********** To Asymptote **********
 write(Hello!);
 **********************************
 
 -: 1.12: syntax error
 error: could not load module '-'

Now you can easily see the problem: we forgot to put quotes around our string,
and Asymptote really doesn't like that exclamation point! Correcting our code to:

 $asy++;
 $asy->write('"Hello!"');
 $asy--;

yeilds