btred

btred - non-interactive scriptable version of the tree editor TrEd

SYNOPSIS

  btred [-c config-file]
        [-t context] [-m|-I macro-file] [-e code] [-i init-code]
        [-N|-H] [-T] [-S | --no-save] [--knit] [-P] [-F]
        [-s strip-sfx] [-a append-sfx] [-p strip-prefix] [-r add-prefix]
        [-f out-fmt] [-n file-encoding] [-d terminal-encoding]
        [-W] [-q|-Q] [-D] [-V] [-L port] [-b hub]
        [-x extra_attribs] [-X gov,ord?,hide?] [-R]
        [-o script options -- ] [-l file-list] files...
or
  btred -u          for usage
  btred -h          for help
  btred --man       for the manual page

DESCRIPTION

btred is an off-line TrEd macro processor which applies macros on given files

OPTIONS

--macro-file|-m filename

File with macro definitions to load. If no macro-file is given, standard macro file (by default tred.mac) is used.

--include-macro-file|-I filename

A file containing additional set of macros to load. This option is typically used instead of --macro-file to allow loading macros both from filename and the default macro set (tred.mac). --macro-file can still be used in combination with --include-macro-file to supply a replacement for tred.mac.

--execute|-e code

Macro code to apply to given files. If no code is specified, btred expects a function called `autostart' to be defined in the used context and defaults to `autostart()' as the macro code.

The macro code may use all functions defined in a given macro file, the default macro file tred.def, plus all functions and methods from Fslib (see Fslib documentation).

Note, that a lot of information on the current node, file etc. can be obtained using some pre-defined macro from `tred.def'. The documentation for `tred.def' is a highly recommended reading for btred macro coder and macros defined there in should be prefered in all applicable situations.

As in TrEd, the following variables may be used in the macros:

$this - the current node (the root of the first tree in a file at the beginning)

$root - the root node of the current tree

$grp->{FSFile} - current FSFile object (see section on FSFile in Fslib documentation)

$grp->{treeNo} - current tree number

$grp->{macroContext} - current macro context

$FileChanged ($TredMacro::FileChanged) - macro may change this to 1 to indicate that the file should be saved at the end of the pocessing. This variable is called $FileNotSaved in older documentation. Both names are equally usable.

--initial-code|-i code

Code to be evaluated before any file is open.

--context|-t

