1Monotone::AutomateStdioU(s3e)r Contributed Perl DocumentaMtoinoontone::AutomateStdio(3)
2
3
4

NAME

6       Monotone::AutomateStdio - Perl interface to Monotone via automate stdio
7

VERSION

9       1.10
10

SYNOPSIS

12         use Monotone::AutomateStdio qw(:capabilities :severities);
13         my(@manifest,
14            $mtn,
15            @revs);
16         $mtn = Monotone::AutomateStdio->new("/home/fred/venge.mtn");
17         $mtn->select(\@revs, "h:net.venge.monotone");
18         $mtn->get_manifest_of(\@manifest, $revs[0])
19             or die("mtn: " . $mtn->get_error_message());
20

DESCRIPTION

22       The Monotone::AutomateStdio class gives a Perl developer access to
23       Monotone's automate stdio facility via an easy to use interface. All
24       command, option and output formats are handled internally by this
25       class. Any structured information returned by Monotone is parsed and
26       returned back to the caller as lists of records for ease of access
27       (detailed below). One also has the option of accessing Monotone's
28       output as one large string should you prefer.
29
30       The mtn automate stdio subprocess is also controlled by this class. A
31       new subprocess is started, if necessary, when anything that requires it
32       is called. The subprocess is terminated on object destruction or when
33       $mtn->closedown() is called.
34
35       All automate commands have been implemented in this class except for
36       the `stdio' command, hopefully the reason is obvious :-). Versions of
37       Monotone that are supported by this class range from 0.35 up to and
38       including the latest version (currently 1.10). If you happen to be
39       using a newer version of Monotone then this class will hopefully
40       largely work but without the support for new or changed features.
41

CONSTRUCTORS

43       $mtn = Monotone::AutomateStdio->new([\@options])
44           Creates a new Monotone::AutomateStdio object, using the current
45           workspace's database.
46
47       $mtn = Monotone::AutomateStdio->new_from_db($db[, \@options])
48           Creates a new Monotone::AutomateStdio object, using the database
49           named in $db.
50
51       $mtn = Monotone::AutomateStdio->new_from_service($service, [\@options])
52           Creates a new Monotone::AutomateStdio object, using the named
53           network service (which is expressed as either a Monotone style URL
54           or a host name optionally followed by a colon and the port number).
55
56           (feature: MTN_REMOTE_CONNECTIONS)
57
58       $mtn = Monotone::AutomateStdio->new_from_ws($ws[, \@options])
59           Creates a new Monotone::AutomateStdio object, using the workspace
60           named in $ws.
61
62       Please note that Monotone::AutomateStdio->new() is simply an alias for
63       Monotone::AutomateStdio->new_from_db().
64
65       The @options parameter specifies what options are to be passed to the
66       mtn subprocess. The currently supported list (in vaguely the format in
67       which it would be passed to the constructor) is:
68
69           ["--allow-default-confdir",
70            "--allow-workspace",
71            "--builtin-rcfile",
72            "--clear-rcfiles",
73            "--confdir"               => <Directory>,
74            "--key"                   => <Key To Be Used For Signatures>,
75            "--keydir"                => <Key Store Location>,
76            "--no-builtin-rcfile",
77            "--no-default-confdir",
78            "--no-standard-rcfiles",
79            "--no-workspace",
80            "--norc",
81            "--nostd",
82            "--rcfile"                => <LUA File To Load>,
83            "--root"                  => <Root Directory>,
84            "--ssh-sign"              => One of "check", "no" or "yes",
85            "--standard-rcfiles",
86            "--use-default-key"]
87

CLASS METHODS

89       Monotone::AutomateStdio->register_db_locked_handler([$handler[,
90       $client_data]])
91           Registers the handler specified as a subroutine reference in
92           $handler for database locked conditions. The value of $client_data
93           is simply passed to the handler and can be used by the caller to
94           provide a context. This is both a class method as well as an object
95           one. When used as a class method, the specified database locked
96           handler is used for all Monotone::AutomateStdio objects that do not
97           specify their own handlers. If no handler is given then the
98           database locked condition handling is reset to the default
99           behaviour.
100
101           The handler subroutine is given two arguments, the first one is the
102           Monotone::AutomateStdio object that encountered the locked database
103           and the second is the value passed in as $client_data when the
104           hander was registered. If the handler returns true then the request
105           that failed is retried, if false is returned (undef) then the
106           default behaviour is performed, which is to treat it like any other
107           error.
108
109           Typically one would register a database locked handler when you are
110           using this class in a long running application where it is quite
111           possible that a user might do an mtn sync in the background. For
112           example, mtn-browse uses this handler to display a `Database is
113           locked, please retry...' dialog window.
114
115       Monotone::AutomateStdio->register_error_handler($severity[, $handler[,
116       $client_data]])
117           Registers the handler specified as a subroutine reference in
118           $handler for errors of a certain severity as specified by
119           $severity. $severity can be one of MTN_SEVERITY_WARNING,
120           MTN_SEVERITY_ERROR or MTN_SEVERITY_ALL. The value of $client_data
121           is simply passed to the handler and can be used by the caller to
122           provide a context. This is a class method rather than an object one
123           as errors can be raised when calling a constructor. If no handler
124           is given then the error handling is reset to the default behaviour
125           for that severity level.
126
127           The handler subroutine is given three arguments, the first one is a
128           severity string that indicates the severity of the error being
129           handled (either MTN_SEVERITY_WARNING or MTN_SEVERITY_ERROR), the
130           second one is the error message and the third is the value passed
131           in as $client_data when the hander was registered.
132
133           Please note:
134
135           1)  Warnings can be generated internally or whenever a message is
136               received from an mtn subprocess that is flagged as being in
137               error. For example, this occurs when an invalid selector is
138               given to the $mtn->select() method. The subprocess does not
139               exit under these conditions. Errors, however, are generated
140               whenever this class detects abnormal behaviour such as output
141               that is formatted in an unexpected manor or output appearing on
142               the mtn subprocess's STDERR file descriptor. Under these
143               circumstances it is expected that the application should exit
144               or at least destroy any Monotone::AutomateStdio objects that
145               are in error.
146
147           2)  Whilst warnings result in false being returned by those methods
148               that return a boolean success indicator, errors always result
149               in an exception being thrown.
150
151           3)  If the severity is MTN_SEVERITY_ERROR then it is expected that
152               croak or die will be called by the handler, if this is not the
153               case then this class will call croak() upon return. If you need
154               to trap errors and prevent program exit then use an eval block
155               to protect yourself in the calling code.
156
157           4)  If a warning handler is registered then this can be used to
158               report problems via one routine rather than checking the
159               boolean success indicator returned by most methods in this
160               class.
161
162           5)  In order to get the severity constants into your namespace you
163               need to use the following to load in this library.
164
165                   use Monotone::AutomateStdio qw(:severities);
166
167       Monotone::AutomateStdio->register_io_wait_handler([$handler, $timeout[,
168       $client_data]])
169           Registers the handler specified as a subroutine reference in
170           $handler for I/O wait conditions. This class will call the handler
171           after waiting $timeout seconds for data to come from the mtn
172           subprocess. The value of $client_data is simply passed to the
173           handler and can be used by the caller to provide a context. This is
174           both a class method as well as an object one. When used as a class
175           method, the specified I/O wait handler is used for all
176           Monotone::AutomateStdio objects that do not specify their own
177           handlers. If no handler is given then I/O wait handling is reset to
178           the default behaviour.
179
180           The handler subroutine is given two arguments, the first one is the
181           Monotone::AutomateStdio object that is waiting for output from the
182           mtn subprocess and the second is the value passed in as
183           $client_data when the handler was registered.
184
185           Typically one would register an I/O wait handler when you are using
186           this class in an interactive application where it may be necessary
187           to do some periodic background processing whilst waiting for the
188           mtn subprocess to do something. For example, mtn-browse uses this
189           handler to process any outstanding Gtk2 events so that the
190           application can keep its windows up to date.
191
192       Monotone::AutomateStdio->suppress_utf8_conversion($suppress)
193           Controls whether UTF-8 conversion should be done on the data sent
194           to and from the mtn subprocess by this class. If $suppress is true
195           then UTF-8 conversion is not done, otherwise it is. The default
196           action is to do UTF-8 conversion. This is both a class method as
197           well as an object one. When used as a class method, the setting is
198           used for all applicable Monotone::AutomateStdio objects that do not
199           specify their own setting.
200
201       Monotone::AutomateStdio->switch_to_ws_root($switch)
202           Controls whether this class automatically switches to a workspace's
203           root directory before running the mtn subprocess. If $switch is
204           true then the switch to the workspace's root directory is done,
205           otherwise it is not. The default action is to do the switch as this
206           is generally safer. This setting only affects objects constructed
207           from calling Monotone::AutomateStdio->new() and
208           Monotone::AutomateStdio->new_from_db(). This is both a class method
209           as well as an object one. When used as a class method, the setting
210           is used for all applicable Monotone::AutomateStdio objects that do
211           not specify their own setting.
212

