Debian Codegraph @

bin/mvs

raw ◀ ▶
Source reconstructed at patch state 0 of 5 — not the installed (fully patched) source.
5 Debian patches touch this file
1 #!/usr/bin/perl -w
2
3 use strict;
4 use WWW::Mediawiki::Client;
5 use Getopt::Long ();
6 use Pod::Usage;
7 use Data::Dumper;
8
9 ##############################################################################
10 # Fields #
11 ##############################################################################
12
13 # Options:
14 our (
15 $opt_help, $opt_verbose, $opt_defaults,
16 $opt_host, $opt_lang, $opt_username, $opt_password, $opt_basic_http_authorization,
17 $opt_version, $opt_wiki_path, $opt_space_sub,
18 $opt_message, $opt_watch, $opt_minor, $opt_tls
19 );
20 $opt_verbose = 0;
21
22 # Multi-state options:
23 use constant OPTION_STATES => (
24 yes => WWW::Mediawiki::Client->OPT_YES,
25 no => WWW::Mediawiki::Client->OPT_NO,
26 keep => WWW::Mediawiki::Client->OPT_KEEP,
27 default => WWW::Mediawiki::Client->OPT_DEFAULT,
28 );
29
30 our $VERSION = $WWW::Mediawiki::Client::VERSION;
31
32 my $LOGFILE = '.mediawiki.errors';
33
34 ##############################################################################
35 # Subroutines #
36 ##############################################################################
37
38 sub print_defaults {
39 my $DEFAULTS = WWW::Mediawiki::Client->DEFAULTS;
40 for my $host (keys %$DEFAULTS) {
41 print "Hostname: $host\n";
42 for my $field (keys %{$DEFAULTS->{$host}}) {
43 print " $field: " . $DEFAULTS->{$host}->{$field} . "\n";
44 }
45 print "\n";
46 }
47 exit 1;
48 }
49
50 sub main {
51 my ($command, @files) = @_;
52 print_defaults if $opt_defaults;
53 version_message() if $opt_version;
54 pod2usage unless $command;
55 my $method= "do_$command";
56 # do help if indicated
57 pod2usage(-verbose => 1) if $opt_help;
58 # create the init array, and maybe pre-populate it
59 my $wmc = WWW::Mediawiki::Client->new();
60 unless ($wmc->can($method)) {
61 print "Command \"$command\" not supported.\n\n";
62 pod2usage(-verbose => 1);
63 }
64 $wmc->host($opt_host) if $opt_host;
65 $wmc->protocol('https') if $opt_tls;
66 $wmc->commit_message($opt_message) if $opt_message;
67 $wmc->language_code($opt_lang) if $opt_lang;
68 $wmc->username($opt_username) if $opt_username;
69 $wmc->password($opt_password) if $opt_password;
70 $wmc->http_authorization_method( 'Basic' ) if $opt_basic_http_authorization;
71 $wmc->space_substitute($opt_space_sub) if $opt_space_sub;
72 $wmc->wiki_path($opt_wiki_path) if $opt_wiki_path;
73 $wmc->minor_edit($opt_minor) if defined($opt_minor);
74 $wmc->watch($opt_watch) if defined($opt_watch);
75 # run command
76 my $message = "Doing $command ";
77 $message .= @files ? join(' ', @files) . ' ' : '';
78 $message .= "with host: "
79 . $wmc->host . " and lang: "
80 . $wmc->language_code . "\n";
81 my $watch = multistate_text($wmc->watch);
82 my $minor = multistate_text($wmc->minor_edit);
83 $message .= " wiki_path: " . $wmc->wiki_path . "\n"
84 . " space_substitute: " . $wmc->space_substitute . "\n"
85 . " watch this page?: $watch\n"
86 . " minor edit?: $minor\n"
87 if $opt_verbose >= 1;
88 print $message unless $opt_verbose <= -1;
89 eval { $wmc->$method(@files) };
90
91 my $tmp_error = $@;
92
93 if (UNIVERSAL::isa($tmp_error, 'WWW::Mediawiki::Client::Exception')) {
94 open (LOG, ">>$LOGFILE");
95 print LOG "\n-----------------\n$tmp_error";
96 warn "\n-----------------\n$tmp_error" if $opt_verbose >= 1;
97
98 if (UNIVERSAL::isa($tmp_error, 'WWW::Mediawiki::Client::LoginException')) {
99 print LOG Data::Dumper->Dump([$tmp_error->res], ['res'] ) . "\n";
100 print LOG Data::Dumper->Dump([$tmp_error->cookie_jar],
101 ['cookie_jar']) . "\n";
102 close LOG;
103 die $tmp_error->error . "See $LOGFILE for details.\n" ;
104 } elsif (UNIVERSAL::isa($tmp_error,
105 'WWW::Mediawiki::Client::CommitException')) {
106 print LOG Data::Dumper->Dump([$tmp_error->res], ['res']) . "\n";
107
108 } elsif (UNIVERSAL::isa($tmp_error,
109 'WWW::Mediawiki::Client::ServerPageException')) {
110 print LOG Data::Dumper->Dump([$tmp_error->res], ['res']) . "\n";
111 }
112
113 warn $tmp_error->error, "\n", "See $LOGFILE for details.\n";
114
115 } elsif ($tmp_error) {
116 die $tmp_error->error;
117 }
118 return 1 unless $wmc->status;
119 my %status = %{$wmc->status};
120 foreach my $file (keys %status) {
121 print $status{$file} . " $file\n" if $status{$file};
122 }
123 return 1;
124 }
125
126 sub HELP_MESSAGE {
127 pod2usage(-verbose => 1);
128 }
129
130 sub version_message {
131 print "Mediawiki versioning system version $VERSION\n";
132 exit 1;
133 }
134
135 sub parse_command {
136 local @ARGV = @{$_[0]};
137
138 my $command;
139 Getopt::Long::Configure('bundling', 'pass_through');
140 Getopt::Long::GetOptions('<>' => sub {
141 $command = $_[0] unless $command;
142 });
143
144 return $command;
145 }
146
147 sub multistate_map {
148 my @states = @_;
149
150 my %states = OPTION_STATES;
151 my %statemap;
152 foreach my $state (@states) {
153 $statemap{$state} = $states{$state};
154 }
155 return \%statemap;
156 }
157
158 sub multistate_text {
159 my ($value) = @_;
160 return 'not set' unless defined($value);
161
162 my %states = OPTION_STATES;
163 my %reverse = map {$states{$_} => $_} keys %states;
164 return $reverse{$value} if defined($reverse{$value});
165 return 'unknown';
166 }
167
168 sub multistate_option {
169 my ($ref, @states) = @_;
170
171 my $statemap = multistate_map(@states);
172
173 return sub {
174 my ($name, $value) = @_;
175 my $state = $statemap->{lc($value)};
176 die "Unknown setting for $name: $value\n"
177 . "Valid settings: " . join(', ', @states) . "\n"
178 unless defined($state);
179 ${$ref} = $state;
180 };
181 }
182
183 sub parse_options {
184 my $command = shift;
185 local @ARGV = @{$_[0]};
186 $command ||= "";
187 my @addit;
188 @addit = (
189 'host|d=s' => \$opt_host,
190 'use_tls|T' => \$opt_tls,
191 'lang|l=s' => \$opt_lang,
192 'username|u=s' => \$opt_username,
193 'password|p=s' => \$opt_password,
194 'basic_http_authorization|b' => \$opt_basic_http_authorization,
195 'wikipath|w=s' => \$opt_wiki_path,
196 'spaces|S=s' => \$opt_space_sub,
197 ) if $command eq 'login';
198 @addit = (
199 'message|summary|m|s=s' => \$opt_message,
200 'minor=s' => multistate_option(
201 \$opt_minor, qw(yes no default)),
202 'watch=s' => multistate_option(
203 \$opt_watch, qw(yes no default keep)),
204 'M' => sub { $opt_minor = WWW::Mediawiki::Client->OPT_YES },
205 'W' => sub { $opt_watch = WWW::Mediawiki::Client->OPT_YES },
206 ) if $command eq 'commit' or $command eq 'com'
207 or $command eq 'preview';
208
209 Getopt::Long::Configure(
210 'no_ignore_case', 'bundling', 'no_pass_through');
211 Getopt::Long::GetOptions(
212 'verbose|v' => sub { $opt_verbose++ },
213 'quiet|q' => sub { $opt_verbose-- },
214 'help|h' => \$opt_help,
215 'version|V' => \$opt_version,
216 @addit,
217 ) or exit(-1);
218
219 return @ARGV;
220 }
221
222 # parse command line
223 my $command = parse_command(\@ARGV);
224 my @args = parse_options($command, \@ARGV);
225 main (@args);
226
227 __END__
228
229 =head1 NAME
230
231 mvs - A command line Mediawiki client
232
233 =head1 SYNOPSIS
234
235 mvs [Options] command [Options] [filename]
236
237 mvs -h|--help
238 mvs --version
239 mvs -D
240
241 mkdir wikistuff
242 cd wikistuff
243
244 mvs login [-q|-v] [-T] [-d <wikihost>] [-l language_code ] [-u <username>] [-p <password> ] [-b] [-w <wiki_path>]
245
246 mvs update [-q|-v] [<file> ..]
247 mvs up [[-q|-v] <file> ..]
248
249 mvs commit [-q|-v] [-M] [-W] -m "commit message" <file>
250 mvs com [-q|-v] [-M] [-W] -m "commit message" <file>
251 mvs preview [-q|-v] [-M] [-W] [-m "commit message"] <file>
252
253 =head1 DESCRIPTION
254
255 C<mvs> is a command line client whose purpose is to simplify offline
256 editing of Wiki content. It allows you to get any number of pages from a
257 given Mediawiki site, edit the pages with any editor, get and merge any
258 concurrent updates of the pages, and then safely commit the users own
259 changes back to the version of the page on the server.
260
261 The C<mvs> commands which take a filename argument only accept a single
262 filename as so to avoid taking up too much server bandwidth.
263
264 B<Note:>Users of C<mvs> from before version 0.27 will notice that in this
265 documentation the options are mostly listed after the C<mvs> sub-command.
266 This makes C<mvs> behave more like C<cvs>, C<svn>, or C<tla>, and so should
267 make it easier for people who are used to using those programs. If you
268 prefer to use C<mvs> the old way, that will still work, at least for the
269 next few versions.
270
271 =head1 QUICKSTART
272
273 =head2 Step 1: Create an account on the Mediawiki server.
274
275 This should be done the normal way, by visiting the Mediawiki website to
276 which you want to contribute and creating a new account, setting the
277 preferences, etc.
278
279 It should hopefully go without saying that you will want to become familiar
280 with the editorial, usage, and copyright guidelines of the site. You
281 should probably also make some contributions through the normal UI, and
282 learn about following recent changes before contributing using mvs.
283
284 In addition for the sake of this test you should already have a user page
285 like User:<username> with something on it, where <username> is the user
286 name with which you established the account.
287
288 =head2 Step 2: Create a working directory
289
290 C<mvs> works with Mediawiki formatted files with a C<.wiki> extension and
291 which are stored together with server information in a I<working directory>.
292 You will have to have I<at least> one working directory for each Mediawiki
293 site to which you contribute.
294
295 Simply use C<mkdir> or the equivalent to make a new directory, and then
296 before cd into that directory.
297
298 mkdir wikitravel.en
299 cd wikitravel.en
300
301 All of the operations below should be done from this directory.
302
303 =head2 Step 3: Login using C<mvs login>
304
305 To use login you will need to know the I<host>name for the Mediawiki site
306 to which you want to contribute.
307
308 www.wikitravel.org
309
310 Now use the I<host> with your username and password to login.
311
312 mvs login -d www.wikitravel.org -u <username> -p 'secret'
313
314 If C<mvs> knows about your Mediawiki host it will set set the
315 C<wiki_path> to the correct default for that server. In this case it will
316 also be able to select the language version of that Wiki for you if you
317 specify a C<language_code>:
318
319 mvs login -d www.wikitravel.org -l fr -u <username> -p 'secret'
320
321 The code must match the one which your wiki host uses for a given language,
322 and of course the language version must exist for the given host.
323
324 If the wiki requires Basic HTTP Authentication, use -b.
325
326 If your Mediawiki install uses a nonstandard path to the wiki script you
327 can specify it on login. The path to the wiki script is the part of the
328 URL after the host name, and before the '?':
329
330 mvs login \
331 -d www.wikitravel.org \
332 -u <username> \
333 -p 'secret' \
334 -w 'mw/wiki.phtml'
335
336 You can change the edit and action paths in the created .mediawiki
337 file after successful login accordingly.
338
339 Now anything you submit to the Mediawiki server will be credited to user
340 "<username>".
341
342 B<NOTE:> If you have been using an earlier version of C<mvs> you should
343 probably delete the .mediawiki file in your working directory.
344
345 =head2 Step 4: Use C<mvs update> to fetch one or more working files
346
347 You can fetch existing material off of the site, or create new pages with
348 C<mvs update>, remembering that your files will need a C<.wiki> extension:
349
350 mvs update User:<username>.wiki User:<username>/Test_Page.wiki
351
352 This should produce the output:
353
354 U User:<username>.wiki
355 A User:<username>/Test_Page.wiki
356
357 The U (for Updated) means that User:<username> was found on the server and
358 its contents inserted into the local files. The A (for Added) means that
359 the User:<username>/Test_Page.wiki page does not yet exist on the server,
360 and will be added when you run C<mvs commit>.
361
362 Note that both of the pages we are working with are within I<your>
363 User Namespace. It's probably a good idea to restrict yourself to working
364 with such pages while you are experimenting with C<mvs>
365
366 =head2 Step 5: Edit the files to make corrections and contributions
367
368 Use your favorite text editor to edit the files. You might want to check
369 out this page to see if there is a Mediawiki syntax highlighting file for
370 your editor:
371
372 http://en.wikipedia.org/wiki/Wikipedia:Syntax_highlighting
373
374 Of course if you don't find a highlighting file for you editor you are
375 welcome to create one and submit it to the page above.
376
377 =head2 Step 6: Use C<mvs commit> to submit your changes
378
379 When you are done editing a file and would like to submit your changes to
380 the wiki server use C<mvs commit> to do so:
381
382 mvs commit -m 'commit message' User:<username>.wiki
383
384 Where 'commit message' is whatever you want to say about the changes you
385 are submitting and why. You must provide a commit message or C<mvs commit>
386 will fail. You might also find that C<mvs commit> fails complaining that
387 the file has changed on the server. If this is the case you will need to
388 use C<mvs update> again to get the most recent changes.
389
390 =head2 Step 7: Update your wiki files
391
392 You can use C<mvs update> again at any time to reconcile any of your files
393 with the most recent changes from the server. Your changes I<will not> be
394 overwritten, but rather C<mvs> will try to merge any server changes into
395 the files as they exist in your working directory. Note that update and
396 commit only work on one file at a time, as so to help prevent accidents and
397 server congestion.
398
399 If for some reason there is a conflict, i.e. you and someone else have made
400 changes which appear to be incompatible, and cannot be resolved then your
401 file will contain a I<conflict message>, as detailed in the documentation
402 for C<mvs update> below. You I<must> resolve any conflicts I<before>
403 attempting to use C<mvs commit> on the file. This is usually a very simple
404 matter of choosing one version of the change or another. You should use
405 your best judgement, consulting the relevant C<Talk:> page to try to work
406 out an agreement with the other contributor in cases where you just simply
407 disagree.
408
409 =head2 Repeat
410
411 You can continue editing and committing changes with the files in your
412 working directory. It might be a good idea for you to eventually create
413 multiple working directories per site, perhaps grouping them by subject.
414 This will work fine with C<mvs> since it does I<not> need to have a
415 complete copy of all of the pages from a given server in a given working
416 directory to work.
417
418 =head1 CHARACTER ENCODING
419
420 All of your C<.wiki> files should be stored with UTF-8 encoding. Upon
421 login to a given server mvs will determine the encoding used by that
422 server, and will upload in that encoding only. For servers using non-UTF-8
423 character sets you should use HTML entities for any character you want to
424 represent which is outside of the server's character set. This includes
425 the english Wikipedia. Most newer Mediawiki sites however do use UTF-8, on
426 these sites HTML entities are I<never> needed.
427
428 =head1 ARGUMENTS
429
430 =head2 Commands
431
432 The first argument after the options should be one of the following two
433 commands:
434
435 =over 4
436
437 =item mvs login
438
439 Allows the user to login to the Mediawiki server using an I<existing> login
440 and password for that server. After calling C<login> all C<commit>s from
441 the same working directory will be logged as from the logged-in user.
442
443 =item mvs update
444
445 Updates the specified file[s] with content from the Mediawiki server. If a
446 file does not exist it is created and populated with the current online
447 version. If there is no online version, the file either created and left
448 blank, or just left as it is. If there is content in both the specified
449 file and in the corresponding Wiki page, an attempt is made to merge the
450 two, line by line. Files which are the same as the server version are
451 ignored.
452
453 If no filenames are given on the command line, all visible files with the
454 .wiki extension are processed.
455
456 Conflicting changes to a given line are detected on the basis of the date
457 of the most recent update of the local file and date of the most recent
458 change to the online Wiki page. If a line has changed in both the online
459 page and the local file it is flagged as a conflict, as in CVS, but with a
460 slightly different syntax:
461
462 ********************Start of conflict 1 Insert to Primary, Insert to Secondary ************************************************************
463
464 The line as it appears on the server
465
466 ****************************************************************************************************
467
468 The line as it appears locally
469 ********************End of conflict 1********************************************************************************
470
471 C<mvs update> reports the status of files which it touches to STDERR with
472 a letter indicating the file status, and then name of the file, again like
473 CVS. The status letters are:
474
475 =over 4
476
477 =item = (Unchanged)
478
479 The file is the same as the page on the server.
480
481 =item A (Added)
482
483 The file will become a new page on the wiki server.
484
485 =item M (Modified)
486
487 The file has been modified locally.
488
489 =item U (Updated)
490
491 The file has been updated with changes from the wiki server.
492
493 =item C (Conflicts)
494
495 The file contains conflict markers.
496
497 =item ? (Unknown)
498
499 Neither the file, nor a corresponding server page exist.
500
501 =back
502
503 =item commit
504
505 Commits any changes in the specified local file to the Wiki site. A check
506 is made first to make sure that there are no changes on the server more
507 recent than the most recent update. Nothing will be comitted if the file
508 and server version are identical.
509
510 When running C<mvs commit> you I<must> use the C<-m> flag to send a commit
511 message to the Mediawiki server. e.g.:
512
513 mvs commit -m 'Added Hotel Eldorado' Paris.wiki
514
515 =item preview
516
517 This command functions identically to C<mvs commit>, except that nothing is
518 actually committed. Instead, the file is uploaded and the Mediawiki server
519 sends back a formatted preview. The C<-m> flag is optional. If you set
520 the L<MVS_BROWSER> environmental variable to the path and filename of your
521 favorite browser, mvs will launch it with the preview page.
522
523 =item clean
524
525 This command removes any local version reference files relating to
526 pages you've deleted.
527
528 rm Paris.wiki
529 mvs clean
530
531 =back
532
533 =head2 File names
534
535 Any additional arguments are taken as I<local> filenames to be processed.
536 The local filename of a given Mediawiki page will be the same as its URL
537 encoded name with the extension ".wiki". If no arguments are given then
538 any filenames with the "wiki" extension and under the current directory are
539 processed.
540
541 =head1 OPTIONS
542
543 =head2 -h
544
545 Display usage information.
546
547 =head2 -D
548
549 Print information about known Mediawiki servers, then exit.
550
551 =head2 -q
552
553 Causes the command to be quiet. Informational messages are suppressed.
554
555 =head2 -u "<username>"
556
557 Specifies a username for C<mvs login>.
558
559 =head2 -p "<password>"
560
561 Specifies a password for C<mvs login>.
562
563 =head2 -l "<language_code>"
564
565 The language code the wiki server uses to differentiate between language
566 versions.
567
568 =head2 -m "<your message>"
569
570 A commit message for C<mvs commit>. Use this to explain the nature of your
571 changes.
572
573 =head2 -s "<your message>"
574
575 Same as C<-m>
576
577 =head2 --minor <yes|no|default>
578
579 Choose whether to mark change as a minor edit. The default is to mark
580 changes as minor if the Mediawiki user profile is set to do so by
581 default. Use this when committing a change with C<mvs commit> or
582 previewing with C<mvs preview>.
583
584 =head2 -M
585
586 Same as C<--minor yes>.
587
588 =head2 --watch <yes|no|keep|default>
589
590 Choose whether to add the edited page to your watchlist. Specifying
591 C<keep> will maintain the current watched status. The default is to
592 watch the page if it is already being watched, or if the Mediawiki
593 user profile is set to do so by default. Use this when committing a
594 change with C<mvs commit> or previewing with C<mvs preview>.
595
596 =head2 -W
597
598 Same as C<--watch yes>.
599
600 =head2 -w "<wiki path>"
601
602 The path on the given C<host> to the Mediawiki script. This defaults to
603 I<wiki/wiki.phtml> which is correct for a vanilla install of Mediawiki
604 1.4.x.
605
606 =head2 -v
607
608 Verbose. If this is set C<mvs> will give you lots of extra information
609 about what it's doing. The -q flag overrides this.
610
611 =head1 ENVIRONMENTAL VARIABLES
612
613 =head2 MVS_BROWSER
614
615 The browser you prefer to use for previewing changes.
616
617 =head2 HTTP_PROXY
618
619 A proxy server to use (if any), expressed as a standard URL, something like
620 this:
621
622 export HTTP_PROXY=http://[username:password@]proxy.myorg.org:8080
623
624 =head1 CAVEATS
625
626 This is an early version of this program. Future versions may have major
627 differences which will effect your ability to use them interchangeably with
628 this one. In particular the initial "command" arguments may become
629 options and the handling of conflicts might change dramatically.
630
631 =head1 BUGS
632
633 Please submit bug reports to the CPAN bug tracker at
634 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Mediawiki-Client>.
635
636 =head1 DISCUSSION
637
638 There is a discussion list. You can subscribe or read the archives at:
639 L<http://www.geekhive.net/cgi-bin/mailman/listinfo/www-mediawiki-client-l>
640
641 =head1 SEE ALSO
642
643 =head2 Mediawiki
644
645 L<http://www.wikimedia.org|Mediawiki>
646
647 =head2 CVS
648
649 L<http://www.cvs.org|The CVS home page>
650
651 =head1 AUTHORS
652
653 =over
654
655 =item Mark Jaroski <[email protected]>
656
657 =item Bernhard Kaindl <[email protected]>
658
659 Improved error and usage messages.
660
661 =item Oleg Alexandrov <[email protected]>, Thomas Widmann <[email protected]>
662
663 Bug reports and feedback.
664
665 =item Adrian Irving-Beer <[email protected]>
666
667 Preview support, export support for multi-page update, more 'minor'
668 and 'watch' settings, and bug reports.
669
670 =back
671
672 =head1 COPYRIGHT
673
674 (C) Copyright 2004-2005, Mark Jaroski
675
676 This program is free software; you can redistribute it and/or modify it
677 under the same terms as Perl itself.
678