Debian Codegraph @

bin/mvs

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