OBJECT METHODS

214       See http://monotone.ca/monotone.html for a complete description of the
215       mtn automate commands.
216
217       Methods that return data from the mtn subprocess do so via their first
218       argument. This argument is a reference to either a scalar or a list
219       depending upon whether the data returned by the method is raw data or a
220       list of items respectively. Methods that return lists of records,
221       rather than a simple list of scalar items, also provide the option of
222       returning the data as one raw chunk if the reference points to a scalar
223       rather than a list. Therefore:
224
225           $mtn->get_manifest_of(\$buffer);
226
227       would simply put the output from the `get_manifest_of' command into the
228       variable named $buffer, whereas:
229
230           $mtn->get_manifest_of(\@list);
231
232       would return the output as a list of records (actually anonymous hashes
233       to be precise). However:
234
235           $mtn->get_file(\$buffer, $file_id);
236
237       will always need a reference to a scalar and:
238
239           $mtn->select(\@list, $selector);
240
241       will always need a reference to a list (each item is just a string
242       containing a revision id rather than a record).
243
244       The one exception to the above is the $mtn->generate_key() method,
245       which expects a reference to either a scalar or a hash as it only ever
246       returns one record's worth of information.
247
248       The remaining arguments depend upon the mtn command being used.
249
250       The following methods are provided:
251
252       $mtn->ancestors(\@list, $revision_id ...)
253           Get a list of ancestors for the specified revisions.
254
255       $mtn->ancestry_difference(\@list, $new_revision_id [, $old_revision_id
256       ...])
257           Get a list of ancestors for the specified revision, that are not
258           also ancestors for the specified old revisions.
259
260       $mtn->branches(\@list)
261           Get a list of branches.
262
263       $mtn->cert($revision_id, $name, $value)
264           Add the specified certificate to the specified revision.
265
266       $mtn->certs(\$buffer | \@list, $revision_id)
267           Get all the certificates for the specified revision. If \$buffer is
268           passed then the output from the command is simply placed into the
269           variable. However if \@list is passed then the output is returned
270           as a list of anonymous hashes, each one containing the following
271           fields:
272
273               key       - The signer of the cert. Prior to version 0.45 of
274                           Monotone this was in the form of typically an email
275                           address. From version 0.45 onwards this is now a
276                           hash. (feature: MTN_HASHED_SIGNATURES)
277               signature - Signer status. Values can be one of "ok", "bad" or
278                           "unknown".
279               name      - The cert name.
280               value     - Its value.
281               trust     - Its trust status. Values can be one of "trusted" or
282                           "untrusted".
283
284       $mtn->checkout(\@options, $ws_dir)
285           Create a new workspace in the directory specified by $ws_dir. One
286           can optionally specify the branch and revision if required. Please
287           note that this command changes the current working directory of the
288           mtn subprocess. If this is not what you want then the subprocess
289           can simply be restarted by using the $mtn->closedown() method.
290
291           The $options argument is a list of valid options, with some having
292           arguments. For example, one could call this method specifying all
293           of the options like this:
294
295               $mtn->checkout(["branch"   => "net.venge.monotone",
296                               "revision" => "t:monotone-0.35",
297                               "move-conflicting-paths"],
298                              "my-mtn-ws");
299
300           (feature: MTN_CHECKOUT)
301
302       $mtn->children(\@list, $revision_id)
303           Get a list of children for the specified revision.
304
305       $mtn->closedown()
306           If started then stop the mtn subprocess. Please note that the mtn
307           subprocess is automatically stopped when the related object is
308           destroyed. This method is provided so that application developers
309           can conveniently control when the subprocess is active.
310
311       $mtn->common_ancestors(\@list, $revision_id ...)
312           Get a list of revisions that are all ancestors of the specified
313           revision(s).
314
315       $mtn->content_diff(\$buffer[, \@options[, $revision_id1,
316       $revision_id2[, $file_name ...]]])
317           Get the difference between the two specified revisions, optionally
318           limiting the output by using the specified options and file
319           restrictions. If the second revision id is undefined then the
320           workspace's current revision is used. If both revision ids are
321           undefined then the workspace's current and base revisions are used.
322           If no file names are listed then differences in all files are
323           reported.
324
325           The $options argument is a list of valid options, with some having
326           arguments. For example, one could call this method specifying all
327           of the options like this (feature: MTN_CONTENT_DIFF_EXTRA_OPTIONS):
328
329               $mtn->content_diff(\@result,
330                                  ["depth"   => 1,
331                                   "exclude" => "work.cc",
332                                   "reverse",
333                                   "with-header"],
334                                  "unix");
335
336       $mtn->db_get(\$buffer, $domain, $name)
337           Get the value of a database variable.
338
339           (feature: MTN_DB_GET, obsolete: replaced by
340           $mtn->get_db_variables())
341
342       $mtn->db_locked_condition_detected()
343           Check to see if the Monotone database was locked the last time a
344           command was issued.
345
346       $mtn->descendents(\@list, $revision_id ...)
347           Get a list of descendants for the specified revision(s).
348
349       $mtn->drop_attribute($path[, $key])
350           Drop attributes from the specified file or directory, optionally
351           limiting it to the specified attribute.
352
353           (feature: MTN_DROP_ATTRIBUTE)
354
355       $mtn->drop_db_variables($domain[, $name])
356           Drop variables from the specified domain, optionally limiting it to
357           the specified variable.
358
359           (feature: MTN_DROP_DB_VARIABLES)
360
361       $mtn->drop_public_key($key_id)
362           Drop the public key from the database for the specified key id
363           (either in the form of a name or hash id).
364
365           (feature: MTN_DROP_PUBLIC_KEY)
366
367       $mtn->erase_ancestors(\@list[, $revision_id ...])
368           For a given list of revisions, weed out those that are ancestors to
369           other revisions specified within the list.
370
371       $mtn->erase_descendants(\@list[, $revision_id ...])
372           For a given list of revisions, weed out those that are descendants
373           to other revisions specified within the list.
374
375           (feature: MTN_ERASE_DESCENDANTS)
376
377       $mtn->file_merge(\$buffer, $left_revision_id, $left_file_name,
378       $right_revision_id, $right_file_name)
379           Get the result of merging two files, both of which are on separate
380           revisions.
381
382           (feature: MTN_FILE_MERGE)
383
384       $mtn->generate_key(\$buffer | \%hash, $key_id, $pass_phrase)
385           Generate a new key for use within the database. If \$buffer is
386           passed then the output from the command is simply placed into the
387           variable. However if \%hash is passed then the output is returned
388           as one anonymous hash containing the following fields:
389
390               Prior to version 0.44 of Monotone:
391                   name              - The name of the key.
392                   public_hash       - The public hash code.
393                   private_hash      - The private hash code.
394                   public_locations  - A list of locations for the public hash
395                                       code. Values can be one of "database" or
396                                       "keystore".
397                   private_locations - A list of locations for the private hash
398                                       code. Values can be one of "database" or
399                                       "keystore".
400
401               From version 0.44 of Monotone onwards
402               (feature: MTN_COMMON_KEY_HASH):
403                   name              - The name of the key.
404                   hash              - The hash code (both public and private).
405                   public_locations  - A list of locations for the public hash
406                                       code. Values can be one of "database" or
407                                       "keystore".
408                   private_locations - A list of locations for the private hash
409                                       code. Values can be one of "database" or
410                                       "keystore".
411
412           Also known as $mtn->genkey().
413
414           (feature: MTN_GENERATE_KEY)
415
416       $mtn->get_attributes(\$buffer | \@list, $file_name[, $revision_id])
417           Get the attributes of the specified file under the specified
418           revision. If the revision id is undefined then the current
419           workspace revision is used. If \$buffer is passed then the output
420           from the command is simply placed into the variable. However if
421           \@list is passed then the output is returned as a list of anonymous
422           hashes, each one containing the following fields:
423
424               attribute - The name of the attribute.
425               value     - The value of the attribute.
426               state     - The status of the attribute. Values can be one of
427                           "added", "changed", "dropped" or "unchanged".
428
429           The ability to specify a revision id, thus being able to call this
430           method outside of a workspace, was introduced in Monotone version
431           13.1 (feature: MTN_GET_ATTRIBUTES_TAKING_OPTIONS).
432
433           Also known as $mtn->attributes().
434
435           (feature: MTN_GET_ATTRIBUTES)
436
437       $mtn->get_base_revision_id(\$buffer)
438           Get the id of the revision upon which the workspace is based.
439
440       $mtn->get_content_changed(\@list, $revision_id, $file_name)
441           Get a list of revisions in which the content was most recently
442           changed, relative to the specified revision.
443
444       $mtn->get_corresponding_path(\$buffer, $source_revision_id, $file_name,
445       $target_revision_id)
446           For the specified file name in the specified source revision,
447           return the corresponding file name for the specified target
448           revision.
449
450       $mtn->get_current_revision(\$buffer | \@list[, \@options[, $path ...]])
451           Get the revision information for the current revision, optionally
452           limiting the output by using the specified options and file
453           restrictions. If \$buffer is passed then the output from the
454           command is simply placed into the variable. However if \@list is
455           passed then the output is returned in exactly the same format as
456           for the $mtn->get_revision() method.
457
458           The $options argument is a list of valid options, with some having
459           arguments. For example, one could call this method specifying all
460           of the options like this:
461
462               $mtn->get_current_revision(\@result,
463                                          ["depth"   => 1,
464                                           "exclude" => "work.cc"],
465                                          "unix");
466
467           (feature: MTN_GET_CURRENT_REVISION)
468
469       $mtn->get_current_revision_id(\$buffer)
470           Get the id of the revision that would be created if an unrestricted
471           commit was done in the workspace.
472
473       $mtn->get_db_name()
474           Return the file name of the Monotone database as given to the
475           constructor. If no such name was given then undef is returned.
476
477       $mtn->get_db_variables(\$buffer | \@list[, $domain])
478           Get the variables stored in the database, optionally limiting it to
479           the specified domain. If \$buffer is passed then the output from
480           the command is simply placed into the variable. However if \@list
481           is passed then the output is returned as a list of anonymous
482           hashes, each one containing the following fields:
483
484               domain - The domain name to which the variable belongs.
485               name   - The name of the variable.
486               value  - The value of the variable.
487
488           (feature: MTN_GET_DB_VARIABLES)
489
490       $mtn->get_error_message()
491           Return the last error message received from the mtn subprocess. An
492           empty string is returned if no error has occurred yet.
493
494           Please note that the error message is never cleared but just
495           overwritten.  Therefore one can use this method to determinate the
496           nature of an error once it has been discovered but not to actually
497           detect it in the first place. Use either an error handler or check
498           the return status of methods to detect error conditions.
499
500       $mtn->get_extended_manifest_of(\$buffer | \@list, $revision_id)
501           Get the extended manifest for the specified revision. If \$buffer
502           is passed then the output from the command is simply placed into
503           the variable. However if \@list is passed then the output is
504           returned as a list of anonymous hashes, each one containing one or
505           more of the following fields:
506
507               type         - The type of entry. Values can be one of "file" or
508                              "directory".
509               name         - The name of the directory or file.
510               file_id      - The id of the file. This field is only present if
511                              type is set to "file".
512               birth        - The id of the revision in which the node was first
513                              added.
514               content_mark - The id of the revision in which the contents of
515                              the file was last changed.
516               path_mark    - The id of the revision in which the file was last
517                              renamed.
518               size         - The size of the file's contents in bytes.
519               attributes   - A list of attributes for the file or directory.
520                              Each entry has the following fields:
521                                  attribute - The name of the attribute.
522                                  value     - The value of the attribute.
523               attr_mark    - A list of attributes and when they were lasted
524                              changed. Each entry has the following fields:
525                                  attribute   - The name of the attribute.
526                                  revision_id - The id of the revision in which
527                                                the attributes value was last
528                                                changed.
529               dormant_attr - A list of attributes that have previously been
530                              deleted.
531
532           (feature: MTN_GET_EXTENDED_MANIFEST_OF)
533
534       $mtn->get_file(\$buffer, $file_id)
535           Get the contents of the file referenced by the specified file id.
536
537       $mtn->get_file_of(\$buffer, $file_name[, $revision_id])
538           Get the contents of the specified file under the specified
539           revision. If the revision id is undefined then the current
540           workspace revision is used.
541
542       $mtn->get_file_size(\$buffer, $file_id)
543           Get the size of the file referenced by the specified file id.
544
545           (feature: MTN_GET_FILE_SIZE)
546
547       $mtn->get_manifest_of(\$buffer | \@list[, $revision_id])
548           Get the manifest for the current or specified revision. If \$buffer
549           is passed then the output from the command is simply placed into
550           the variable. However if \@list is passed then the output is
551           returned as a list of anonymous hashes, each one containing the
552           following fields:
553
554               type       - The type of entry. Values can be one of "file" or
555                            "directory".
556               name       - The name of the directory or file.
557               file_id    - The id of the file. This field is only present if
558                            type is set to "file".
559               attributes - A list of attributes for the file or directory. Each
560                            entry has the following fields:
561                                attribute - The name of the attribute.
562                                value     - The value of the attribute.
563
564       $mtn->get_option(\$buffer, $option_name)
565           Get the value of an option stored in a workspace's _MTN directory.
566
567       $mtn->get_pid()
568           Return the process id of the mtn subprocess spawned by this class.
569           Zero is returned if no subprocess is thought to exist. Also if the
570           subprocess should exit unexpectedly then this method will carry on
571           returning its process id until the $mtn->closedown() method is
572           called.
573
574       $mtn->get_public_key(\$buffer, $key_id)
575           Get the public key for the specified key id (either in the form of
576           a name or hash id).
577
578           (feature: MTN_GET_PUBLIC_KEY)
579
580       $mtn->get_revision(\$buffer | \@list, $revision_id)
581           Get the revision information for the current or specified revision.
582           If \$buffer is passed then the output from the command is simply
583           placed into the variable. However if \@list is passed then the
584           output is returned as a list of anonymous hashes, each one
585           containing a variety of fields depending upon the type of entry:
586
587               type - The type of entry. Values can be one of "add_dir",
588                      "add_file", "clear", "delete", "new_manifest",
589                      "old_revision", "patch", "rename" or "set".
590
591               add_dir:
592                   name - The name of the directory that was added.
593
594               add_file:
595                   name    - The name of the file that was added.
596                   file_id - The id of the file.
597
598               clear:
599                   name      - The name of the file to which the attribute
600                               applied.
601                   attribute - The name of the attribute that was cleared.
602
603               delete:
604                   name - The name of the directory or file that was deleted.
605
606               new_manifest:
607                   manifest_id - The id of the revision's new manifest.
608
609               old_revision:
610                   revision_id - The id of the parent revision.
611
612               patch:
613                   name         - The name of the file that was changed.
614                   from_file_id - The file's old id.
615                   to_file_id   - The file's new id.
616
617               rename:
618                   from_name - The name of the file before the rename.
619                   to_name   - The name of the file after the rename.
620
621               set:
622                   name      - The name of the file that had an attribute set.
623                   attribute - The name of the attribute that was set.
624                   value     - The value that the attribute was set to.
625
626       $mtn->get_service_name()
627           Return the service name of the Monotone server as given to the
628           constructor.
629
630           (feature: MTN_REMOTE_CONNECTIONS)
631
632       $mtn->get_workspace_root(\$buffer)
633           Get the absolute path for the current workspace's root directory.
634
635           (feature: MTN_GET_WORKSPACE_ROOT)
636
637       $mtn->get_ws_path()
638           Return the the workspace's base directory as either given to the
639           constructor or deduced from the current workspace. If neither
640           condition holds true then undef is returned. Please note that the
641           workspace's base directory may differ from that given to the
642           constructor if the specified workspace path is actually a
643           subdirectory within that workspace.
644
645       $mtn->graph(\$buffer | \@list)
646           Get a complete ancestry graph of the database. If \$buffer is
647           passed then the output from the command is simply placed into the
648           variable. However if \@list is passed then the output is returned
649           as a list of anonymous hashes, each one containing the following
650           fields:
651
652               revision_id - The id of a revision.
653               parent_ids  - A list of parent revision ids.
654
655       $mtn->heads(\@list[, $branch_name])
656           Get a list of revision ids that are heads on the specified branch.
657           If no branch is given then the workspace's branch is used.
658
659       $mtn->identify(\$buffer, $file_name)
660           Get the file id, i.e. hash, of the specified file.
661
662       $mtn->ignore_suspend_certs($ignore)
663           Determine whether revisions with a suspend certificate are to be
664           ignored or not. If $ignore is true then suspend certificates are
665           ignored, otherwise they are honoured (in which case any suspended
666           revisions and branches that only have suspended revisions on their
667           heads will not be listed). The default behaviour is to honour
668           suspend certificates.
669
670           (feature: MTN_IGNORING_OF_SUSPEND_CERTS)
671
672       $mtn->interface_version(\$buffer)
673           Get the version of the mtn automate interface.
674
675       $mtn->inventory(\$buffer | \@list[, \@options[, $path ...]])
676           Get the inventory for the current workspace, optionally limiting
677           the output by using the specified options and file restrictions. If
678           \$buffer is passed then the output from the command is simply
679           placed into the variable. However if \@list is passed then the
680           output is returned as a list of anonymous hashes, each one
681           containing one or more of the following fields:
682
683               Prior to version 0.37 of Monotone:
684                   status       - The three inventory status characters for the
685                                  file or directory.
686                   crossref_one - The first cross-referencing number.
687                   crossref_two - The second cross-referencing number.
688                   name         - The name of the file or directory.
689
690               From version 0.37 of Monotone onwards
691               (feature: MTN_INVENTORY_IN_IO_STANZA_FORMAT):
692                   path     - The name of the file or directory.
693                   old_type - The type of the entry in the base manifest. Values
694                              can be one of "directory", "file" or "none".
695                   new_type - The type of the entry in the revision manifest.
696                              Values can be one of "directory", "file" or
697                              "none".
698                   fs_type  - The type of the entry on the file system. Values
699                              can be one of "directory", "file" or "none".
700                   old_path - The old name of the file or directory if it has
701                              been renamed in the revision manifest.
702                   new_path - The new name of the file or directory if it has
703                              been renamed in the revision manifest.
704                   birth    - The id of the revision in which the node was first
705                              added. Only from version 0.41 of Monotone
706                              onwards. (feature: MTN_INVENTORY_WITH_BIRTH_ID)
707                   status   - A list of status flags. Values can be one of
708                              "added", "dropped", "ignored", "invalid", "known",
709                              "missing", "rename_source", "rename_target" or
710                              "unknown".
711                   changes  - A list of change flags. Values can be one of
712                              "attrs" or "content".
713
714           Please note that some fields are not used by all entries, in which
715           case they are not present (use Perl's exists() function to
716           determine their presence and not defined()).
717
718           The $options argument is a list of valid options, with some having
719           arguments. For example, one could call this method specifying all
720           of the options like this (feature: MTN_INVENTORY_TAKING_OPTIONS):
721
722               $mtn->inventory(\@result,
723                               ["depth"   => 1,
724                                "exclude" => "work.cc",
725                                "no-corresponding-renames",
726                                "no-ignored",
727                                "no-unknown",
728                                "no-unchanged"],
729                               "unix");
730
731       $mtn->keys(\$buffer | \@list)
732           Get a list of all the keys known to mtn. If \$buffer is passed then
733           the output from the command is simply placed into the variable.
734           However if \@list is passed then the output is returned as a list
735           of anonymous hashes, each one containing the following fields:
736
737               Prior to version 0.44 of Monotone:
738                   name              - The name of the key.
739                   public_hash       - The public hash code.
740                   private_hash      - The private hash code.
741                   public_locations  - A list of locations for the public hash
742                                       code. Values can be one of "database" or
743                                       "keystore".
744                   private_locations - A list of locations for the private hash
745                                       code. Values can be one of "database" or
746                                       "keystore". This field is only present if
747                                       there is a private key.
748
749               Version 0.44 of Monotone (feature: MTN_COMMON_KEY_HASH):
750                   name              - The name of the key.
751                   hash              - The hash code (both public and private).
752                   public_locations  - A list of locations for the public hash
753                                       code. Values can be one of "database" or
754                                       "keystore".
755                   private_locations - A list of locations for the private hash
756                                       code. Values can be one of "database" or
757                                       "keystore". This field is only present if
758                                       there is a private key.
759
760               From version 0.45 of Monotone onwards
761               (feature: MTN_HASHED_SIGNATURES):
762                   given_name        - The name of the key as given when it was
763                                       created.
764                   hash              - The hash code (both public and private).
765                   local_name        - The local name of the key as returned by
766                                       the get_local_key_name() hook.
767                   public_locations  - A list of locations for the public hash
768                                       code. Values can be one of "database" or
769                                       "keystore".
770                   private_locations - A list of locations for the private hash
771                                       code. Values can be one of "database" or
772                                       "keystore". This field is only present if
773                                       there is a private key.
774
775           Please note that some fields are not used by all entries, in which
776           case they are not present (use Perl's exists() function to
777           determine their presence and not defined()).
778
779       $mtn->leaves(\@list)
780           Get a list of leaf revisions.
781
782       $mtn->log(\@list[, \@options[, $file_name]])
783           Get a list of revision ids that form a log history for an entire
784           project, optionally limiting the output by using the specified
785           options and file name restrictions.
786
787           The $options argument is a list of valid options, with some having
788           arguments. For example, one could call this method specifying all
789           of the options like this:
790
791               $mtn->log(\@list,
792                         ["clear-from",
793                          "clear-to",
794                          "from"       => "h:",
795                          "last"       => 20,
796                          "next"       => 30,
797                          "no-merges"
798                          "to"         => "t:test-checkin"],
799                         "Makefile.am");
800
801           (feature: MTN_LOG)
802
803       $mtn->lua(\$buffer, $lua_function[, $argument ...])
804           Call the specified LUA function with any required arguments.
805
806           (feature: MTN_LUA)
807
808       $mtn->packet_for_fdata(\$buffer, $file_id)
809           Get the contents of the file referenced by the specified file id in
810           packet format.
811
812       $mtn->packet_for_fdelta(\$buffer, $from_file_id, $to_file_id)
813           Get the file delta between the two files referenced by the
814           specified file ids in packet format.
815
816       $mtn->packet_for_rdata(\$buffer, $revision_id)
817           Get the contents of the revision referenced by the specified
818           revision id in packet format.
819
820       $mtn->packets_for_certs(\$buffer, $revision_id)
821           Get all the certs for the revision referenced by the specified
822           revision id in packet format.
823
824       $mtn->parents(\@list, $revision_id)
825           Get a list of parents for the specified revision.
826
827       $mtn->pull(\$buffer | \@list[,@options[, $uri]])
828           Synchronises database changes from the specified remote server to
829           the local database but not in the other direction. Other details
830           are identical to the $mtn->sync() method.
831
832           (feature: MTN_SYNCHRONISATION)
833
834       $mtn->push(\$buffer | \@list[,@options[, $uri]])
835           Synchronises database changes from the local database to the
836           specified remote server but not in the other direction. Other
837           details are identical to the $mtn->sync() method.
838
839           (feature: MTN_SYNCHRONISATION)
840
841       $mtn->put_file(\$buffer, $base_file_id, \$contents)
842           Put the specified file contents into the database, optionally
843           basing it on the specified file id (this is used for delta
844           encoding). The file id is returned.
845
846       $mtn->put_public_key($public_key)
847           Put the specified public key data into the database.
848
849           (feature: MTN_PUT_PUBLIC_KEY)
850
851       $mtn->put_revision(\$buffer, \$contents)
852           Put the specified revision data into the database. The revision id
853           is returned. Please note that any newly created revisions have no
854           certificates associated with them and so these have to be added
855           using the $mtn->cert() method.
856
857       $mtn->read_packets($packet_data)
858           Decode and store the specified packet data in the database.
859
860           (feature: MTN_READ_PACKETS)
861
862       $mtn->register_error_handler($severity[, $handler [, $client_data]])
863           Registers an error handler for the object rather than the class.
864           For further details please see the description of the class method.
865
866       $mtn->register_db_locked_handler([$handler[, $client_data]])
867           Registers a database locked handler for the object rather than the
868           class. For further details please see the description of the class
869           method.
870
871       $mtn->register_io_wait_handler([$handler, $timeout [, $client_data]])
872           Registers an I/O wait handler for the object rather than the class.
873           For further details please see the description of the class method.
874
875       $mtn->register_stream_handle($stream[, $handle]])
876           Registers the file handle specified in $handle so that it will
877           receive data from the specified mtn output stream. $stream can be
878           one of MTN_P_STREAM or MTN_T_STREAM. If no file handle is given
879           then any existing file handle is unregistered for that stream.
880
881           Please note:
882
883           1)  It is vitally important that if you register some sort of pipe
884               or socket to receive mtn stream output, that any data sent down
885               it is read immediately and independently from the code calling
886               the method generating the output (either by using a thread or
887               another process). Not doing so could easily cause a deadlock
888               situation to occur where the method stops processing, waiting
889               for the pipe or socket to empty before proceeding.
890
891           2)  The output streams are largely sent as received from the mtn
892               subprocess (please refer to the Monotone documentation for
893               further details on the format). The only difference is that
894               since the `l' or last message (which marks the end of a
895               command's output) is only sent once by mtn, this class
896               duplicates it onto any registered stream so that the reader
897               knows when there is no more data for a command.
898
899           3)  In order to get the stream constants into your namespace you
900               need to use the following to load in this library.
901
902                   use Monotone::AutomateStdio qw(:streams);
903
904           (feature: MTN_STREAM_IO)
905
906       $mtn->roots(\@list)
907           Get a list of root revisions, i.e. revisions with no parents.
908
909       $mtn->select(\@list, $selector)
910           Get a list of revision ids that match the specified selector.
911
912       $mtn->set_attribute($path, $key, $value)
913           Set an attribute on the specified file or directory.
914
915           (feature: MTN_SET_ATTRIBUTE)
916
917       $mtn->set_db_variable($domain, $name, $value)
918           Set the value of a database variable.
919
920           Also known as $mtn->db_set().
921
922           (feature: MTN_SET_DB_VARIABLE)
923
924       $mtn->show_conflicts(\$buffer | \@list[, $branch][, $left_revision_id,
925       $right_revision_id])
926           Get a list of conflicts between the first two head revisions on the
927           current branch, optionally one can specify both head revision ids
928           and the name of the branch that they reside on. If \$buffer is
929           passed then the output from the command is simply placed into the
930           variable. However if \@list is passed then the output is returned
931           as a list of anonymous hashes, each one containing one or more of
932           the following fields:
933
934               ancestor          - The id of the common ancestor revision for
935                                   both revisions in conflict.
936               ancestor_file_id  - The common ancestor file id for both files in
937                                   conflict.
938               ancestor_name     - The name of the ancestor file or directory.
939               attr_name         - The name of the Monotone file or directory
940                                   attribute that is in conflict.
941               conflict          - The nature of the conflict. Values can be one
942                                   of "attribute", "content",
943                                   "directory_loop", "duplicate_name",
944                                   "invalid_name", "missing_root",
945                                   "multiple_names", "orphaned_directory" or
946                                   "orphaned_file".
947               left              - The id of the left hand revision that is in
948                                   conflict.
949               left_attr_value   - The value of the attribute on the file or
950                                   directory in the left hand revision.
951               left_file_id      - The id of the file in the left hand revision.
952               left_name         - The name of the file or directory in the left
953                                   hand revision.
954               left_type         - The type of conflict relating to the file or
955                                   directory in the left hand revision. Values
956                                   can be one of "added directory",
957                                   "added file", "deleted directory",
958                                   "pivoted root", "renamed directory" or
959                                   "renamed file".
960               node_type         - The type of manifest node. Values can be one
961                                   of "file" or "directory".
962               resolved_internal - Only present if the conflict can be resolved
963                                   internally by Monotone during the merge
964                                   process.
965               right             - The id of the right hand revision that is in
966                                   conflict.
967               right_attr_state  - The state of the attribute in the right hand
968                                   revision. Values can only be "dropped".
969               right_attr_value  - The value of the attribute on the file or
970                                   directory in the right hand revision.
971               right_file_id     - The id of the file in the right hand
972                                   revision.
973               right_name        - The name of the file or directory in the
974                                   right hand revision.
975               right_type        - The type of conflict relating to the file or
976                                   directory in the left revision. Values are as
977                                   documented for left_type.
978
979           Please note that some fields are not used by all entries, in which
980           case they are not present (use Perl's exists() function to
981           determine their presence and not defined()).
982
983           (feature: MTN_SHOW_CONFLICTS)
984
985       $mtn->supports($feature)
986           Determine whether a certain feature is available with the version
987           of Monotone that is currently being used by this object. The list
988           of valid features are:
989
990               MTN_CHECKOUT
991               MTN_COMMON_KEY_HASH
992               MTN_CONTENT_DIFF_EXTRA_OPTIONS
993               MTN_DB_GET
994               MTN_DROP_ATTRIBUTE
995               MTN_DROP_DB_VARIABLES
996               MTN_DROP_PUBLIC_KEY
997               MTN_ERASE_DESCENDANTS
998               MTN_FILE_MERGE
999               MTN_GENERATE_KEY
1000               MTN_GET_ATTRIBUTES
1001               MTN_GET_ATTRIBUTES_TAKING_OPTIONS
1002               MTN_GET_CURRENT_REVISION
1003               MTN_GET_DB_VARIABLES
1004               MTN_GET_EXTENDED_MANIFEST_OF
1005               MTN_GET_FILE_SIZE
1006               MTN_GET_PUBLIC_KEY
1007               MTN_GET_WORKSPACE_ROOT
1008               MTN_HASHED_SIGNATURES
1009               MTN_IGNORING_OF_SUSPEND_CERTS
1010               MTN_INVENTORY_IN_IO_STANZA_FORMAT
1011               MTN_INVENTORY_TAKING_OPTIONS
1012               MTN_INVENTORY_WITH_BIRTH_ID
1013               MTN_K_SELECTOR
1014               MTN_LOG
1015               MTN_LUA
1016               MTN_M_SELECTOR
1017               MTN_P_SELECTOR
1018               MTN_PUT_PUBLIC_KEY
1019               MTN_READ_PACKETS
1020               MTN_REMOTE_CONNECTIONS
1021               MTN_SELECTOR_FUNCTIONS
1022               MTN_SELECTOR_MIN_FUNCTION
1023               MTN_SELECTOR_NOT_FUNCTION
1024               MTN_SELECTOR_OR_OPERATOR
1025               MTN_SET_ATTRIBUTE
1026               MTN_SET_DB_VARIABLE
1027               MTN_SHOW_CONFLICTS
1028               MTN_STREAM_IO
1029               MTN_SYNCHRONISATION
1030               MTN_SYNCHRONISATION_WITH_OUTPUT
1031               MTN_U_SELECTOR
1032               MTN_UPDATE
1033               MTN_W_SELECTOR
1034
1035           In order to get these constants into your namespace you need to use
1036           the following to load in this library.
1037
1038               use Monotone::AutomateStdio qw(:capabilities);
1039
1040           Please note that if you see (feature: ...) then this means that
1041           whatever is being discussed is only available if $mtn->supports()
1042           returns true for the specified feature.
1043
1044       $mtn->sync(\$buffer | \@list[,@options[, $uri]])
1045           Synchronises database changes between the local database and the
1046           specified remote server. $uri specifies the name of the server, the
1047           port, the database and the branch pattern to synchronise to, for
1048           example "mtn://code.monotone.ca:8000/monotone?net.venge.monotone*".
1049           If \$buffer is passed then the output from the command is simply
1050           placed into the variable. However if \@list is passed then the
1051           output is returned as a list of anonymous hashes, each one
1052           containing one or more of the following fields (feature:
1053           MTN_SYNCHRONISATION_WITH_OUTPUT):
1054
1055               key              - The signing key id for the current item.
1056               receive_cert     - The name of the certificate that has just been
1057                                  received.
1058               receive_key      - The id of the key that has just been received.
1059               receive_revision - The id of the revision that has just been
1060                                  received.
1061               revision         - The id of the revision relating to the current
1062                                  item.
1063               send_cert        - The name of the certificate that has just been
1064                                  sent.
1065               send_key         - The id of the key that has just been sent.
1066               send_revision    - The id of the revision that has just been
1067                                  sent.
1068               value            - The value of the certificate.
1069
1070           The $options argument is a list of valid options, with some having
1071           arguments. For example, one could call this method specifying all
1072           of the options like this:
1073
1074               $mtn->sync(\$buffer,
1075                          ["dry-run",
1076                           "exclude"             => "experiments.hacks",
1077                           "key-to-push"         => "me@mydomain.com",
1078                           "max-netsync-version" => 2,
1079                           "min-netsync-version" => 1,
1080                           "set-default"],
1081                          "mtn://code.monotone.ca/monotone?net.venge.monotone");
1082
1083           (feature: MTN_SYNCHRONISATION)
1084
1085       $mtn->tags(\$buffer | \@list[, $branch_pattern])
1086           Get all the tags attached to revisions on branches that match the
1087           specified branch pattern. If no pattern is given then all branches
1088           are searched. If \$buffer is passed then the output from the
1089           command is simply placed into the variable. However if \@list is
1090           passed then the output is returned as a list of anonymous hashes,
1091           each one containing the following fields:
1092
1093               tag         - The name of the tag.
1094               revision_id - The id of a revision that the tag is attached to.
1095               signer      - The signer of the tag. Prior to version 0.45 of
1096                             Monotone this was in the form of typically an email
1097                             address. From version 0.45 onwards this is now a
1098                             hash. (feature: MTN_HASHED_SIGNATURES)
1099               branches    - A list of all branches that contain this revision.
1100
1101       $mtn->toposort(\@list[, $revision_id ...])
1102           Sort the specified revision ids such that the ancestors come out
1103           first.
1104
1105       $mtn->update([@options])
1106           Updates the current workspace to the specified revision and
1107           possible branch. If no options are specified then the workspace is
1108           updated to the head revision of the current branch.
1109
1110           The $options argument is a list of valid options, with some having
1111           arguments. For example, one could call this method specifying all
1112           of the options like this:
1113
1114               $mtn->update(["branch"                  => "experiments.hacks",
1115                             "move-conflicting-paths",
1116                             "revision"                => "h:"]);
1117
1118           (feature: MTN_UPDATE)
1119

