.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MNI::DataDir 3" .TH MNI::DataDir 3 "2016-03-23" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" MNI::DataDir \- find directory containing static model data for a package .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use MNI::DataDir; \& \& $data_dir = MNI::DataDir::dir ($package_name); \& MNI::DataDir::check_data ($data_dir, \e@model_files); \& \& $install_dir = MNI::DataDir::install_dir ($package_name); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIMNI::DataDir\fR gives a standard method for applications to find static data (such as model files), and a standard interface for users to customize this search. This is to ensure that all our software acts in a consistent, predictable way. .PP From the programmer's perspective, using \fIMNI::DataDir\fR is quite simple: make a single call to \f(CW\*(C`MNI::DataDir::dir\*(C'\fR early in your program, and use the result from that to construct the names of all your static data files. You can also call \f(CW\*(C`MNI::DataDir::check_data\*(C'\fR to ensure that all required data files are present before proceeding. .PP For example, \f(CW\*(C`mritotal\*(C'\fR (part of the \s-1MNI\s0 AutoReg package) depends on several custom variations of the \s-1MNI\s0 Average Brain. Assume that all these files start with \f(CW\*(Aqaverage_305\*(Aq\fR, and end with \f(CW\*(Aq_mask.mnc\*(Aq\fR, \&\f(CW\*(Aq_16_blur.mnc\*(Aq\fR, etc. Code to find the model directory would be: .PP .Vb 1 \& $ModelDir = MNI::DataDir::dir (\*(Aqautoreg\*(Aq); .Ve .PP and to ensure that all the required model files are present: .PP .Vb 5 \& @files = (\*(Aqaverage_305_mask.mnc\*(Aq, \& \*(Aqaverage_305_16_blur.mnc\*(Aq, \& \*(Aqaverage_305_8_blur.mnc\*(Aq, \& \*(Aqaverage_305_8_dxyz.mnc\*(Aq); \& MNI::DataDir::check_data ($ModelDir, \e@files); .Ve .PP (In reality, \f(CW\*(C`mritotal\*(C'\fR allows a user-defined model, so the \&\f(CW\*(Aqaverage_305\*(Aq\fR string isn't fixed. But that's not relevant here.) .PP From the user's perspective, things are equally simple: there is a default directory hard-coded into \fIMNI::DataDir\fR, which is selected by the system administrator when the \s-1MNI\s0 Perl Library is built and installed. The hard-coded default for the version of \fIMNI::DataDir\fR that you're currently reading about is \fI/mnt/storage/grid/software\-management/cvmfs/civet/1.1.12/tmp/CIVET\-1.1.12/Linux\-x86_64\fR. .PP Normally, \f(CW\*(C`MNI::DataDir::dir\*(C'\fR looks under this default directory for a package-specific data directory\-\-\-for instance, in the above example, it would look for \fI/mnt/storage/grid/software\-management/cvmfs/civet/1.1.12/tmp/CIVET\-1.1.12/Linux\-x86_64/autoreg\fR. If this directory isn't found, \f(CW\*(C`MNI::DataDir::dir\*(C'\fR will \f(CW\*(C`die\*(C'\fR, crashing your program with an appropriate error message for the end user. .PP However, the user may override this default directory by setting the \&\f(CW\*(C`MNI_DATAPATH\*(C'\fR environment variable. This should be a colon-separated list of directories, which will be searched in turn for the package-specific directory. If it is not found in any of the explicitly-named directories, \f(CW\*(C`MNI::DataDir::dir\*(C'\fR will \f(CW\*(C`die\*(C'\fR. It will \&\fInot\fR fallback to the default directory. .SH "SUBROUTINES" .IX Header "SUBROUTINES" .IP "dir (\s-1PACKAGE\s0)" 4 .IX Item "dir (PACKAGE)" Searches for a directory named by \s-1PACKAGE\s0, either in the directories specified in the \f(CW\*(C`MNI_DATAPATH\*(C'\fR environment variable, or in the hard-coded default directory. Returns the directory name in a form suitable for immediate concatenation with filenames\-\-\-i.e. with a trailing slash. Dies if the directory was not found. .IP "install_dir (\s-1PACKAGE\s0)" 4 .IX Item "install_dir (PACKAGE)" Similar to \f(CW\*(C`dir\*(C'\fR, but \f(CW\*(C`install_dir\*(C'\fR never fails; if it doesn't find a directory for \s-1PACKAGE\s0 on its search path, it makes an educated guess at what the package directory ought to be. In particular, it takes the first directory from the search path (which will just be the hard-coded default directory, unless the \s-1MNI_DATAPATH\s0 environment variable is defined) and appends \s-1PACKAGE\s0 to it. .Sp This is meant to be used only at package-configuration time, to provide the installer of the package with a reasonable default place to put the package's data. .Sp Note that \f(CW\*(C`install_dir\*(C'\fR most expressly does \fInot\fR create the directory it comes up with. For one thing, the installer ought to be able to choose a different directory; this is just a reasonable initial guess. For another thing, installation directories should only be created at installation time, not at configuration time. .IP "check_data (\s-1DIR\s0, \s-1FILES\s0)" 4 .IX Item "check_data (DIR, FILES)" Checks that each file named in \s-1FILES\s0 (a list ref) exists in \s-1DIR\s0. \s-1DIR\s0 is presumably of the form returned by \f(CW\*(C`MNI::DataDir::dir\*(C'\fR, i.e. with a trailing slash. Dies if any files do not exist or are not readable. .SH "AUTHOR" .IX Header "AUTHOR" Greg Ward, . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1997 by Gregory P. Ward, McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. .PP This file is part of the \s-1MNI\s0 Perl Library. It is free software, and may be distributed under the same terms as Perl itself.