home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _fc6e113e1111457ff781913e1256b5ff < prev    next >
Text File  |  2004-06-01  |  32KB  |  955 lines
  1. package Tk::CmdLine; # -*-Perl-*-
  2.  
  3. #/----------------------------------------------------------------------------//
  4. #/ Module: Tk/CmdLine.pm
  5. #/
  6. #/ Purpose:
  7. #/
  8. #/   Process standard X11 command line options and set initial resources.
  9. #/
  10. #/ Author: ????                      Date: ????
  11. #/
  12. #/ History: SEE POD
  13. #/----------------------------------------------------------------------------//
  14.  
  15. use vars qw($VERSION);
  16. $VERSION = '4.006'; # $Id: //depot/Tkutf8/Tk/CmdLine.pm#6 $
  17.  
  18. use 5.004;
  19.  
  20. use strict;
  21.  
  22. use Config;
  23.  
  24. my $OBJECT = undef; # define the current object
  25.  
  26. #/----------------------------------------------------------------------------//
  27. #/ Constructor
  28. #/   Returns the object reference.
  29. #/----------------------------------------------------------------------------//
  30.  
  31. sub new # Tk::CmdLine::new()
  32. {
  33.     my $this  = shift(@_);
  34.     my $class = ref($this) || $this;
  35.  
  36.     my $name = 'pTk';
  37.     $name = $1 if (($0 =~ m/(?:^|[\/\\])([\w-]+)(?:\.\w+)?$/) && ($1 ne '-e'));
  38.  
  39.     my $self = {
  40.         name        => $name,
  41.         config      => { -name => $name },
  42.         options     => {},
  43.         methods     => {},
  44.         command     => [],
  45.         synchronous => 0,
  46.         iconic      => 0,
  47.         motif       => ($Tk::strictMotif || 0),
  48.         resources   => {} };
  49.  
  50.     return bless($self, $class);
  51. }
  52.  
  53. #/----------------------------------------------------------------------------//
  54. #/ Process the arguments in a given array or in @ARGV.
  55. #/   Returns the object reference.
  56. #/----------------------------------------------------------------------------//
  57.  
  58. sub Argument_ # Tk::CmdLine::Argument_($flag) # private method
  59. {
  60.     my $self = shift(@_);
  61.     my $flag = shift(@_);
  62.     unless ($self->{offset} < @{$self->{argv}})
  63.     {
  64.         die 'Usage: ', $self->{name}, ' ... ', $flag, " <argument> ...\n";
  65.     }
  66.     return splice(@{$self->{argv}}, $self->{offset}, 1);
  67. }
  68.  
  69. sub Config_ # Tk::CmdLine::Config_($flag, $name) # private method
  70. {
  71.     my $self = shift(@_);
  72.     my ($flag, $name) = @_;
  73.     my $val = $self->Argument_($flag);
  74.     push(@{$self->{command}}, $flag, $val);
  75.     $self->{config}->{"-$name"} = $val;
  76. }
  77.  
  78. sub Flag_ # Tk::CmdLine::Flag_($flag, $name) # private method
  79. {
  80.     my $self = shift(@_);
  81.     my ($flag, $name) = @_;
  82.     push(@{$self->{command}}, $flag);
  83.     $self->{$name} = 1;
  84. }
  85.  
  86. sub Option_ # Tk::CmdLine::Option_($flag, $name) # private method
  87. {
  88.     my $self = shift(@_);
  89.     my ($flag, $name) = @_;
  90.     my $val = $self->Argument_($flag);
  91.     push(@{$self->{command}}, $flag, $val);
  92.     $self->{options}->{"*$name"} = $val;
  93. }
  94.  
  95. sub Method_ # Tk::CmdLine::Method_($flag, $name) # private method
  96. {
  97.     my $self = shift(@_);
  98.     my ($flag, $name) = @_;
  99.     my $val = $self->Argument_($flag);
  100.     push(@{$self->{command}}, $flag, $val);
  101.     $self->{methods}->{$name} = $val;
  102. }
  103.  
  104. sub Resource_ # Tk::CmdLine::Resource_($flag, $name) # private method
  105. {
  106.     my $self = shift(@_);
  107.     my ($flag, $name) = @_;
  108.     my $val = $self->Argument_($flag);
  109.     if ($val =~ /^([^!:\s]+)*\s*:\s*(.*)$/)
  110.     {
  111.         push(@{$self->{command}}, $flag, $val);
  112.         $self->{options}->{$1} = $2;
  113.     }
  114. }
  115.  
  116. my %Method = (
  117.     background   => 'Option_',
  118.     bg           => 'background', # alias
  119.     class        => 'Config_',
  120.     display      => 'screen',     # alias
  121.     fg           => 'foreground', # alias
  122.     fn           => 'font',       # alias
  123.     font         => 'Option_',
  124.     foreground   => 'Option_',
  125.     geometry     => 'Method_',
  126.     iconic       => 'Flag_',
  127.     iconposition => 'Method_',
  128.     motif        => 'Flag_',
  129.     name         => 'Config_',
  130.     screen       => 'Config_',
  131.     synchronous  => 'Flag_',
  132.     title        => 'Config_',
  133.     xrm          => 'Resource_'
  134. );
  135.  
  136. sub SetArguments # Tk::CmdLine::SetArguments([@argument])
  137. {
  138.     my $self = (@_ # define the object as necessary
  139.         ? ((ref($_[0]) eq __PACKAGE__)
  140.             ? shift(@_)
  141.             : (($_[0] eq __PACKAGE__) ? shift(@_) : 1) && ($OBJECT ||= __PACKAGE__->new()))
  142.         : ($OBJECT ||= __PACKAGE__->new()));
  143.     $OBJECT = $self; # update the current object
  144.     $self->{argv}   = (@_ ? [ @_ ] : \@ARGV);
  145.     $self->{offset} = 0; # its existence will denote that this method has been called
  146.  
  147.     my @option = ();
  148.  
  149.     while ($self->{offset} < @{$self->{argv}})
  150.     {
  151.         last if ($self->{argv}->[$self->{offset}] eq '--');
  152.         unless (
  153.             (($self->{argv}->[$self->{offset}] =~ /^-{1,2}(\w+)$/)  && (@option = $1)) ||
  154.             (($self->{argv}->[$self->{offset}] =~ /^--(\w+)=(.*)$/) && (@option = ($1, $2))))
  155.         {
  156.             ++$self->{offset};
  157.             next;
  158.         }
  159.  
  160.         next if (!exists($Method{$option[0]}) && ++$self->{offset});
  161.  
  162.         $option[0] = $Method{$option[0]} if exists($Method{$Method{$option[0]}});
  163.  
  164.         my $method = $Method{$option[0]};
  165.  
  166.         if (@option > 1) # replace --<option>=<value> with <value>
  167.         {
  168.             $self->{argv}->[$self->{offset}] = $option[1];
  169.         }
  170.         else # remove the argument
  171.         {
  172.             splice(@{$self->{argv}}, $self->{offset}, 1);
  173.         }
  174.  
  175.         $self->$method(('-' . $option[0]), $option[0]);
  176.     }
  177.  
  178.     $self->{config}->{-class} ||= ucfirst($self->{config}->{-name});
  179.  
  180.     delete($self->{argv}); # no longer needed
  181.  
  182.     return $self;
  183. }
  184.  
  185. use vars qw(&process); *process = \&SetArguments; # alias to keep old code happy
  186.  
  187. #/----------------------------------------------------------------------------//
  188. #/ Get a list of the arguments that have been processed by SetArguments().
  189. #/   Returns an array.
  190. #/----------------------------------------------------------------------------//
  191.  
  192. sub GetArguments # Tk::CmdLine::GetArguments()
  193. {
  194.     my $self = (@_ # define the object as necessary
  195.         ? ((ref($_[0]) eq __PACKAGE__)
  196.             ? shift(@_)
  197.             : (($_[0] eq __PACKAGE__) ? shift(@_) : 1) && ($OBJECT ||= __PACKAGE__->new()))
  198.         : ($OBJECT ||= __PACKAGE__->new()));
  199.     $OBJECT = $self; # update the current object
  200.  
  201.     $self->SetArguments() unless exists($self->{offset}); # set arguments if not yet done
  202.  
  203.     return @{$self->{command}};
  204. }
  205.  
  206. #/----------------------------------------------------------------------------//
  207. #/ Get the value of a configuration option (default: -class).
  208. #/   Returns the option value.
  209. #/----------------------------------------------------------------------------//
  210.  
  211. sub cget # Tk::CmdLine::cget([$option])
  212. {
  213.     my $self = (@_ # define the object as necessary
  214.         ? ((ref($_[0]) eq __PACKAGE__)
  215.             ? shift(@_)
  216.             : (($_[0] eq __PACKAGE__) ? shift(@_) : 1) && ($OBJECT ||= __PACKAGE__->new()))
  217.         : ($OBJECT ||= __PACKAGE__->new()));
  218.     $OBJECT = $self; # update the current object
  219.     my $option = shift(@_) || '-class';
  220.  
  221.     $self->SetArguments() unless exists($self->{offset}); # set arguments if not yet done
  222.  
  223.     return (exists($self->{config}->{$option}) ? $self->{config}->{$option} : undef);
  224. }
  225.  
  226. #/----------------------------------------------------------------------------//
  227.  
  228. sub CreateArgs # Tk::CmdLine::CreateArgs()
  229. {
  230.     my $self = (@_ # define the object as necessary
  231.         ? ((ref($_[0]) eq __PACKAGE__)
  232.             ? shift(@_)
  233.             : (($_[0] eq __PACKAGE__) ? shift(@_) : 1) && ($OBJECT ||= __PACKAGE__->new()))
  234.         : ($OBJECT ||= __PACKAGE__->new()));
  235.     $OBJECT = $self; # update the current object
  236.  
  237.     $self->SetArguments() unless exists($self->{offset}); # set arguments if not yet done
  238.  
  239.     return $self->{config};
  240. }
  241.  
  242. #/----------------------------------------------------------------------------//
  243.  
  244. sub Tk::MainWindow::apply_command_line
  245. {
  246.     my $mw = shift(@_);
  247.  
  248.     my $self = ($OBJECT ||= __PACKAGE__->new());
  249.  
  250.     $self->SetArguments() unless exists($self->{offset}); # set arguments if not yet done
  251.  
  252.     foreach my $priority (keys(%{$self->{resources}}))
  253.     {
  254.         foreach my $resource (@{$self->{resources}->{$priority}})
  255.         {
  256.             $mw->optionAdd(@{$resource}, $priority);
  257.         }
  258.     }
  259.  
  260.     foreach my $key (keys(%{$self->{options}}))
  261.     {
  262.         $mw->optionAdd($key => $self->{options}->{$key}, 'interactive');
  263.     }
  264.  
  265.     foreach my $key (keys(%{$self->{methods}}))
  266.     {
  267.         $mw->$key($self->{methods}->{$key});
  268.     }
  269.  
  270.     if ($self->{methods}->{geometry})
  271.     {
  272.         if ($self->{methods}->{geometry} =~ /[+-]\d+[+-]\d+/)
  273.         {
  274.             $mw->positionfrom('user');
  275.         }
  276.         if ($self->{methods}->{geometry} =~ /\d+x\d+/)
  277.         {
  278.             $mw->sizefrom('user');
  279.         }
  280.         delete $self->{methods}->{geometry}; # XXX needed?
  281.     }
  282.  
  283.     $mw->Synchronize() if $self->{synchronous};
  284.  
  285.     if ($self->{iconic})
  286.     {
  287.         $mw->iconify();
  288.         $self->{iconic} = 0;
  289.     }
  290.  
  291.     $Tk::strictMotif = ($self->{motif} || 0);
  292.  
  293.     # Both these are needed to reliably save state
  294.     # but 'hostname' is tricky to do portably.
  295.     # $mw->client(hostname());
  296.     $mw->protocol('WM_SAVE_YOURSELF' => ['WMSaveYourself',$mw]);
  297.     $mw->command([ $self->{name}, @{$self->{command}} ]);
  298. }
  299.  
  300. #/----------------------------------------------------------------------------//
  301. #/ Set the initial resources.
  302. #/   Returns the object reference.
  303. #/----------------------------------------------------------------------------//
  304.  
  305. sub SetResources # Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])
  306. {
  307.     my $self = (@_ # define the object as necessary
  308.         ? ((ref($_[0]) eq __PACKAGE__)
  309.             ? shift(@_)
  310.             : (($_[0] eq __PACKAGE__) ? shift(@_) : 1) && ($OBJECT ||= __PACKAGE__->new()))
  311.         : ($OBJECT ||= __PACKAGE__->new()));
  312.     $OBJECT = $self; # update the current object
  313.  
  314.     $self->SetArguments() unless exists($self->{offset}); # set arguments if not yet done
  315.     return $self unless @_;
  316.  
  317.     my $data      = shift(@_);
  318.     my $priority  = shift(@_) || 'userDefault';
  319.  
  320.     $self->{resources}->{$priority} = [] unless exists($self->{resources}->{$priority});
  321.  
  322.     foreach my $resource ((ref($data) eq 'ARRAY') ? @{$data} : $data)
  323.     {
  324.         if (ref($resource) eq 'ARRAY') # resources in [ <pattern>, <value> ] format
  325.         {
  326.             push(@{$self->{resources}->{$priority}}, [ @{$resource} ])
  327.                 if (@{$resource} == 2);
  328.         }
  329.         else # resources in resource file format
  330.         {
  331.             push(@{$self->{resources}->{$priority}}, [ $1, $2 ])
  332.                 if ($resource =~ /^([^!:\s]+)*\s*:\s*(.*)$/);
  333.         }
  334.     }
  335.  
  336.     return $self;
  337. }
  338.  
  339. #/----------------------------------------------------------------------------//
  340. #/ Load initial resources from one or more files (default: $XFILESEARCHPATH with
  341. #/ priority 'startupFile' and $XUSERFILESEARCHPATH with priority 'userDefault').
  342. #/   Returns the object reference.
  343. #/----------------------------------------------------------------------------//
  344.  
  345. sub LoadResources # Tk::CmdLine::LoadResources([%options])
  346. {
  347.     my $self = (@_ # define the object as necessary
  348.         ? ((ref($_[0]) eq __PACKAGE__)
  349.             ? shift(@_)
  350.             : (($_[0] eq __PACKAGE__) ? shift(@_) : 1) && ($OBJECT ||= __PACKAGE__->new()))
  351.         : ($OBJECT ||= __PACKAGE__->new()));
  352.     $OBJECT = $self; # update the current object
  353.  
  354.     $self->SetArguments() unless exists($self->{offset}); # set arguments if not yet done
  355.  
  356.     my %options = @_;
  357.  
  358.     my @file = ();
  359.     my $echo = (exists($options{-echo})
  360.         ? (defined($options{-echo}) ? $options{-echo} : \*STDOUT) : undef);
  361.  
  362.     unless (%options && (exists($options{-file}) || exists($options{-symbol})))
  363.     {
  364.         @file = (
  365.             { -symbol => 'XFILESEARCHPATH',     -priority => 'startupFile' },
  366.             { -symbol => 'XUSERFILESEARCHPATH', -priority => 'userDefault' } );
  367.     }
  368.     else
  369.     {
  370.         @file = { %options };
  371.     }
  372.  
  373.     my $delimiter = (($^O eq 'MSWin32') ? ';' : ':');
  374.  
  375.     foreach my $file (@file)
  376.     {
  377.         my $fileSpec = $file->{-spec} = undef;
  378.         if (exists($file->{-symbol}))
  379.         {
  380.             my $xpath = undef;
  381.             if ($file->{-symbol} eq 'XUSERFILESEARCHPATH')
  382.             {
  383.                 $file->{-priority} ||= 'userDefault';
  384.                 foreach my $symbol (qw(XUSERFILESEARCHPATH XAPPLRESDIR HOME))
  385.                 {
  386.                     last if (exists($ENV{$symbol}) && ($xpath = $ENV{$symbol}));
  387.                 }
  388.                 next unless defined($xpath);
  389.             }
  390.             else
  391.             {
  392.                 $file->{-priority} ||= (($file->{-symbol} eq 'XFILESEARCHPATH')
  393.                     ? 'startupFile' : 'userDefault');
  394.                 next unless (
  395.                     exists($ENV{$file->{-symbol}}) && ($xpath = $ENV{$file->{-symbol}}));
  396.             }
  397.  
  398.             unless (exists($self->{translation}))
  399.             {
  400.                 $self->{translation} = {
  401.                     '%l' => '',                       # ignored
  402.                     '%C' => '',                       # ignored
  403.                     '%S' => '',                       # ignored
  404.                     '%L' => ($ENV{LANG} || 'C'),      # language
  405.                     '%T' => 'app-defaults',           # type
  406.                     '%N' => $self->{config}->{-class} # filename
  407.                 };
  408.             }
  409.  
  410.             my @postfix = map({ $_ . '/' . $self->{config}->{-class} }
  411.                 ('/' . $self->{translation}->{'%L'}), '');
  412.  
  413.             ITEM: foreach $fileSpec (split($Config{path_sep}, $xpath))
  414.             {
  415.                 if ($fileSpec =~ s/(%[A-Za-z])/$self->{translation}->{$1}/g) # File Pattern
  416.                 {
  417.                     if (defined($echo) && ($file->{-symbol} ne 'XFILESEARCHPATH'))
  418.                     {
  419.                         print $echo 'Checking ', $fileSpec, "\n";
  420.                     }
  421.                     next unless ((-f $fileSpec) && (-r _) && (-s _));
  422.                     $file->{-spec} = $fileSpec;
  423.                     last;
  424.                 }
  425.                 else # Directory - Check for <Directory>/$LANG/<Class>, <Directory>/<CLASS>
  426.                 {
  427.                     foreach my $postfix (@postfix)
  428.                     {
  429.                         my $fileSpec2 = $fileSpec . $postfix;
  430.                         if (defined($echo) && ($file->{-symbol} ne 'XFILESEARCHPATH'))
  431.                         {
  432.                             print $echo 'Checking ', $fileSpec2, "\n";
  433.                         }
  434.                         next unless ((-f $fileSpec2) && (-r _) && (-s _));
  435.                         $file->{-spec} = $fileSpec2;
  436.                         last ITEM;
  437.                     }
  438.                 }
  439.             }
  440.         }
  441.         elsif (exists($file->{-file}) && ($fileSpec = $file->{-file}))
  442.         {
  443.             print $echo 'Checking ', $fileSpec, "\n" if defined($echo);
  444.             next unless ((-f $fileSpec) && (-r _) && (-s _));
  445.             $file->{-spec} = $fileSpec;
  446.         }
  447.     }
  448.  
  449.     foreach my $file (@file)
  450.     {
  451.         next unless defined($file->{-spec});
  452.         local *SPEC;
  453.         next unless open(SPEC,$file->{-spec});
  454.         print $echo ' Loading ', $file->{-spec}, "\n" if defined($echo);
  455.  
  456.         my $resource     = undef;
  457.         my @resource     = ();
  458.         my $continuation = 0;
  459.  
  460.         while (defined(my $line = <SPEC>))
  461.         {
  462.             chomp($line);
  463.             next if ($line =~ /^\s*$/); # skip blank lines
  464.             next if ($line =~ /^\s*!/); # skip comments
  465.             $continuation = ($line =~ s/\s*\\$/ /); # search for trailing backslash
  466.             unless (defined($resource)) # it is the first line
  467.             {
  468.                 $resource = $line;
  469.             }
  470.             else # it is a continuation line
  471.             {
  472.                 $line =~ s/^\s*//; # remove leading whitespace
  473.                 $resource .= $line;
  474.             }
  475.             next if $continuation;
  476.             push(@resource, [ $1, $2 ]) if ($resource =~ /^([^:\s]+)*\s*:\s*(.*)$/);
  477.             $resource = undef;
  478.         }
  479.  
  480.         close(SPEC);
  481.  
  482.         if (defined($resource)) # special case - EOF after line with trailing backslash
  483.         {
  484.             push(@resource, [ $1, $2 ]) if ($resource =~ /^([^:\s]+)*\s*:\s*(.*)$/);
  485.         }
  486.  
  487.         $self->SetResources(\@resource, $file->{-priority}) if @resource;
  488.     }
  489.  
  490.     return $self;
  491. }
  492.  
  493. #/----------------------------------------------------------------------------//
  494.  
  495. 1;
  496.  
  497. __END__
  498.  
  499. =cut
  500.  
  501. =head1 NAME
  502.  
  503. Tk::CmdLine - Process standard X11 command line options and set initial resources
  504.  
  505. =for pm Tk/CmdLine.pm
  506.  
  507. =for category Creating and Configuring Widgets
  508.  
  509. =head1 SYNOPSIS
  510.  
  511.   Tk::CmdLine::SetArguments([@argument]);
  512.  
  513.   my $value = Tk::CmdLine::cget([$option]);
  514.  
  515.   Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]);
  516.  
  517.   Tk::CmdLine::LoadResources(
  518.       [ -symbol   => $symbol     ]
  519.       [ -file     => $fileSpec   ]
  520.       [ -priority => $priority   ]
  521.       [ -echo     => $fileHandle ] );
  522.  
  523. =head1 DESCRIPTION
  524.  
  525. Process standard X11 command line options and set initial resources.
  526.  
  527. The X11R5 man page for X11 says: "Most X programs attempt to use the same names
  528. for command line options and arguments. All applications written with the
  529. X Toolkit Intrinsics automatically accept the following options: ...".
  530. This module processes these command line options for perl/Tk applications
  531. using the C<SetArguments>() function.
  532.  
  533. This module can optionally be used to load initial resources explicitly via
  534. function C<SetResources>(), or from specified files (default: the standard X11
  535. application-specific resource files) via function C<LoadResources>().
  536.  
  537. =head2 Command Line Options
  538.  
  539. =over 4
  540.  
  541. =item B<-background> I<Color> | B<-bg> I<Color>
  542.  
  543. Specifies the color to be used for the window background.
  544.  
  545. =item B<-class> I<Class>
  546.  
  547. Specifies the class under which resources for the application should be found.
  548. This option is useful in shell aliases to distinguish between invocations
  549. of an application, without resorting to creating links to alter the executable
  550. file name.
  551.  
  552. =item B<-display> I<Display> | B<-screen> I<Display>
  553.  
  554. Specifies the name of the X server to be used.
  555.  
  556. =item B<-font> I<Font> | B<-fn> I<Font>
  557.  
  558. Specifies the font to be used for displaying text.
  559.  
  560. =item B<-foreground> I<Color> | B<-fg> I<Color>
  561.  
  562. Specifies the color to be used for text or graphics.
  563.  
  564. =item B<-geometry> I<Geometry>
  565.  
  566. Specifies the initial size and location of the I<first>
  567. L<MainWindow|Tk::MainWindow>.
  568.  
  569. =item B<-iconic>
  570.  
  571. Indicates that the user would prefer that the application's windows initially
  572. not be visible as if the windows had been immediately iconified by the user.
  573. Window managers may choose not to honor the application's request.
  574.  
  575. =item B<-motif>
  576.  
  577. Specifies that the application should adhere as closely as possible to Motif
  578. look-and-feel standards. For example, active elements such as buttons and
  579. scrollbar sliders will not change color when the pointer passes over them.
  580.  
  581. =item B<-name> I<Name>
  582.  
  583. Specifies the name under which resources for the application should be found.
  584. This option is useful in shell aliases to distinguish between invocations
  585. of an application, without resorting to creating links to alter the executable
  586. file name.
  587.  
  588. =item B<-synchronous>
  589.  
  590. Indicates that requests to the X server should be sent synchronously, instead of
  591. asynchronously. Since Xlib normally buffers requests to the server, errors do
  592. do not necessarily get reported immediately after they occur. This option turns
  593. off the buffering so that the application can be debugged. It should never
  594. be used with a working program.
  595.  
  596. =item B<-title> I<TitleString>
  597.  
  598. This option specifies the title to be used for this window. This information is
  599. sometimes used by a window manager to provide some sort of header identifying
  600. the window.
  601.  
  602. =item B<-xrm> I<ResourceString>
  603.  
  604. Specifies a resource pattern and value to override any defaults. It is also
  605. very useful for setting resources that do not have explicit command line
  606. arguments.
  607.  
  608. The I<ResourceString> is of the form E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>,
  609. that is (the first) ':' is used to determine which part is pattern and which
  610. part is value. The (E<lt>I<pattern>E<gt>, E<lt>I<value>E<gt>) pair is entered
  611. into the options database with B<optionAdd> (for each
  612. L<MainWindow|Tk::MainWindow> configured), with I<interactive> priority.
  613.  
  614. =back
  615.  
  616. =head2 Initial Resources
  617.  
  618. There are several mechanism for initializing the resource database to be used
  619. by an X11 application. Resources may be defined in a $C<HOME>/.Xdefaults file,
  620. a system application defaults file (e.g.
  621. /usr/lib/X11/app-defaults/E<lt>B<CLASS>E<gt>),
  622. or a user application defaults file (e.g. $C<HOME>/E<lt>B<CLASS>E<gt>).
  623. The Tk::CmdLine functionality for setting initial resources concerns itself
  624. with the latter two.
  625.  
  626. Resource files contain data lines of the form
  627. E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>.
  628. They may also contain blank lines and comment lines (denoted
  629. by a ! character as the first non-blank character). Refer to L<option|Tk::option>
  630. for a description of E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>.
  631.  
  632. =over 4
  633.  
  634. =item System Application Defaults Files
  635.  
  636. System application defaults files may be specified via environment variable
  637. $C<XFILESEARCHPATH> which, if set, contains a list of file patterns
  638. (joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>).
  639.  
  640. =item User Application Defaults Files
  641.  
  642. User application defaults files may be specified via environment variables
  643. $C<XUSERFILESEARCHPATH>, $C<XAPPLRESDIR> or $C<HOME>.
  644.  
  645. =back
  646.  
  647. =head1 METHODS
  648.  
  649. =over 4
  650.  
  651. =item B<SetArguments> - Tk::CmdLine::SetArguments([@argument])
  652.  
  653. Extract the X11 options contained in a specified array (@ARGV by default).
  654.  
  655.   Tk::CmdLine::SetArguments([@argument])
  656.  
  657. The X11 options may be specified using a single dash I<-> as per the X11
  658. convention, or using two dashes I<--> as per the POSIX standard (e.g.
  659. B<-geometry> I<100x100>, B<-geometry> I<100x100> or B<-geometry=>I<100x100>).
  660. The options may be interspersed with other options or arguments.
  661. A I<--> by itself terminates option processing.
  662.  
  663. By default, command line options are extracted from @ARGV the first time
  664. a MainWindow is created. The Tk::MainWindow constructor indirectly invokes
  665. C<SetArguments>() to do this.
  666.  
  667. =item B<GetArguments> - Tk::CmdLine::GetArguments()
  668.  
  669. Get a list of the X11 options that have been processed by C<SetArguments>().
  670. (C<GetArguments>() first invokes C<SetArguments>() if it has not already been invoked.)
  671.  
  672. =item B<cget> - Tk::CmdLine::cget([$option])
  673.  
  674. Get the value of a configuration option specified via C<SetArguments>().
  675. (C<cget>() first invokes C<SetArguments>() if it has not already been invoked.)
  676.  
  677.   Tk::CmdLine::cget([$option])
  678.  
  679. The valid options are: B<-class>, B<-name>, B<-screen> and B<-title>.
  680. If no option is specified, B<-class> is implied.
  681.  
  682. A typical use of C<cget>() might be to obtain the application class in order
  683. to define the name of a resource file to be loaded in via C<LoadResources>().
  684.  
  685.   my $class = Tk::CmdLine::cget(); # process command line and return class
  686.  
  687. =item B<SetResources> - Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])
  688.  
  689. Set the initial resources.
  690.  
  691.   Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])
  692.  
  693. A single resource may be specified using a string of the form
  694. 'E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>'. Multiple resources may be specified
  695. by passing an array reference whose elements are either strings of the above
  696. form, and/or anonymous arrays of the form [ E<lt>I<pattern>E<gt>,
  697. E<lt>I<value>E<gt> ]. The optional second argument specifies the priority,
  698. as defined in L<option|Tk::option>, to be associated with the resources
  699. (default: I<userDefault>).
  700.  
  701. Note that C<SetResources>() first invokes C<SetArguments>() if it has not already
  702. been invoked.
  703.  
  704. =item B<LoadResources> - Tk::CmdLine::LoadResources([%options])
  705.  
  706. Load initial resources from one or more files.
  707.  
  708.   Tk::CmdLine::LoadResources(
  709.       [ -symbol   => $symbol     ]
  710.       [ -file     => $fileSpec   ]
  711.       [ -priority => $priority   ]
  712.       [ -echo     => $fileHandle ] );
  713.  
  714. [ B<-symbol> =E<gt> $symbol ] specifies the name of an environment variable
  715. that, if set, defines a list of one or more directories and/or file patterns
  716. (joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>).
  717. $C<XUSERFILESEARCHPATH> is a special case.
  718. If $C<XUSERFILESEARCHPATH> is not set, $C<XAPPLRESDIR> is checked instead.
  719. If $C<XAPPLRESDIR> is not set, $C<HOME> is checked instead.
  720.  
  721. An item is identified as a file pattern if it contains one or more /%[A-Za-z]/
  722. patterns. Only patterns B<%L>, B<%T> and B<%N> are currently recognized. All
  723. others are replaced with the null string. Pattern B<%L> is translated into
  724. $C<LANG>. Pattern B<%T> is translated into I<app-defaults>. Pattern B<%N> is
  725. translated into the application class name.
  726.  
  727. Each file pattern, after substitutions are applied, is assumed to define a
  728. FileSpec to be examined.
  729.  
  730. When a directory is specified, FileSpecs
  731. E<lt>B<DIRECTORY>E<gt>/E<lt>B<LANG>E<gt>/E<lt>B<CLASS>E<gt>
  732. and E<lt>B<DIRECTORY>E<gt>/E<lt>B<CLASS>E<gt> are defined, in that order.
  733.  
  734. [ B<-file> =E<gt> $fileSpec ] specifies a resource file to be loaded in.
  735. The file is silently skipped if if does not exist, or if it is not readable.
  736.  
  737. [ B<-priority> =E<gt> $priority ] specifies the priority, as defined in
  738. L<option|Tk::option>, to be associated with the resources
  739. (default: I<userDefault>).
  740.  
  741. [ B<-echo> =E<gt> $fileHandle ] may be used to specify that a line should be
  742. printed to the corresponding FileHandle (default: \*STDOUT) everytime a file
  743. is examined / loaded.
  744.  
  745. If no B<-symbol> or B<-file> options are specified, C<LoadResources>()
  746. processes symbol $C<XFILESEARCHPATH> with priority I<startupFile> and
  747. $C<XUSERFILESEARCHPATH> with priority I<userDefault>.
  748. (Note that $C<XFILESEARCHPATH> and $C<XUSERFILESEARCHPATH> are supposed to
  749. contain only patterns. $C<XAPPLRESDIR> and $C<HOME> are supposed to be a single
  750. directory. C<LoadResources>() does not check/care whether this is the case.)
  751.  
  752. For each set of FileSpecs, C<LoadResources>() examines each FileSpec to
  753. determine if the file exists and is readable. The first file that meets this
  754. criteria is read in and C<SetResources>() is invoked.
  755.  
  756. Note that C<LoadResources>() first invokes C<SetArguments>() if it has not already
  757. been invoked.
  758.  
  759. =back
  760.  
  761. =head1 NOTES
  762.  
  763. This module is an object-oriented module whose methods can be invoked as object
  764. methods, class methods or regular functions. This is accomplished via an
  765. internally-maintained object reference which is created as necessary, and which
  766. always points to the last object used. C<SetArguments>(), C<SetResources>() and
  767. C<LoadResources>() return the object reference.
  768.  
  769. =head1 EXAMPLES
  770.  
  771. =over
  772.  
  773. =item 1
  774.  
  775. @ARGV is processed by Tk::CmdLine at MainWindow creation.
  776.  
  777.   use Tk;
  778.  
  779.   # <Process @ARGV - ignoring all X11-specific options>
  780.  
  781.   my $mw = MainWindow->new();
  782.  
  783.   MainLoop();
  784.  
  785. =item 2
  786.  
  787. @ARGV is processed by Tk::CmdLine before MainWindow creation.
  788. An @ARGV of (--geometry=100x100 -opt1 a b c -bg red)
  789. is equal to (-opt1 a b c) after C<SetArguments>() is invoked.
  790.  
  791.   use Tk;
  792.  
  793.   Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too
  794.  
  795.   # <Process @ARGV - not worrying about X11-specific options>
  796.  
  797.   my $mw = MainWindow->new();
  798.  
  799.   MainLoop();
  800.  
  801. =item 3
  802.  
  803. Just like 2) except that default arguments are loaded first.
  804.  
  805.   use Tk;
  806.  
  807.   Tk::CmdLine::SetArguments(qw(-name test -iconic));
  808.   Tk::CmdLine::SetArguments();
  809.  
  810.   # <Process @ARGV - not worrying about X11-specific options>
  811.  
  812.   my $mw = MainWindow->new();
  813.  
  814.   MainLoop();
  815.  
  816. =item 4
  817.  
  818. @ARGV is processed by Tk::CmdLine before MainWindow creation.
  819. Standard resource files are loaded in before MainWindow creation.
  820.  
  821.   use Tk;
  822.  
  823.   Tk::CmdLine::SetArguments();
  824.  
  825.   # <Process @ARGV - not worrying about X11-specific options>
  826.  
  827.   Tk::CmdLine::LoadResources();
  828.  
  829.   my $mw = MainWindow->new();
  830.  
  831.   MainLoop();
  832.  
  833. =item 5
  834.  
  835. @ARGV is processed by Tk::CmdLine before MainWindow creation.
  836. Standard resource files are loaded in before MainWindow creation
  837. using non-default priorities.
  838.  
  839.   use Tk;
  840.  
  841.   Tk::CmdLine::SetArguments();
  842.  
  843.   # <Process @ARGV - not worrying about X11-specific options>
  844.  
  845.   Tk::CmdLine::LoadResources(-echo => \*STDOUT,
  846.       -priority => 65, -symbol => 'XFILESEARCHPATH' );
  847.   Tk::CmdLine::LoadResources(-echo => \*STDOUT,
  848.       -priority => 75, -symbol => 'XUSERFILESEARCHPATH' );
  849.  
  850.   my $mw = MainWindow->new();
  851.  
  852.   MainLoop();
  853.  
  854. =item 6
  855.  
  856. @ARGV is processed by Tk::CmdLine before MainWindow creation.
  857. Standard resource files are loaded in before MainWindow creation.
  858. Individual resources are also loaded in before MainWindow creation.
  859.  
  860.   use Tk;
  861.  
  862.   Tk::CmdLine::SetArguments();
  863.  
  864.   # <Process @ARGV - not worrying about X11-specific options>
  865.  
  866.   Tk::CmdLine::LoadResources();
  867.  
  868.   Tk::CmdLine::SetResources( # set a single resource
  869.       '*Button*background: red',
  870.       'widgetDefault' );
  871.  
  872.   Tk::CmdLine::SetResources( # set multiple resources
  873.       [ '*Button*background: red', '*Button*foreground: blue' ],
  874.       'widgetDefault' );
  875.  
  876.   my $mw = MainWindow->new();
  877.  
  878.   MainLoop();
  879.  
  880. =back
  881.  
  882. =head1 ENVIRONMENT
  883.  
  884. =over 4
  885.  
  886. =item B<HOME> (optional)
  887.  
  888. Home directory which may contain user application defaults files as
  889. $C<HOME>/$C<LANG>/E<lt>B<CLASS>E<gt> or $C<HOME>/E<lt>B<CLASS>E<gt>.
  890.  
  891. =item B<LANG> (optional)
  892.  
  893. The current language (default: I<C>).
  894.  
  895. =item B<XFILESEARCHPATH> (optional)
  896.  
  897. List of FileSpec patterns
  898. (joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>)
  899. used in defining system application defaults files.
  900.  
  901. =item B<XUSERFILESEARCHPATH> (optional)
  902.  
  903. List of FileSpec patterns
  904. (joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>)
  905. used in defining user application defaults files.
  906.  
  907. =item B<XAPPLRESDIR> (optional)
  908.  
  909. Directory containing user application defaults files as
  910. $C<XAPPLRESDIR>/$C<LANG>/E<lt>B<CLASS>E<gt> or
  911. $C<XAPPLRESDIR>/E<lt>B<CLASS>E<gt>.
  912.  
  913. =back
  914.  
  915. =head1 SEE ALSO
  916.  
  917. L<MainWindow|Tk::MainWindow>
  918. L<option|Tk::option>
  919.  
  920. =head1 HISTORY
  921.  
  922. =over 4
  923.  
  924. =item *
  925.  
  926. 1999.03.04 Ben Pavon E<lt>ben.pavon@hsc.hac.comE<gt>
  927.  
  928. Rewritten as an object-oriented module.
  929.  
  930. Allow one to process command line options in a specified array (@ARGV by default).
  931. Eliminate restrictions on the format and location of the options within the array
  932. (previously the X11 options could not be specified in POSIX format and had to be
  933. at the beginning of the array).
  934.  
  935. Added the C<SetResources>() and C<LoadResources>() functions to allow the definition
  936. of resources prior to MainWindow creation.
  937.  
  938. =item *
  939.  
  940. 2000.08.31 Ben Pavon E<lt>ben.pavon@hsc.hac.comE<gt>
  941.  
  942. Added the C<GetArguments>() method which returns the list of arguments that
  943. have been processed by C<SetArguments>().
  944.  
  945. Modified C<LoadResources>() to split the symbols using the OS-dependent
  946. path delimiter defined in the B<Config> module.
  947.  
  948. Modified C<LoadResources>() to eliminate a warning message when processing
  949. patterns B<%l>, B<%C>, B<%S>.
  950.  
  951. =back
  952.  
  953. =cut
  954.  
  955.