RETURN VALUE

1121       Except for those methods listed below, all remaining methods return a
1122       boolean success indicator, true for success or false for failure.
1123
1124       The following constructors return Monotone::AutomateStdio objects:
1125
1126           Monotone::AutomateStdio->new()
1127           Monotone::AutomateStdio->new_from_db()
1128           Monotone::AutomateStdio->new_from_service()
1129           Monotone::AutomateStdio->new_from_ws()
1130
1131       The following method returns true or false (but it does not indicate
1132       success or failure):
1133
1134           $mtn->db_locked_condition_detected()
1135
1136       The following method returns an integer:
1137
1138           $mtn->get_pid()
1139
1140       The following methods return a string or undef:
1141
1142           $mtn->get_db_name()
1143           $mtn->get_error_message()
1144           $mtn->get_ws_path()
1145
1146       The following methods do not return anything:
1147
1148           Monotone::AutomateStdio->register_db_locked_handler()
1149           Monotone::AutomateStdio->register_error_handler()
1150           Monotone::AutomateStdio->register_io_wait_handler()
1151           Monotone::AutomateStdio->register_stream_handle()
1152           Monotone::AutomateStdio->suppress_utf8_conversion()
1153           $mtn->closedown()
1154
1155       Please note that the boolean true and false values used by this class
1156       are defined as 1 and undef respectively.
1157

