monotone

monotone Mtn Source Tree

Root/lib/Monotone/AutomateStdio.pod

1=pod
2
3=head1 NAME
4
5Monotone::AutomateStdio - Perl interface to Monotone via automate stdio
6
7=head1 VERSION
8
90.08
10
11=head1 SYNOPSIS
12
13 use Monotone::AutomateStdio qw(:capabilities :severities);
14 my(@manifest,
15 $mtn,
16 @revs);
17 $mtn = Monotone::AutomateStdio->new("/home/fred/venge.mtn");
18 $mtn->select(\@revs, "h:net.venge.monotone");
19 $mtn->get_manifest_of(\@manifest, $revs[0])
20 or die("mtn: " . $mtn->get_error_message());
21
22=head1 DESCRIPTION
23
24The Monotone::AutomateStdio class gives a Perl developer access to Monotone's
25automate stdio facility via an easy to use interface. All command, option and
26output formats are handled internally by this class. Any structured information
27returned by Monotone is parsed and returned back to the caller as lists of
28records for ease of access (detailed below). One also has the option of
29accessing Monotone's output as one large string should you prefer.
30
31The mtn automate stdio subprocess is also controlled by this class. A new
32subprocess is started, if necessary, when anything that requires it is
33called. The subprocess is terminated on object destruction or when
34$mtn-E<gt>closedown() is called.
35
36All automate commands have been implemented in this class except for the
37`stdio' command, hopefully the reason is obvious :-). Versions of Monotone that
38are supported by this class range from 0.35 up to and including the latest
39version (currently 0.48). If you happen to be using a newer version of Monotone
40then this class will hopefully largely work but without the support for new or
41changed features.
42
43=head1 CONSTRUCTORS
44
45=over 4
46
47=item B<$mtn = Monotone::AutomateStdio-E<gt>new([\@options])>
48
49Creates a new Monotone::AutomateStdio object, using the current workspace's
50database.
51
52=item B<$mtn = Monotone::AutomateStdio-E<gt>new_from_db($db[, \@options])>
53
54Creates a new Monotone::AutomateStdio object, using the database named in $db.
55
56=item B<$mtn = Monotone::AutomateStdio-E<gt>new_from_service($service,
57[\@options])>
58
59Creates a new Monotone::AutomateStdio object, using the named network service
60(which is expressed as a hostname optionally followed by a colon and a port
61number).
62
63(feature: MTN_REMOTE_CONNECTIONS)
64
65=item B<$mtn = Monotone::AutomateStdio-E<gt>new_from_ws($ws[, \@options])>
66
67Creates a new Monotone::AutomateStdio object, using the workspace named in $ws.
68
69=back
70
71Please note that Monotone::AutomateStdio-E<gt>new() is simply an alias for
72Monotone::AutomateStdio-E<gt>new_from_db().
73
74The @options parameter specifies what options are to be passed to the mtn
75subprocess. The currently supported list (in vaguely the format in which it
76would be passed to the constructor) is:
77
78 ["--confdir" => <Directory>,
79 "--key" => <Key To Be Used For Signatures>,
80 "--keydir" => <Key Store Location>,
81 "--no-default-confdir",
82 "--no-workspace",
83 "--norc",
84 "--nostd",
85 "--root" => <Root Directory>,
86 "--ssh-sign" => One of "check", "no" or "yes"]
87
88=head1 CLASS METHODS
89
90=over 4
91
92=item B<Monotone::AutomateStdio-E<gt>register_db_locked_handler([$handler[,
93$client_data]])>
94
95Registers the handler specified as a subroutine reference in $handler for
96database locked conditions. The value of $client_data is simply passed to the
97handler and can be used by the caller to provide a context. This is both a
98class method as well as an object one. When used as a class method, the
99specified database locked handler is used for all Monotone::AutomateStdio
100objects that do not specify their own handlers. If no handler is given then the
101database locked condition handling is reset to the default behaviour.
102
103The handler subroutine is given two arguments, the first one is the
104Monotone::AutomateStdio object that encountered the locked database and the
105second is the value passed in as $client_data when the hander was
106registered. If the handler returns true then the request that failed is
107retried, if false is returned (undef) then the default behaviour is performed,
108which is to treat it like any other error.
109
110Typically one would register a database locked handler when you are using this
111class in a long running application where it is quite possible that a user
112might do an mtn sync in the background. For example, mtn-browse uses this
113handler to display a `Database is locked, please retry...' dialog window.
114
115=item B<Monotone::AutomateStdio-E<gt>register_error_handler($severity[,
116$handler[, $client_data]])>
117
118Registers the handler specified as a subroutine reference in $handler for
119errors of a certain severity as specified by $severity. $severity can be one of
120MTN_SEVERITY_WARNING, MTN_SEVERITY_ERROR or MTN_SEVERITY_ALL. The value of
121$client_data is simply passed to the handler and can be used by the caller to
122provide a context. This is a class method rather than an object one as errors
123can be raised when calling a constructor. If no handler is given then the error
124handling is reset to the default behaviour for that severity level.
125
126The handler subroutine is given three arguments, the first one is a severity
127string that indicates the severity of the error being handled (either
128MTN_SEVERITY_WARNING or MTN_SEVERITY_ERROR), the second one is the error
129message and the third is the value passed in as $client_data when the hander
130was registered.
131
132Please note:
133
134=over 4
135
136=item 1)
137
138Warnings can be generated internally or whenever a message is received from an
139mtn subprocess that is flagged as being in error. For example, this occurs when
140an invalid selector is given to the $mtn-E<gt>select() method. The subprocess
141does not exit under these conditions. Errors, however, are generated whenever
142this class detects abnormal behaviour such as output that is formatted in an
143unexpected manor or output appearing on the mtn subprocess's STDERR file
144descriptor. Under these circumstances it is expected that the application
145should exit or at least destroy any Monotone::AutomateStdio objects that are in
146error.
147
148=item 2)
149
150Whilst warnings result in false being returned by those methods that return a
151boolean success indicator, errors always result in an exception being thrown.
152
153=item 3)
154
155If the severity is MTN_SEVERITY_ERROR then it is expected that croak or die
156will be called by the handler, if this is not the case then this class will
157call croak() upon return. If you need to trap errors and prevent program exit
158then use an eval block to protect yourself in the calling code.
159
160=item 4)
161
162If a warning handler is registered then this can be used to report problems via
163one routine rather than checking the boolean success indicator returned by most
164methods in this class.
165
166=item 5)
167
168In order to get the severity constants into your namespace you need to use the
169following to load in this library.
170
171 use Monotone::AutomateStdio qw(:severities);
172
173=back
174
175=item B<Monotone::AutomateStdio-E<gt>register_io_wait_handler([$handler,
176$timeout[, $client_data]])>
177
178Registers the handler specified as a subroutine reference in $handler for I/O
179wait conditions. This class will call the handler after waiting $timeout
180seconds for data to come from the mtn subprocess. The value of $client_data is
181simply passed to the handler and can be used by the caller to provide a
182context. This is both a class method as well as an object one. When used as a
183class method, the specified I/O wait handler is used for all
184Monotone::AutomateStdio objects that do not specify their own handlers. If no
185handler is given then I/O wait handling is reset to the default behaviour.
186
187The handler subroutine is given two arguments, the first one is the
188Monotone::AutomateStdio object that is waiting for output from the mtn
189subprocess and the second is the value passed in as $client_data when the
190handler was registered.
191
192Typically one would register an I/O wait handler when you are using this class
193in an interactive application where it may be necessary to do some periodic
194background processing whilst waiting for the mtn subprocess to do
195something. For example, mtn-browse uses this handler to process any outstanding
196Gtk2 events so that the application can keep its windows up to date.
197
198=item B<Monotone::AutomateStdio-E<gt>suppress_utf8_conversion($suppress)>
199
200Controls whether UTF-8 conversion should be done on the data sent to and from
201the mtn subprocess by this class. If $suppress is true then UTF-8 conversion is
202not done, otherwise it is. The default action is to do UTF-8 conversion. This
203is both a class method as well as an object one. When used as a class method,
204the setting is used for all applicable Monotone::AutomateStdio objects that do
205not specify their own setting.
206
207=item B<Monotone::AutomateStdio-E<gt>switch_to_ws_root($switch)>
208
209Controls whether this class automatically switches to a workspace's root
210directory before running the mtn subprocess. If $switch is true then the switch
211to the workspace's root directory is done, otherwise it is not. The default
212action is to do the switch as this is generally safer. This setting only
213affects objects constructed from calling Monotone::AutomateStdio-E<gt>new() and
214Monotone::AutomateStdio-E<gt>new_from_db(). This is both a class method as well
215as an object one. When used as a class method, the setting is used for all
216applicable Monotone::AutomateStdio objects that do not specify their own
217setting.
218
219=back
220
221=head1 OBJECT METHODS
222
223See http://monotone.ca/monotone.html for a complete description of the mtn
224automate commands.
225
226Methods that return data from the mtn subprocess do so via their first
227argument. This argument is a reference to either a scalar or a list depending
228upon whether the data returned by the method is raw data or a list of items
229respectively. Methods that return lists of records, rather than a simple list
230of scalar items, also provide the option of returning the data as one raw chunk
231if the reference points to a scalar rather than a list. Therefore:
232
233 $mtn->get_manifest_of(\$buffer);
234
235would simply put the output from the `get_manifest_of' command into the
236variable named $buffer, whereas:
237
238 $mtn->get_manifest_of(\@list);
239
240would return the output as a list of records (actually anonymous hashes to be
241precise). However:
242
243 $mtn->get_file(\$buffer, $file_id);
244
245will always need a reference to a scalar and:
246
247 $mtn->select(\@list, $selector);
248
249will always need a reference to a list (each item is just a string containing a
250revision id rather than a record).
251
252The one exception to the above is the $mtn-E<gt>genkey() method, which expects
253a reference to either a scalar or a hash as it only ever returns one record's
254worth of information.
255
256The remaining arguments depend upon the mtn command being used.
257
258The following methods are provided:
259
260=over 4
261
262=item B<$mtn-E<gt>ancestors(\@list, $revision_id ...)>
263
264Get a list of ancestors for the specified revisions.
265
266=item B<$mtn-E<gt>ancestry_difference(\@list, $new_revision_id
267[, $old_revision_id ...])>
268
269Get a list of ancestors for the specified revision, that are not also
270ancestors for the specified old revisions.
271
272=item B<$mtn-E<gt>branches(\@list)>
273
274Get a list of branches.
275
276=item B<$mtn-E<gt>cert($revision_id, $name, $value)>
277
278Add the specified certificate to the specified revision.
279
280=item B<$mtn-E<gt>certs(\$buffer | \@list, $revision_id)>
281
282Get all the certificates for the specified revision. If \$buffer is passed then
283the output from the command is simply placed into the variable. However if
284\@list is passed then the output is returned as a list of anonymous hashes,
285each one containing the following fields:
286
287 key - The signer of the cert. Prior to version 0.45 of
288 Monotone this was in the form of typically an email
289 address. From version 0.45 onwards this is now a
290 hash. (feature: MTN_HASHED_SIGNATURES)
291 signature - Signer status. Values can be one of "ok", "bad" or
292 "unknown".
293 name - The cert name.
294 value - Its value.
295 trust - Its trust status. Values can be one of "trusted" or
296 "untrusted".
297
298=item B<$mtn-E<gt>children(\@list, $revision_id)>
299
300Get a list of children for the specified revision.
301
302=item B<$mtn-E<gt>closedown()>
303
304If started then stop the mtn subprocess. Please note that the mtn subprocess is
305automatically stopped when the related object is destroyed. This method is
306provided so that application developers can conveniently control when the
307subprocess is active.
308
309=item B<$mtn-E<gt>common_ancestors(\@list, $revision_id ...)>
310
311Get a list of revisions that are all ancestors of the specified revision(s).
312
313=item B<$mtn-E<gt>content_diff(\$buffer[, \@options[, $revision_id1,
314$revision_id2[, $file_name ...]]])>
315
316Get the difference between the two specified revisions, optionally limiting the
317output by using the specified options and file restrictions. If the second
318revision id is undefined then the workspace's current revision is used. If both
319revision ids are undefined then the workspace's current and base revisions are
320used. If no file names are listed then differences in all files are reported.
321
322The $options argument is a list of valid options, with some having
323arguments. For example, one could call this method specifying all of the
324options like this (feature: MTN_CONTENT_DIFF_EXTRA_OPTIONS):
325
326 $mtn->content_diff(\@result,
327 ["depth" => 1,
328 "exclude" => "work.cc",
329 "reverse",
330 "with-header"],
331 "unix");
332
333=item B<$mtn-E<gt>db_get(\$buffer, $domain, $name)>
334
335Get the value of a database variable.
336
337(feature: MTN_DB_GET, obsolete: replaced by $mtn-E<gt>get_db_variables())
338
339=item B<$mtn-E<gt>db_locked_condition_detected()>
340
341Check to see if the Monotone database was locked the last time a command was
342issued.
343
344=item B<$mtn-E<gt>descendents(\@list, $revision_id ...)>
345
346Get a list of descendants for the specified revision(s).
347
348=item B<$mtn-E<gt>drop_attribute($path[, $key])>
349
350Drop attributes from the specified file or directory, optionally limiting it to
351the specified attribute.
352
353(feature: MTN_DROP_ATTRIBUTE)
354
355=item B<$mtn-E<gt>drop_db_variables($domain[, $name])>
356
357Drop variables from the specified domain, optionally limiting it to the
358specified variable.
359
360(feature: MTN_DROP_DB_VARIABLES)
361
362=item B<$mtn-E<gt>erase_ancestors(\@list[, $revision_id ...])>
363
364For a given list of revisions, weed out those that are ancestors to other
365revisions specified within the list.
366
367=item B<$mtn-E<gt>file_merge(\$buffer, $left_revision_id, $left_file_name,
368$right_revision_id, $right_file_name)>
369
370Get the result of merging two files, both of which are on separate revisions.
371
372(feature: MTN_FILE_MERGE)
373
374=item B<$mtn-E<gt>genkey(\$buffer | \%hash, $key_id, $pass_phrase)>
375
376Generate a new key for use within the database. If \$buffer is passed then the
377output from the command is simply placed into the variable. However if \%hash
378is passed then the output is returned as one anonymous hash containing the
379following fields:
380
381 Prior to version 0.44 of Monotone:
382 name - The name of the key.
383 public_hash - The public hash code.
384 private_hash - The private hash code.
385 public_locations - A list of locations for the public hash
386 code. Values can be one of "database" or
387 "keystore".
388 private_locations - A list of locations for the private hash
389 code. Values can be one of "database" or
390 "keystore".
391
392 From version 0.44 of Monotone onwards
393 (feature: MTN_COMMON_KEY_HASH):
394 name - The name of the key.
395 hash - The hash code (both public and private).
396 public_locations - A list of locations for the public hash
397 code. Values can be one of "database" or
398 "keystore".
399 private_locations - A list of locations for the private hash
400 code. Values can be one of "database" or
401 "keystore".
402
403=item B<$mtn-E<gt>get_attributes(\$buffer | \@list, $file_name)>
404
405Get the attributes of the specified file. If \$buffer is passed then the output
406from the command is simply placed into the variable. However if \@list is
407passed then the output is returned as a list of anonymous hashes, each one
408containing the following fields:
409
410 attribute - The name of the attribute.
411 value - The value of the attribute.
412 state - The status of the attribute. Values can be one of
413 "added", "changed", "dropped" or "unchanged".
414
415Also known as $mtn-E<gt>attributes().
416
417(feature: MTN_GET_ATTRIBUTES)
418
419=item B<$mtn-E<gt>get_base_revision_id(\$buffer)>
420
421Get the id of the revision upon which the workspace is based.
422
423=item B<$mtn-E<gt>get_content_changed(\@list, $revision_id, $file_name)>
424
425Get a list of revisions in which the content was most recently changed,
426relative to the specified revision.
427
428=item B<$mtn-E<gt>get_corresponding_path(\$buffer, $source_revision_id,
429$file_name, $target_revision_id)>
430
431For the specified file name in the specified source revision, return the
432corresponding file name for the specified target revision.
433
434=item B<$mtn-E<gt>get_current_revision(\$buffer | \@list[, \@options[, $path
435...]])>
436
437Get the revision information for the current revision, optionally limiting the
438output by using the specified options and file restrictions. If \$buffer is
439passed then the output from the command is simply placed into the
440variable. However if \@list is passed then the output is returned in exactly
441the same format as for the $mtn-E<gt>get_revision() method.
442
443The $options argument is a list of valid options, with some having
444arguments. For example, one could call this method specifying all of the
445options like this:
446
447 $mtn->get_current_revision(\@result,
448 ["depth" => 1,
449 "exclude" => "work.cc"],
450 "unix");
451
452(feature: MTN_GET_CURRENT_REVISION)
453
454=item B<$mtn-E<gt>get_current_revision_id(\$buffer)>
455
456Get the id of the revision that would be created if an unrestricted commit was
457done in the workspace.
458
459=item B<$mtn-E<gt>get_db_name()>
460
461Return the file name of the Monotone database as given to the constructor. If
462no such name was given then undef is returned.
463
464=item B<$mtn-E<gt>get_db_variables(\$buffer | \@list[, $domain])>
465
466Get the variables stored in the database, optionally limiting it to the
467specified domain. If \$buffer is passed then the output from the command is
468simply placed into the variable. However if \@list is passed then the output is
469returned as a list of anonymous hashes, each one containing the following
470fields:
471
472 domain - The domain name to which the variable belongs.
473 name - The name of the variable.
474 value - The value of the variable.
475
476(feature: MTN_GET_DB_VARIABLES)
477
478=item B<$mtn-E<gt>get_error_message()>
479
480Return the last error message received from the mtn subprocess. An empty string
481is returned if no error has occurred yet.
482
483Please note that the error message is never cleared but just overwritten.
484Therefore one can use this method to determinate the nature of an error once it
485has been discovered but not to actually detect it in the first place. Use
486either an error handler or check the return status of methods to detect error
487conditions.
488
489=item B<$mtn-E<gt>get_file(\$buffer, $file_id)>
490
491Get the contents of the file referenced by the specified file id.
492
493=item B<$mtn-E<gt>get_file_of(\$buffer, $file_name[, $revision_id])>
494
495Get the contents of the specified file under the specified revision. If the
496revision id is undefined then the current workspace revision is used.
497
498=item B<$mtn-E<gt>get_manifest_of(\$buffer | \@list, $revision_id)>
499
500Get the manifest for the current or specified revision. If \$buffer is
501passed then the output from the command is simply placed into the
502variable. However if \@list is passed then the output is returned as a list
503of anonymous hashes, each one containing the following fields:
504
505 type - The type of entry. Values can be one of "file" or
506 "directory".
507 name - The name of the directory or file.
508 file_id - The id of the file. This field is only present if
509 type is set to "file".
510 attributes - A list of attributes for the file or directory. Each
511 entry has the following fields:
512 attribute - The name of the attribute.
513 value - The value of the attribute.
514
515=item B<$mtn-E<gt>get_option(\$buffer, $option_name)>
516
517Get the value of an option stored in a workspace's _MTN directory.
518
519=item B<$mtn-E<gt>get_pid()>
520
521Return the process id of the mtn subprocess spawned by this class. Zero is
522returned if no subprocess is thought to exist. Also if the subprocess should
523exit unexpectedly then this method will carry on returning its process id until
524the $mtn-E<gt>closedown() method is called.
525
526=item B<$mtn-E<gt>get_revision(\$buffer | \@list, $revision_id)>
527
528Get the revision information for the current or specified revision. If \$buffer
529is passed then the output from the command is simply placed into the
530variable. However if \@list is passed then the output is returned as a list of
531anonymous hashes, each one containing a variety of fields depending upon the
532type of entry:
533
534 type - The type of entry. Values can be one of "add_dir",
535 "add_file", "clear", "delete", "new_manifest",
536 "old_revision", "patch", "rename" or "set".
537
538 add_dir:
539 name - The name of the directory that was added.
540
541 add_file:
542 name - The name of the file that was added.
543 file_id - The id of the file.
544
545 clear:
546 name - The name of the file to which the attribute
547 applied.
548 attribute - The name of the attribute that was cleared.
549
550 delete:
551 name - The name of the directory or file that was deleted.
552
553 new_manifest:
554 manifest_id - The id of the revision's new manifest.
555
556 old_revision:
557 revision_id - The id of the parent revision.
558
559 patch:
560 name - The name of the file that was changed.
561 from_file_id - The file's old id.
562 to_file_id - The file's new id.
563
564 rename:
565 from_name - The name of the file before the rename.
566 to_name - The name of the file after the rename.
567
568 set:
569 name - The name of the file that had an attribute set.
570 attribute - The name of the attribute that was set.
571 value - The value that the attribute was set to.
572
573=item B<$mtn-E<gt>get_db_name()>
574
575Return the service name of the Monotone server as given to the constructor.
576
577(feature: MTN_REMOTE_CONNECTIONS)
578
579=item B<$mtn-E<gt>get_workspace_root(\$buffer)>
580
581Get the absolute path for the current workspace's root directory.
582
583(feature: MTN_GET_WORKSPACE_ROOT)
584
585=item B<$mtn-E<gt>get_ws_path()>
586
587Return the the workspace's base directory as either given to the constructor or
588deduced from the current workspace. If neither condition holds true then undef
589is returned. Please note that the workspace's base directory may differ from
590that given to the constructor if the specified workspace path is actually a
591subdirectory within that workspace.
592
593=item B<$mtn-E<gt>graph(\$buffer | \@list)>
594
595Get a complete ancestry graph of the database. If \$buffer is passed then the
596output from the command is simply placed into the variable. However if \@list
597is passed then the output is returned as a list of anonymous hashes, each one
598containing the following fields:
599
600 revision_id - The id of a revision.
601 parent_ids - A list of parent revision ids.
602
603=item B<$mtn-E<gt>heads(\@list[, $branch_name])>
604
605Get a list of revision ids that are heads on the specified branch. If no branch
606is given then the workspace's branch is used.
607
608=item B<$mtn-E<gt>identify(\$buffer, $file_name)>
609
610Get the file id, i.e. hash, of the specified file.
611
612=item B<$mtn-E<gt>ignore_suspend_certs($ignore)>
613
614Determine whether revisions with a suspend certificate are to be ignored or
615not. If $ignore is true then suspend certificates are ignored, otherwise they
616are honoured (in which case any suspended revisions and branches that only have
617suspended revisions on their heads will not be listed). The default behaviour
618is to honour suspend certificates.
619
620(feature: MTN_IGNORING_OF_SUSPEND_CERTS)
621
622=item B<$mtn-E<gt>interface_version(\$buffer)>
623
624Get the version of the mtn automate interface.
625
626=item B<$mtn-E<gt>inventory(\$buffer | \@list[, \@options[, $path ...]])>
627
628Get the inventory for the current workspace, optionally limiting the output by
629using the specified options and file restrictions. If \$buffer is passed then
630the output from the command is simply placed into the variable. However if
631\@list is passed then the output is returned as a list of anonymous hashes,
632each one containing one or more of the following fields:
633
634 Prior to version 0.37 of Monotone:
635 status - The three inventory status characters for the
636 file or directory.
637 crossref_one - The first cross-referencing number.
638 crossref_two - The second cross-referencing number.
639 name - The name of the file or directory.
640
641 From version 0.37 of Monotone onwards
642 (feature: MTN_INVENTORY_IN_IO_STANZA_FORMAT):
643 path - The name of the file or directory.
644 old_type - The type of the entry in the base manifest. Values
645 can be one of "directory", "file" or "none".
646 new_type - The type of the entry in the revision manifest.
647 Values can be one of "directory", "file" or
648 "none".
649 fs_type - The type of the entry on the file system. Values
650 can be one of "directory", "file" or "none".
651 old_path - The old name of the file or directory if it has
652 been renamed in the revision manifest.
653 new_path - The new name of the file or directory if it has
654 been renamed in the revision manifest.
655 birth_id - The revision id in which the node was first
656 added. Only from version 0.41 of Monotone
657 onwards. (feature: MTN_INVENTORY_WITH_BIRTH_ID)
658 status - A list of status flags. Values can be one of
659 "added", "dropped", "ignored", "invalid", "known",
660 "missing", "rename_source", "rename_target" or
661 "unknown".
662 changes - A list of change flags. Values can be one of
663 "attrs" or "content".
664
665Please note that some fields are not used by all entries, in which case they
666are not present (use Perl's exists() function to determine their presence and
667not defined()).
668
669The $options argument is a list of valid options, with some having
670arguments. For example, one could call this method specifying all of the
671options like this (feature: MTN_INVENTORY_TAKING_OPTIONS):
672
673 $mtn->inventory(\@result,
674 ["depth" => 1,
675 "exclude" => "work.cc",
676 "no-corresponding-renames",
677 "no-ignored",
678 "no-unknown",
679 "no-unchanged"],
680 "unix");
681
682=item B<$mtn-E<gt>keys(\$buffer | \@list)>
683
684Get a list of all the keys known to mtn. If \$buffer is passed then the output
685from the command is simply placed into the variable. However if \@list is
686passed then the output is returned as a list of anonymous hashes, each one
687containing the following fields:
688
689 Prior to version 0.44 of Monotone:
690 name - The name of the key.
691 public_hash - The public hash code.
692 private_hash - The private hash code.
693 public_locations - A list of locations for the public hash
694 code. Values can be one of "database" or
695 "keystore".
696 private_locations - A list of locations for the private hash
697 code. Values can be one of "database" or
698 "keystore". This field is only present if
699 there is a private key.
700
701 Version 0.44 of Monotone (feature: MTN_COMMON_KEY_HASH):
702 name - The name of the key.
703 hash - The hash code (both public and private).
704 public_locations - A list of locations for the public hash
705 code. Values can be one of "database" or
706 "keystore".
707 private_locations - A list of locations for the private hash
708 code. Values can be one of "database" or
709 "keystore". This field is only present if
710 there is a private key.
711
712 From version 0.45 of Monotone onwards
713 (feature: MTN_HASHED_SIGNATURES):
714 given_name - The name of the key as given when it was
715 created.
716 hash - The hash code (both public and private).
717 local_name - The local name of the key as returned by
718 the get_local_key_name() hook.
719 public_locations - A list of locations for the public hash
720 code. Values can be one of "database" or
721 "keystore".
722 private_locations - A list of locations for the private hash
723 code. Values can be one of "database" or
724 "keystore". This field is only present if
725 there is a private key.
726
727Please note that some fields are not used by all entries, in which case they
728are not present (use Perl's exists() function to determine their presence and
729not defined()).
730
731=item B<$mtn-E<gt>leaves(\@list)>
732
733Get a list of leaf revisions.
734
735=item B<$mtn-E<gt>lua(\$buffer, $lua_function[, $argument ...])>
736
737Call the specified LUA function with any required arguments.
738
739(feature: MTN_LUA)
740
741=item B<$mtn-E<gt>packet_for_fdata(\$buffer, $file_id)>
742
743Get the contents of the file referenced by the specified file id in packet
744format.
745
746=item B<$mtn-E<gt>packet_for_fdelta(\$buffer, $from_file_id, $to_file_id)>
747
748Get the file delta between the two files referenced by the specified file ids
749in packet format.
750
751=item B<$mtn-E<gt>packet_for_rdata(\$buffer, $revision_id)>
752
753Get the contents of the revision referenced by the specified revision id in
754packet format.
755
756=item B<$mtn-E<gt>packets_for_certs(\$buffer, $revision_id)>
757
758Get all the certs for the revision referenced by the specified revision id in
759packet format.
760
761=item B<$mtn-E<gt>parents(\@list, $revision_id)>
762
763Get a list of parents for the specified revision.
764
765=item B<$mtn-E<gt>pull([@options[, $service[, $pattern]]])>
766
767Synchronises database changes from the specified remote server to the local
768database but not in the other direction. Other details are identical to the
769$mtn-E<gt>sync() method.
770
771(feature: MTN_SYNCHRONISATION)
772
773=item B<$mtn-E<gt>push([@options[, $service[, $pattern]]])>
774
775Synchronises database changes from the local database to the specified remote
776server but not in the other direction. Other details are identical to the
777$mtn-E<gt>sync() method.
778
779(feature: MTN_SYNCHRONISATION)
780
781=item B<$mtn-E<gt>put_file(\$buffer, $base_file_id, \$contents)>
782
783Put the specified file contents into the database, optionally basing it on the
784specified file id (this is used for delta encoding). The file id is returned.
785
786=item B<$mtn-E<gt>put_revision(\$buffer, \$contents)>
787
788Put the specified revision data into the database. The revision id is
789returned. Please note that any newly created revisions have no certificates
790associated with them and so these have to be added using the $mtn-E<gt>cert()
791method.
792
793=item B<$mtn-E<gt>read_packets($packet_data)>
794
795Decode and store the specified packet data in the database.
796
797(feature: MTN_READ_PACKETS)
798
799=item B<$mtn-E<gt>register_error_handler($severity[, $handler
800[, $client_data]])>
801
802Registers an error handler for the object rather than the class. For further
803details please see the description of the class method.
804
805=item B<$mtn-E<gt>register_db_locked_handler([$handler[, $client_data]])>
806
807Registers a database locked handler for the object rather than the class. For
808further details please see the description of the class method.
809
810=item B<$mtn-E<gt>register_io_wait_handler([$handler, $timeout
811[, $client_data]])>
812
813Registers an I/O wait handler for the object rather than the class. For further
814details please see the description of the class method.
815
816=item B<$mtn-E<gt>register_stream_handle($stream[, $handle]])>
817
818Registers the file handle specified in $handle so that it will receive data
819from the specified mtn output stream. $stream can be one of MTN_P_STREAM or
820MTN_T_STREAM. If no file handle is given then any existing file handle is
821unregistered for that stream.
822
823Please note:
824
825=over 4
826
827=item 1)
828
829It is vitally important that if you register some sort of pipe or socket to
830receive mtn stream output, that any data sent down it is read immediately and
831independently from the code calling the method generating the output (either by
832using a thread or another process). Not doing so could easily cause a deadlock
833situation to occur where the method stops processing, waiting for the pipe or
834socket to empty before proceeding.
835
836=item 2)
837
838The output streams are largely sent as received from the mtn subprocess (please
839refer to the Monotone documentation for further details on the format). The
840only difference is that since the `l' or last message (which marks the end of a
841command's output) is only sent once by mtn, this class duplicates it onto any
842registered stream so that the reader knows when there is no more data for a
843command.
844
845=item 3)
846
847In order to get the stream constants into your namespace you need to use the
848following to load in this library.
849
850 use Monotone::AutomateStdio qw(:streams);
851
852=back
853
854(feature: MTN_STREAM_IO)
855
856=item B<$mtn-E<gt>roots(\@list)>
857
858Get a list of root revisions, i.e. revisions with no parents.
859
860=item B<$mtn-E<gt>select(\@list, $selector)>
861
862Get a list of revision ids that match the specified selector.
863
864=item B<$mtn-E<gt>set_attribute($path, $key, $value)>
865
866Set an attribute on the specified file or directory.
867
868(feature: MTN_SET_ATTRIBUTE)
869
870=item B<$mtn-E<gt>set_db_variable($domain, $name, $value)>
871
872Set the value of a database variable.
873
874Also known as $mtn-E<gt>db_set().
875
876(feature: MTN_SET_DB_VARIABLE)
877
878=item B<$mtn-E<gt>show_conflicts(\$buffer | \@list[, $branch][,
879$left_revision_id, $right_revision_id])>
880
881Get a list of conflicts between the first two head revisions on the current
882branch, optionally one can specify both head revision ids and the name of the
883branch that they reside on. If \$buffer is passed then the output from the
884command is simply placed into the variable. However if \@list is passed then
885the output is returned as a list of anonymous hashes, each one containing one
886or more of the following fields:
887
888 ancestor - The id of the common ancestor revision for
889 both revisions in conflict.
890 ancestor_file_id - The common ancestor file id for both files in
891 conflict.
892 ancestor_name - The name of the ancestor file or directory.
893 attr_name - The name of the Monotone file or directory
894 attribute that is in conflict.
895 conflict - The nature of the conflict. Values can be one
896 of "attribute", "content",
897 "directory_loop", "duplicate_name",
898 "invalid_name", "missing_root",
899 "multiple_names", "orphaned_directory" or
900 "orphaned_file".
901 left - The id of the left hand revision that is in
902 conflict.
903 left_attr_value - The value of the attribute on the file or
904 directory in the left hand revision.
905 left_file_id - The id of the file in the left hand revision.
906 left_name - The name of the file or directory in the left
907 hand revision.
908 left_type - The type of conflict relating to the file or
909 directory in the left hand revision. Values
910 can be one of "added directory",
911 "added file", "deleted directory",
912 "pivoted root", "renamed directory" or
913 "renamed file".
914 node_type - The type of manifest node. Values can be one
915 of "file" or "directory".
916 resolved_internal - Only present if the conflict can be resolved
917 internally by Monotone during the merge
918 process.
919 right - The id of the right hand revision that is in
920 conflict.
921 right_attr_state - The state of the attribute in the right hand
922 revision. Values can only be "dropped".
923 right_attr_value - The value of the attribute on the file or
924 directory in the right hand revision.
925 right_file_id - The id of the file in the right hand
926 revision.
927 right_name - The name of the file or directory in the
928 right hand revision.
929 right_type - The type of conflict relating to the file or
930 directory in the left revision. Values are as
931 documented for left_type.
932
933Please note that some fields are not used by all entries, in which case they
934are not present (use Perl's exists() function to determine their presence and
935not defined()).
936
937(feature: MTN_SHOW_CONFLICTS)
938
939=item B<$mtn-E<gt>supports($feature)>
940
941Determine whether a certain feature is available with the version of Monotone
942that is currently being used by this object. The list of valid features are:
943
944 MTN_COMMON_KEY_HASH
945 MTN_CONTENT_DIFF_EXTRA_OPTIONS
946 MTN_DB_GET
947 MTN_DROP_ATTRIBUTE
948 MTN_DROP_DB_VARIABLES
949 MTN_FILE_MERGE
950 MTN_GET_ATTRIBUTES
951 MTN_GET_CURRENT_REVISION
952 MTN_GET_DB_VARIABLES
953 MTN_GET_WORKSPACE_ROOT
954 MTN_HASHED_SIGNATURES
955 MTN_IGNORING_OF_SUSPEND_CERTS
956 MTN_INVENTORY_IN_IO_STANZA_FORMAT
957 MTN_INVENTORY_TAKING_OPTIONS
958 MTN_INVENTORY_WITH_BIRTH_ID
959 MTN_LUA
960 MTN_M_SELECTOR
961 MTN_P_SELECTOR
962 MTN_READ_PACKETS
963 MTN_REMOTE_CONNECTIONS
964 MTN_SET_ATTRIBUTE
965 MTN_SET_DB_VARIABLE
966 MTN_SHOW_CONFLICTS
967 MTN_STREAM_IO
968 MTN_SYNCHRONISATION
969 MTN_U_SELECTOR
970 MTN_W_SELECTOR
971
972In order to get these constants into your namespace you need to use the
973following to load in this library.
974
975 use Monotone::AutomateStdio qw(:capabilities);
976
977Please note that if you see (feature: ...) then this means that whatever is
978being discussed is only available if $mtn-E<gt>supports() returns true for the
979specified feature.
980
981=item B<$mtn-E<gt>sync([@options[, $service[, $pattern]]])>
982
983Synchronises database changes between the local database and the specified
984remote server. $service is in exactly the same format as for the
985Monotone::AutomateStdio->new_from_service() constructor. $pattern is a branch
986pattern to include in the synchronisation operation.
987
988The $options argument is a list of valid options, with some having
989arguments. For example, one could call this method specifying all of the
990options like this:
991
992 $mtn->sync(["exclude" => "experiments.hacks",
993 "key-to-push" => "me@mydomain.com",
994 "max-netsync-version" => 2,
995 "min-netsync-version" => 1,
996 "set-default"]);
997
998(feature: MTN_SYNCHRONISATION)
999
1000=item B<$mtn-E<gt>tags(\$buffer | \@list[, $branch_pattern])>
1001
1002Get all the tags attached to revisions on branches that match the specified
1003branch pattern. If no pattern is given then all branches are searched. If
1004\$buffer is passed then the output from the command is simply placed into the
1005variable. However if \@list is passed then the output is returned as a list of
1006anonymous hashes, each one containing the following fields:
1007
1008 tag - The name of the tag.
1009 revision_id - The id of a revision that the tag is attached to.
1010 signer - The signer of the tag. Prior to version 0.45 of
1011 Monotone this was in the form of typically an email
1012 address. From version 0.45 onwards this is now a
1013 hash. (feature: MTN_HASHED_SIGNATURES)
1014 branches - A list of all branches that contain this revision.
1015
1016=item B<$mtn-E<gt>toposort(\@list[, $revision_id ...])>
1017
1018Sort the specified revision ids such that the ancestors come out first.
1019
1020=item B<$mtn-E<gt>update([@options])>
1021
1022Updates the current workspace to the specified revision and possible branch. If
1023no options are specified then the workspace is updated to the head revision of
1024the current branch.
1025
1026The $options argument is a list of valid options, with some having
1027arguments. For example, one could call this method specifying all of the
1028options like this:
1029
1030 $mtn->update(["branch" => "experiments.hacks",
1031 "move-conflicting-paths",
1032 "revision" => "h:"]);
1033
1034(feature: MTN_UPDATE)
1035
1036=back
1037
1038=head1 RETURN VALUE
1039
1040Except for those methods listed below, all remaining methods return a boolean
1041success indicator, true for success or false for failure.
1042
1043The following constructors return Monotone::AutomateStdio objects:
1044
1045 Monotone::AutomateStdio->new()
1046 Monotone::AutomateStdio->new_from_db()
1047 Monotone::AutomateStdio->new_from_service()
1048 Monotone::AutomateStdio->new_from_ws()
1049
1050The following method returns true or false (but it does not indicate success or
1051failure):
1052
1053 $mtn->db_locked_condition_detected()
1054
1055The following method returns an integer:
1056
1057 $mtn->get_pid()
1058
1059The following methods return a string or undef:
1060
1061 $mtn->get_db_name()
1062 $mtn->get_error_message()
1063 $mtn->get_ws_path()
1064
1065The following methods do not return anything:
1066
1067 Monotone::AutomateStdio->register_db_locked_handler()
1068 Monotone::AutomateStdio->register_error_handler()
1069 Monotone::AutomateStdio->register_io_wait_handler()
1070 Monotone::AutomateStdio->register_stream_handle()
1071 Monotone::AutomateStdio->suppress_utf8_conversion()
1072 $mtn->closedown()
1073
1074Please note that the boolean true and false values used by this class are
1075defined as 1 and undef respectively.
1076
1077=head1 EXAMPLES
1078
1079=head2 Detecting Warnings And Errors
1080
1081Errors cause exceptions to be thrown. Warnings cause the responsible method to
1082return false rather than true.
1083
1084Therefore warnings would typically be detected by using code like this:
1085
1086 $mtn->get_file(\$data, $file_id)
1087 or die('$mtn->get_file() failed with: '
1088 . $mtn->get_error_message());
1089
1090However this can get clumsy and cluttered after a while, especially when the
1091calling application knows that there is very little likelihood of there being a
1092problem. Having exceptions being thrown for warnings as well as errors may be a
1093better approach. By doing:
1094
1095 Monotone::AutomateStdio->register_error_handler
1096 (MTN_SEVERITY_ALL,
1097 sub
1098 {
1099 my($severity, $message) = @_;
1100 die($message);
1101 });
1102
1103or more tersely:
1104
1105 Monotone::AutomateStdio->register_error_handler
1106 (MTN_SEVERITY_ALL, sub { die($_[1]); });
1107
1108at the beginning of your application will mean that all errors and warnings
1109detected by this class will generate an exception, thus making the checking of
1110a method's return status redundant.
1111
1112=head2 Silently Retrying Operations When The Database Is Locked
1113
1114If the Monotone database is locked then, by default, this class will report
1115that condition as a warning. However it may be more convenient to ask this
1116class to silently retry the operation until it succeeds. This can easily be
1117done by using the database locked handler as follows:
1118
1119 Monotone::AutomateStdio->register_db_locked_handler
1120 (sub { sleep(1); return 1; });
1121
1122This will mean that should any database locked conditions occur then this class
1123will silently sleep for one second before retrying the operation.
1124
1125=head2 Dealing With Processing Lockouts And Delays
1126
1127Some requests sent to the mtn subprocess can take several seconds to complete
1128and consequently this class will take that amount of time, plus a very small
1129processing overhead, to return. Whilst one can get around this by using
1130threads, another way is to register an I/O wait handler. For example:
1131
1132 Monotone::AutomateStdio->register_io_wait_handler
1133 (sub { WindowManager->instance()->update_gui(); }, 1);
1134
1135will instruct this class to update the user display every second whilst it is
1136waiting for the mtn subprocess to finish processing a request.
1137
1138=head1 NOTES
1139
1140=head2 Using This Class With Monotone Workspaces
1141
1142Certain features are only available when used inside a Monotone workspace, so
1143consequently this class does support the use of workspaces. However certain
1144aspects of a workspace can affect the mtn subprocess. For example, when you run
1145mtn in a workspace's subdirectory then all file name arguments get translated
1146into paths relative to the workspace's root directory (i.e. given a path of
1147/home/freddy/workspace/include/system.h when one runs C<mtn log system.h> in
1148the include directory the file name gets changed to include/system.h).
1149
1150This makes perfect sense on the command line but possibly less so when using
1151mtn from inside a GUI application where the directory in which the application
1152was launched is not as relevant. This is why this class runs the mtn subprocess
1153in specific directories depending upon how the object is constructed. If the
1154object is constructed by calling Monotone::AutomateStdio-E<gt>new() or
1155Monotone::AutomateStdio-E<gt>new_from_db() with the name of a database, then
1156the mtn subprocess is run in the root directory, otherwise it is run in the
1157workspace's root directory. This guarantees correct behaviour.
1158
1159If however you want the mtn subprocess to run in the current directory within a
1160workspace then simply use the Monotone::AutomateStdio-E<gt>switch_to_ws_root()
1161method to before calling Monotone::AutomateStdio-E<gt>new() without specifying
1162a database.
1163
1164Any changing of directory does not affect the caller.
1165
1166=head2 UTF-8 Handling
1167
1168A Monotone database may contain UTF-8 characters. These characters would most
1169commonly appear inside text files but may also appear in the names of files,
1170branches and even in certificates. Later versions of Perl have built in support
1171for UTF-8 strings and can represent this sort of data quite naturally without
1172the developer really having to worry too much. For this reason this class
1173automatically converts any data sent between Perl and a mtn subprocess to and
1174from Perl's internal UTF-8 string format and the standard binary octet
1175notation.
1176
1177There may be times when this built in conversion is inappropriate and so one
1178can simply switch it off by using the
1179Monotone::AutomateStdio-E<gt>suppress_utf8_conversion() method to before
1180calling Monotone::AutomateStdio-E<gt>new().
1181
1182Please note that not everything is converted when using this class's built in
1183UTF-8 conversion mechanism. This is mainly for efficiency. For example, there
1184is no real point in converting revision or file ids as these are always
1185represented as forty character hexadecimal strings. Likewise packet data is not
1186converted as this is always formatted to use seven bit ASCII. However there is
1187one case where no conversion is done for reasons other than efficiency, and
1188that is when handling file content data. Apart from differentiating between
1189binary and non-binary data, Monotone just treats file content data as a
1190sequence of bytes. In order to decide whether a file's contents contains UTF-8
1191data this may involve looking for assorted patterns in the data or checking the
1192file name's extension, all of which being beyond the scope of this class. Also
1193it is a good idea to treat file content data as a simple sequence of octets
1194anyway. Probably the only time that one would need to worry about UTF-8 based
1195file content data is when an application is displaying it using something like
1196Gtk2 (the Gtk2 bindings for Perl uses Perl's internal UTF-8 flag to determine
1197whether a string needs to be handled as a UTF-8 string or as a simple sequence
1198of octets). In this case, once a file's contents has been determined to contain
1199text oriented data, one can use Perl's decode_utf8() function to do the
1200conversion. For more information on Perl's handling of UTF-8 please see the
1201documentation for Encode.
1202
1203=head2 Process Handling
1204
1205There are situations where this class does legitimately terminate the mtn
1206subprocess (for example when a database locked condition is detected). When
1207this happens the subprocess is reaped and its id is reset, i.e. the
1208$mtn-E<gt>get_pid() method returns 0. However if the subprocess should exit
1209unexpectedly whilst processing a request then an exception is raised but no
1210reaping or process id resetting takes place. Therefore an application using
1211this class may wish to have a signal handler registered for SIGCHILD signals
1212that can indirectly trigger a call to the $mtn-E<gt>closedown() method or
1213destroy the object concerned in the event of an error. In order to distinguish
1214between legitimate terminations of the mtn subprocess and failures, simply
1215compare the reaped process id against that returned by the $mtn-E<gt>get_pid()
1216method. If there is a match then there is a problem, otherwise, as far as this
1217class is concerned, there is nothing to worry about.
1218
1219Please note that all SIGPIPE signals are set to be ignored as soon as the first
1220mtn subprocess is started by this class.
1221
1222=head2 Use Of SIGALRM
1223
1224In order to reliably shutdown the mtn subprocess, the alarm() routine is used
1225and will consequently reset any SIGALRM timers. In C I would obviously use
1226setitimer() to set up any timeout timers and then restore their previous state,
1227however to do this in Perl one has to use the Time::HiRes CPAN module. I felt
1228that on balance it would be nicer not to introduce this dependency and use
1229alarm(). Anyway if you want to do something periodically it is usually better
1230to have a thread do that for you rather than use signals. If you have different
1231opinions on this then please let me know.
1232
1233=head2 General
1234
1235When the output of a command from the automate stdio interface changes
1236dramatically, it will probably not be possible to protect Perl applications
1237from those changes. This class is a convenience wrapper rather than something
1238that will totally divorce you from the automate stdio interface. Also the
1239chances are you will want the new type of output anyway.
1240
1241No work will be done to support versions of Monotone older than 0.35, so if you
1242are in that position then I strongly suggest that you upgrade to a later
1243version of Monotone (you will get all the new features and bug fixes, go on you
1244know want them :-)). Also once the automate stdio interface has remained stable
1245for some time, support may be dropped for older versions in order to aid
1246maintenance and regression testing.
1247
1248The $mtn-E<gt>get_content_changed() method is very slow in Monotone versions
12490.40 and 0.41.
1250
1251=head1 SEE ALSO
1252
1253http://monotone.ca
1254
1255=head1 BUGS
1256
1257Your mileage may vary if this class is used with versions of Monotone older
1258than 0.35 (automate stdio interface version 4.3).
1259
1260This class is not thread safe. If you wish to use this class in a
1261multi-threaded environment then you either need to use a separate object per
1262thread or use threads::lock to protect each method call.
1263
1264=head1 AUTHORS
1265
1266Anthony Cooper with contributions and ideas from Thomas Keller. Currently
1267maintained by Anthony Cooper. Please report all faults and suggestions to
1268<support@coosoft.plus.com>.
1269
1270=head1 COPYRIGHT
1271
1272Copyright (C) 2008 by Anthony Cooper <aecooper@coosoft.plus.com>.
1273
1274This library is free software; you can redistribute it and/or modify it under
1275the terms of the GNU Lesser General Public License as published by the Free
1276Software Foundation; either version 3 of the License, or (at your option) any
1277later version.
1278
1279This library is distributed in the hope that it will be useful, but WITHOUT ANY
1280WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
1281PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
1282
1283You should have received a copy of the GNU Lesser General Public License along
1284with this library; if not, write to the Free Software Foundation, Inc., 59
1285Temple Place - Suite 330, Boston, MA 02111-1307 USA.
1286
1287=cut

Archive Download this file

Branches

Tags

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status