modules/FvwmDebug/FvwmDebug.in

   1 #!@PERL@ -w
   2
   3 # Copyright (C) 2002-2009 Mikhael Goikhman <migo@cpan.org>
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program; if not, write to the Free Software
  17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18
  19 # Filter this script to pod2man to get a man page:
  20 #   pod2man -c "Fvwm Module" FvwmDebug | nroff -man | less -e
  21
  22 require 5.003;
  23 use strict;
  24
  25 BEGIN {
  26         use vars qw($prefix $datarootdir $datadir);
  27         $prefix = "@prefix@";
  28         $datarootdir = "@datarootdir@";
  29         $datadir = "@datadir@";
  30 }
  31
  32 use lib "@FVWM_PERLLIBDIR@";
  33 use FVWM::Module;
  34
  35 my $default_mask = MAX_MSG_MASK &
  36         ~(M_FOCUS_CHANGE | M_CONFIGURE_WINDOW | M_VISIBLE_NAME | M_ICON_NAME);
  37 my $default_xmask = MAX_XMSG_MASK &
  38         ~(MX_ENTER_WINDOW | MX_LEAVE_WINDOW | MX_VISIBLE_ICON_NAME);
  39 $default_xmask &= ~M_EXTENDED_MSG;
  40
  41 my $mask  = $default_mask;
  42 my $xmask = $default_xmask;
  43 my $debug = 0;
  44 my $show_args = 1;
  45 my $show_events = undef;
  46 my $log_file = undef;
  47 my $xconsole = 0;
  48 my $log_stream = \*STDERR;
  49 my $send_configinfo = 0;
  50 my $send_windowlist = 0;
  51 my @tracker_names = ();
  52 my @module_args = @ARGV;
  53
  54 my $options = {
  55         'args!'       => \$show_args,
  56         'events!'     => \$show_events,
  57         'l|log=s'     => \$log_file,
  58         'xc|xconsole' => \$xconsole,
  59         'm|mask=i'    => \$mask,
  60         'x|xmask=i'   => \$xmask,
  61         'sc|send-configinfo' => \$send_configinfo,
  62         'sw|send-windowlist' => \$send_windowlist,
  63         'd|debug=i'   => \$debug,
  64         't|track=s'   => \@tracker_names,
  65 };
  66
  67 my $module = new FVWM::Module(
  68         Name  => "FvwmDebug",
  69         Debug => \$debug,
  70         EnableOptions => $options,
  71 );
  72
  73 $show_events = (@tracker_names ? 0 : 1) unless defined $show_events;
  74 $mask  = MAX_MSG_MASK  if $mask  == -1;
  75 $xmask = MAX_XMSG_MASK if $xmask == -1;
  76
  77 $module->debug("argv = '" . join("', '", @module_args) . "'\n");
  78 $module->mask($mask);
  79 $module->xmask($xmask);
  80
  81 #$module->add_handler($mask, \&show_event);
  82 #$module->add_handler($xmask | M_EXTENDED_MSG, \&show_event);
  83 $module->add_handler(MAX_MSG_MASK, \&show_event);
  84 $module->add_handler(MAX_XMSG_MASK | M_EXTENDED_MSG, \&show_event);
  85
  86 $module->add_handler(ON_EXIT, sub { system("killall xconsole"); }) if $xconsole;
  87 $log_file = '|xconsole -file /dev/stdin -geometry 600x400 -notify' if $xconsole;
  88
  89 if ($log_file) {
  90         # let's hope the system will close it automatically on exit
  91         my $prefix = $log_file =~ /^\s*\|/ ? "" : ">";
  92         open $log_stream, "$prefix$log_file";
  93 }
  94
  95 foreach my $name (@tracker_names) {
  96         my $tracker = $module->track($name);
  97         $module->debug(
  98                 "$name: initialized\n" . $tracker->dump . ("-" x 74), 0
  99         );
 100         $tracker->observe("main", sub {
 101                 my ($module, $tracker, $info, @params) = @_;
 102                 my $headline = "$name: " . $tracker->observables->[0];
 103                 $module->debug(
 104                         "$headline\n" . $tracker->dump(@params) . ("-" x 74), 0
 105                 );
 106         });
 107 }
 108
 109 $module->send("Send_ConfigInfo") if $send_configinfo;
 110 $module->send("Send_WindowList") if $send_windowlist;
 111
 112 $module->event_loop;
 113
 114 sub show_event ($$) {
 115         return unless $show_events;
 116         my ($module, $event) = @_;
 117
 118         unless ($show_args) {
 119                 print $log_stream $event->name, "\n";
 120                 return;
 121         }
 122         print $log_stream $event->dump;
 123 }
 124
 125 __END__
 126
 127 # ----------------------------------------------------------------------------
 128 # man page
 129
 130 =head1 NAME
 131
 132 FvwmDebug - the fvwm module debugger
 133
 134 =head1 SYNOPSIS
 135
 136 FvwmDebug should be spawned by fvwm(1) for normal functionality.
 137
 138 To run this module, place this command somewhere in the configuration:
 139
 140     Module FvwmDebug [optional-params]
 141
 142 To stop this module, execute:
 143
 144     KillModule FvwmDebug
 145
 146 =head1 DESCRIPTION
 147
 148 This module persistently dumps all fvwm event details and optionally some
 149 other information into the standard error stream or a file, good for
 150 debugging purposes. The output may be optionally redirected to I<xconsole>
 151 or similar window.
 152
 153 =head1 INVOCATION
 154
 155 There are several command line switches:
 156
 157 B<FvwmDebug>
 158 [ B<--args>|B<--noargs> ]
 159 [ B<--events>|B<--noevents> ]
 160 [ B<--log> I<file> ]
 161 [ B<--xconsole> ]
 162 [ B<--mask> I<mask> ]
 163 [ B<--xmask> I<mask> ]
 164 [ B<--debug> I<level> ]
 165 [ B<--track> I<tracker-name> ]
 166 [ B<--send-configinfo> ]
 167 [ B<--send-windowlist> ]
 168
 169 Long switches may be abbreviated to shorter switches.
 170
 171 B<--noargs> - do not print all arguments of the event, just its name.
 172 B<--args> is the default.
 173
 174 B<--noevents> - do not print even event names, implies B<--noargs>.
 175 It is similar in effect to setting both B<--mask> and B<--xmask> to 0,
 176 but the events are actually received by the module, they are just not printed.
 177
 178 This option may be useful if B<--track> or/and B<--debug> is used.
 179
 180 The default is B<--events> normally, and B<--noevents> if one or more
 181 B<--track> options specified.
 182
 183 B<-l>|B<--log> I<file> - specify the log file name instead of the standard
 184 error stream. If the log file can't be open for writting, the default
 185 standard error stream is used.
 186
 187 The I<file> may start with a pipe '|', this is similar to the usual meaning
 188 of a pipe, the output is piped to the specified command. See also
 189 B<--xconsole> option.
 190
 191 B<-xc>|B<--xconsole> - this is a shortcut for:
 192
 193     FvwmDebug --log '|xconsole -file /dev/stdin -geometry 600x400 -notify'
 194
 195 That shows the module output in the I<xconsole> window rather than
 196 the standard error stream.
 197
 198 B<-m>|B<--mask> I<mask> - set the module mask, 31 bit integer.
 199 By default almost all events are monitored (except for some flood events
 200 like I<CONFIGURE_WINDOW> or I<FOCUS_WINDOW>. The special value of I<-1>
 201 sets the maximal mask.
 202
 203 B<-x>|B<--xmask> I<mask> - set the module extended mask, 31 bit integer.
 204 By default almost all events are monitored (except for some flood events
 205 like I<ENTER_WINDOW> or I<LEAVE_WINDOW>. The special value of I<-1>
 206 sets the maximal extended mask.
 207
 208 B<-d>|B<--debug> I<level> - use the Perl library debugging mechanism.
 209 The useful I<level>s are 2 to 4.
 210
 211 B<-t>|B<--track> I<tracker-name> - create the given Perl library tracker and
 212 observe its main observable. This option may be specified multiple times.
 213 This options implies B<--noevents> unless explicitely overwritten.
 214 You may optionally try B<--debug>, for example:
 215
 216     FvwmDebug -xc --track PageInfo --track GlobalConfig --debug 3
 217
 218 Run "fvwm-perllib man" to get the names of all existing trackers in your
 219 installed Perl library.
 220
 221 B<-sc>|B<--send-configinfo> - send B<Send_ConfigInfo> command to I<fvwm>
 222 on startup, this results in a lot of events received.
 223
 224 B<-sw>|B<--send-windowlist> - send B<Send_WindowList> command to I<fvwm>
 225 on startup, this results in a lot of events received.
 226
 227 =head1 SEE ALSO
 228
 229 See also L<FvwmGtkDebug>.
 230
 231 =head1 AUTHOR
 232
 233 Mikhael Goikhman <migo@homemail.com>.
 234
 235 =cut