EXAMPLES

1159   Detecting Warnings And Errors
1160       Errors cause exceptions to be thrown. Warnings cause the responsible
1161       method to return false rather than true.
1162
1163       Therefore warnings would typically be detected by using code like this:
1164
1165           $mtn->get_file(\$data, $file_id)
1166               or die('$mtn->get_file() failed with: '
1167                      . $mtn->get_error_message());
1168
1169       However this can get clumsy and cluttered after a while, especially
1170       when the calling application knows that there is very little likelihood
1171       of there being a problem. Having exceptions being thrown for warnings
1172       as well as errors may be a better approach. By doing:
1173
1174           Monotone::AutomateStdio->register_error_handler
1175               (MTN_SEVERITY_ALL,
1176                sub
1177                {
1178                    my($severity, $message) = @_;
1179                    die($message);
1180                });
1181
1182       or more tersely:
1183
1184           Monotone::AutomateStdio->register_error_handler
1185               (MTN_SEVERITY_ALL, sub { die($_[1]); });
1186
1187       at the beginning of your application will mean that all errors and
1188       warnings detected by this class will generate an exception, thus making
1189       the checking of a method's return status redundant.
1190
1191   Silently Retrying Operations When The Database Is Locked
1192       If the Monotone database is locked then, by default, this class will
1193       report that condition as a warning. However it may be more convenient
1194       to ask this class to silently retry the operation until it succeeds.
1195       This can easily be done by using the database locked handler as
1196       follows:
1197
1198           Monotone::AutomateStdio->register_db_locked_handler
1199               (sub { sleep(1); return 1; });
1200
1201       This will mean that should any database locked conditions occur then
1202       this class will silently sleep for one second before retrying the
1203       operation.
1204
1205   Dealing With Processing Lockouts And Delays
1206       Some requests sent to the mtn subprocess can take several seconds to
1207       complete and consequently this class will take that amount of time,
1208       plus a very small processing overhead, to return. Whilst one can get
1209       around this by using threads, another way is to register an I/O wait
1210       handler. For example:
1211
1212           Monotone::AutomateStdio->register_io_wait_handler
1213               (sub { WindowManager->instance()->update_gui(); }, 1);
1214
1215       will instruct this class to update the user display every second whilst
1216       it is waiting for the mtn subprocess to finish processing a request.
1217

