Debian Codegraph @

bin/mvs

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