NAME

inc/Probe.pm - Probes some machine configuration parameters for Term::Size::Perl's sake

SYNOPSIS

    $ perl 'inc/Probe.pm';

DESCRIPTION

TODO: improve error handling - this failed horribly in Windows with ExtUtils::CBuilder

  Probe.pm 
  * writes a C file
  * builds it (ExtUtils::CBuilder)
  * runs it (backquote)
  * grabs the output and creates Term/Size/Perl/Params.pm

Yes, that's Perl code which writes C code which writes Perl code.

a typical declaration (found somewhere along "termios.h")

  /* Interface to get and set terminal size. */
  struct  winsize {
    unsigned short  ws_row;    /* Rows, in characters     */
    unsigned short  ws_col;    /* Columns, in characters  */
    unsigned short  ws_xpixel; /* Horizontal size, pixels */
    unsigned short  ws_ypixel; /* Vertical size, pixels   */
  };

ASSUMPTIONS SO FAR:

• struct winsize has no alignment pad (because we'll be using unpack and relying on this arrangement)

• the fields follow the order: ws_row, ws_col, ws_xpixel, ws_ypixel (because we'll be using unpack and relying on this order)

• the type of each field is native unsigned short (because we'll be using unpack with S! field)

WHAT WE ARE PROBING

• sizeof(struct winsize)

• TIOCGWINSZ

• the definition of TIOCGWINSZ

WHAT THE OUTPUT LOOKS LIKE

  package Term::Size::Perl::Params; 

  sub params {
      return (
          winsize => {
              sizeof => 8,
              mask => 'S!S!S!S!'
          },
          TIOCGWINSZ => {
              value => 21505,
              definition => qq{(('T' << 8) | 1)}
          }
      );
  }

  1;

FUNCTIONS

write_probe

  $c_file = write_probe($c_file);

Writes the source code of the probe to the file $c_file. Returns $c_file if successful. Returns undef if something bad happened while writing the file.

build_probe

  $exe_file = build_probe($c_file);

Compiles the C source $c_file to object and then links it to an executable file. Returns the executable file name. If successful, it deletes the intermediary object file. If compiling or linking fails, returns undef.

run_probe

  $output = run_probe($exe_file);

Runs the executable file $exe_file, captures its output to STDOUT and returns it. Returns undef if the exit code ($?) is not 0.

write_params

  $out_file = write_params($pl_code, $out_file);

Writes the contents of $pl_code (a scalar supposed to contain the Perl code of the information we were after) to file $out_file. Returns $out_file if successful. Returns undef if something bad happened while writing the file.

run

  run()

Runs the probe. First, it writes a C file named probe.c. Second, it compiles and links this source. Then, the resulting executable is run and its output captured. At last, this output get written to the file Params.pm. (The intermediary files - probe.c, object and executable files - are deleted at the end of a successful run.) If successful, returns 0. Otherwise, returns true.

SEE ALSO

Term::Size::Perl

AUTHOR

A. R. Ferreira, <ferreira@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by A. R. Ferreira

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.