NOTES

1219   Using This Class With Monotone Workspaces
1220       Certain features are only available when used inside a Monotone
1221       workspace, so consequently this class does support the use of
1222       workspaces. However certain aspects of a workspace can affect the mtn
1223       subprocess. For example, when you run mtn in a workspace's subdirectory
1224       then all file name arguments get translated into paths relative to the
1225       workspace's root directory (i.e. given a path of
1226       /home/freddy/workspace/include/system.h when one runs "mtn log
1227       system.h" in the include directory the file name gets changed to
1228       include/system.h).
1229
1230       This makes perfect sense on the command line but possibly less so when
1231       using mtn from inside a GUI application where the directory in which
1232       the application was launched is not as relevant. This is why this class
1233       runs the mtn subprocess in specific directories depending upon how the
1234       object is constructed. If the object is constructed by calling
1235       Monotone::AutomateStdio->new() or
1236       Monotone::AutomateStdio->new_from_db() with the name of a database,
1237       then the mtn subprocess is run in the root directory, otherwise it is
1238       run in the workspace's root directory. This guarantees correct
1239       behaviour.
1240
1241       If however you want the mtn subprocess to run in the current directory
1242       within a workspace then simply use the
1243       Monotone::AutomateStdio->switch_to_ws_root() method to before calling
1244       Monotone::AutomateStdio->new() without specifying a database.
1245
1246       Any changing of directory does not affect the caller.
1247
1248   UTF-8 Handling
1249       A Monotone database may contain UTF-8 characters. These characters
1250       would most commonly appear inside text files but may also appear in the
1251       names of files, branches and even in certificates. Later versions of
1252       Perl have built in support for UTF-8 strings and can represent this
1253       sort of data quite naturally without the developer really having to
1254       worry too much. For this reason this class automatically converts any
1255       data sent between Perl and a mtn subprocess to and from Perl's internal
1256       UTF-8 string format and the standard binary octet notation.
1257
1258       There may be times when this built in conversion is inappropriate and
1259       so one can simply switch it off by using the
1260       Monotone::AutomateStdio->suppress_utf8_conversion() method to before
1261       calling Monotone::AutomateStdio->new().
1262
1263       Please note that not everything is converted when using this class's
1264       built in UTF-8 conversion mechanism. This is mainly for efficiency. For
1265       example, there is no real point in converting revision or file ids as
1266       these are always represented as forty character hexadecimal strings.
1267       Likewise packet data is not converted as this is always formatted to
1268       use seven bit ASCII. However there is one case where no conversion is
1269       done for reasons other than efficiency, and that is when handling file
1270       content data. Apart from differentiating between binary and non-binary
1271       data, Monotone just treats file content data as a sequence of bytes. In
1272       order to decide whether a file's contents contains UTF-8 data this may
1273       involve looking for assorted patterns in the data or checking the file
1274       name's extension, all of which being beyond the scope of this class.
1275       Also it is a good idea to treat file content data as a simple sequence
1276       of octets anyway. Probably the only time that one would need to worry
1277       about UTF-8 based file content data is when an application is
1278       displaying it using something like Gtk2 (the Gtk2 bindings for Perl
1279       uses Perl's internal UTF-8 flag to determine whether a string needs to
1280       be handled as a UTF-8 string or as a simple sequence of octets). In
1281       this case, once a file's contents has been determined to contain text
1282       oriented data, one can use Perl's decode_utf8() function to do the
1283       conversion. For more information on Perl's handling of UTF-8 please see
1284       the documentation for Encode.
1285
1286   Process Handling
1287       There are situations where this class does legitimately terminate the
1288       mtn subprocess (for example when a database locked condition is
1289       detected). When this happens the subprocess is reaped and its id is
1290       reset, i.e. the $mtn->get_pid() method returns 0. However if the
1291       subprocess should exit unexpectedly whilst processing a request then an
1292       exception is raised but no reaping or process id resetting takes place.
1293       Therefore an application using this class may wish to have a signal
1294       handler registered for SIGCHILD signals that can indirectly trigger a
1295       call to the $mtn->closedown() method or destroy the object concerned in
1296       the event of an error. In order to distinguish between legitimate
1297       terminations of the mtn subprocess and failures, simply compare the
1298       reaped process id against that returned by the $mtn->get_pid() method.
1299       If there is a match then there is a problem, otherwise, as far as this
1300       class is concerned, there is nothing to worry about.
1301
1302       Please note that all SIGPIPE signals are set to be ignored as soon as
1303       the first mtn subprocess is started by this class.
1304
1305   Use Of SIGALRM
1306       In order to reliably shutdown the mtn subprocess, alarm() is used to
1307       timeout calls to waitpid(), allowing this class to kill off any
1308       obstinate mtn subprocesses that remain after having their STDIN, STDOUT
1309       and STDERR file descriptors closed. Normally closing the file
1310       descriptors will cause a clean exit, I have never known it not to, at
1311       which point any alarms are reset without any SIGALRM signal being
1312       generated.
1313
1314   General
1315       When the output of a command from the automate stdio interface changes
1316       dramatically, it will probably not be possible to protect Perl
1317       applications from those changes. This class is a convenience wrapper
1318       rather than something that will totally divorce you from the automate
1319       stdio interface. Also the chances are you will want the new type of
1320       output anyway.
1321
1322       No work will be done to support versions of Monotone older than 0.35,
1323       so if you are in that position then I strongly suggest that you upgrade
1324       to a later version of Monotone (you will get all the new features and
1325       bug fixes, go on you know want them :-)). Also once the automate stdio
1326       interface has remained stable for some time, support may be dropped for
1327       older versions in order to aid maintenance and regression testing.
1328
1329       The $mtn->get_content_changed() method is very slow in Monotone
1330       versions 0.40 and 0.41.
1331