Start in a given macro context (Perl package). The default context is `TredMacro'.

--preload-module|-M module-name

Preload a given Perl module at btred startup so as it is available to all macros (even if running in a safe compartment). This option may be specified more than once with different modules.

--filelist|-l file-list

Read a list of filenames to process from a given file (one filename per line). Files specified in a file-list are processed prior to files specified on the command-line. If file-list is a file with .fl extension, then the first line may contain a file-list name (as in TrEd). Moreover, unlike in other file-lists, filenames in .fl file-lists are asssumed to be relative to the file-list file location.

--glob|-g

Apply Perl glob function on the filename patterns given on the command-line. This expands possible wild-card patterns on each of the filename command-line argument as the standard Unix shell /bin/csh would do. This can not only help in a situation where the shell used doesn't support wildcard expansion, but can also be used to reduce the number of the command-line arguments passed to the process in cases where the argument list would after the shell-expansion exceed a system limit. By default, this flag is 'on' for the Windows platform and 'off' on all other systems.

--strip-prefix|-p regexp

Remove strings matching a given regexp from the beginning of filenames before saving.

--add-prefix|-r prefix

Prepend output filenames with a given prefix.

--strip-suffix|-s regexp

Strip strings matching a given regexp from the end of filenames.

--add-suffix|-a suffix

Append a given suffix to the filenames.

Format to use for files being saved.

--config-file|-c filename

TrEd configuration file (overrides ~/.tredrc).

--resource-dir|-Z dirname

Specifies resource path. This option can be repeated and overrides ResoucePath setting in the TrEd configuration file.

--all-trees|-T

Apply the macro code to all trees (wrapping the code into a

if ($root) { do {{ CODE }} while TredMacro::NextTree()
}

loop).

--all-nodes|-N

Apply the macro code tn all nodes (you still must use --all-trees or -T to aplly to all trees in a file) (wrapping the code into a

while ($this) { CODE ;
$this=$this-E<gt>following }";

loop).

--all-nonhidden-nodes|-H

Apply the macro code to all nodes except the hidden ones (you still must use --all-trees or -T to process all trees in a file). This option wraps the code into a

while ($this) { CODE ;
$this=$this-E<gt>following_visible(FS()) }";

loop).

--file-encoding|-n encoding

Allows to specify character encoding of input files (does not apply to XML files) and is probably only useful with Perl >= 5.8.

--terminal-encoding|-d encoding

Automatically apllies a given character encoding to all stdout and stderr output operations. Works only with Perl >= 5.8.

--save|-S

Unconditionally save files after macro code was applied. By default, files are saved only if the $FileChanged variable has been set to 1 within the macro code.

--knit|K ALL|NONE|name1,name2,...

If a file is saved, save/update also listed types of reffiles the file pulled data from. For the moment, this only makes sense with the PMLBackend which supports so called knitting, i.e. a method to pull certain data from external resources and push it back (with all changes) to the original position in the resource when saving the file. This option allows to list the types of resources (in PML the types are the reference names listed in the PML schema) which should be saved. Default is NONE. This type of resources doesn't include so called secondary files.

--no-save

Never ever save any files (this way you may protect your files from being saved even if applying a macro that modifies them and sets $TredMacro::FileChanged to 1).

--safe-mode|-F

Run macro code in a safe compartment restricting some operations that could be used by a malicious code writer to explore and compromise the user's environment and potentially the entire system. Most notably, this blocks most IO operations. NO WARRANTY! If unsure, don't run the macro code at all.

--csts-tree-attributes|-X gov,ord?,hide?

CSTS format is ``many in one''; there may be more tree structures in one file. This option can be used to specify which tree structure should be used. Provide a comma separated list consisting of names of node atributes corresponding to CSTS elements that contain the necessary information to build a tree out of a CSTS file. The first attribute should be an attribute containing the index of the governing node; the second one is optional and specifies the ordering attribute; the third one is also optional and if specified, it should be the attribute used to mark hidden nodes with the string 'hide'. If the third argument is specified as empty (i.e. there is a trailing comma), default to 'X_hide' with preset-value 'hide'.

Examples: -X govTR,dord - corresponds to elements <TRg> and <tfr> in CSTS

  -X govMD_c,ord,x_MD_c_hide 
                 - corresponds to <MDg src="c">, <r>, 
                   and <x name="MD_c_hide">).

--tectogrammatical-trees|-R

Build tectogrammatic trees from CSTS files.

--fs2csts-attributes|-x list

Comma separated list of FS attribute names that should be preserved as <x> elements when saving to CSTS.

--confing-file|-c filename

Use a given TrEd configuration file.

--preload-files|-P

Preload all given files into memory before applying the macros (DOES NOT WORK WITH RESTRICTED MODE).

--warn-only|-W

Do not stop (die) on errors, just warn.

--validate-fs|-V

Force Fslib to test validity of values assigned to @L (list) attributes in FS files.

--quiet|-q

Print only general processing information on stderr.

--very-quiet|-Q

Don't print anything to stderr at all (except for fatal errors).

--debugging|-D

Print a lot of debugging information on the stderr.

--server-port|-L port

Start btred server, listening on a given port; implies -P. Use a suitable client such as ntred to apply a macro code on the files possesed by the server.

--allow-host|-b hostname

Accept only connections from a given host when operating in the server-mode.

--extra-backends|-B backends

Comma separated list of user-defined IO-backend modules to load.

--no-secondary-files

Neither load or save ``secondary'' files. Normally, secondary files (if loaded) are saved along with their primary files (the exactly same file-name prefix/suffix processing and format apply to both the primary and secondary files). A secondary file is a file required by a (normal - primary) file to be loaded along with it; this is typical for files containing some form of a stand-off annotation where one tree is built upon another. Note however, that this doesn't include so called knitting - an operation where the stand-off annotation is handled by a IO backend and the resulting knitted file appears to btred as a single unit.

--lib

Prints path to module directory containing Fslib and other TrEd specific libraries and exit.

--usage|-u

Print a brief help message on usage and exits.

--help|-h

Prints the help page and exits.

--man

Displays the help as manual page.

AUTHOR

Petr Pajas <pajas@matfyz.cz>