SEE ALSO

1333       http://monotone.ca
1334

BUGS

1336       Your mileage may vary if this class is used with versions of Monotone
1337       older than 0.35 (automate stdio interface version 4.3).
1338
1339       This class is not thread safe. If you wish to use this class in a
1340       multi-threaded environment then you either need to use a separate
1341       object per thread or use threads::lock to protect each method call.
1342

AUTHORS

1344       Anthony Cooper with contributions and ideas from Thomas Keller.
1345       Currently maintained by Anthony Cooper. Please report all faults and
1346       suggestions to <support@coosoft.plus.com>.
1347
1349       Copyright (C) 2008 by Anthony Cooper <aecooper@coosoft.plus.com>.
1350
1351       This library is free software; you can redistribute it and/or modify it
1352       under the terms of the GNU Lesser General Public License as published
1353       by the Free Software Foundation; either version 3 of the License, or
1354       (at your option) any later version.
1355
1356       This library is distributed in the hope that it will be useful, but
1357       WITHOUT ANY WARRANTY; without even the implied warranty of
1358       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
1359       General Public License for more details.
1360
1361       You should have received a copy of the GNU Lesser General Public
1362       License along with this library; if not, write to the Free Software
1363       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
1364       USA.
1365
1366
1367
1368perl v5.32.1                      2021-01-27        Monotone::AutomateStdio(3)
Impressum