&'MIFread_mif(
FILEHANDLE);
MIFread_mif
handles the parsing of the Frame MIF specified by FILEHANDLE
and calls token callback routines defined by the caller of MIFread_mif
for each
token encountered in the MIF.
%mif'MIFToken
associative array.
The keys of the array are any legal MIF tokens of interest. The values of the array
are the names of the routines to be invoked when key/token is encountered in the
MIF markup.
$mif'MIFToken{`ParaLine'} = `paragraph_line';
When MIFread_mif
encounters a ParaLine
, it will call the routine
paragraph_line
.
main'paragraph_line
) when stored in the %mif'MIFToken
.
A token callback is invoked as follows:
&
token_func($token, $mode, *data);
Where token_func is a token routine defined in %mif'MIFToken
.
Argument descriptions:
$token
$mode
$mif'MOpen
,
$mif'MClose
, $mif'MLine
, respectively.
*data
$MLine
, or $MClose
if the storing option
is in effect. The data string contains the data content of the token specified
by $token
. The exception is when storing is done (see Storing MIF below
for more info).
The token routine never see the `
<
` and `>
' markup delimiters, with the following
exceptions:
MIFread_mif
will store MIF markup if the routine for a token is prefixed by the
value, $MStore
, and the `,
' character.
$mif'MIFToken{`ParaLine'} =
"$mif'MStore,paragraph_line";
,
' character is needed to separate the $MStore
string from the routine name.
Once the token closes, the named routine is called with mode $MClose
, and the
*data
argument contains the MIF. The store routine may also be called if the
token specified does not contain nested MIF or is empty. In this case, $MLine
is
passed as the mode, and the markup delimiters, `<
` and `>
', are not in the *data
argument string (i.e. The behavior is the same if $MStore
was not specified).
$mif'MImportData
. If a
routine is registered for this token, than it will be invoked as follows:
&
token_func($MImportData, $MLine, *data);
Where *data
is a pointer to the string that contains the imported data. The
imported data is passed "as is", and it is up to the calling routine to process it.
$MStore
for $MImportData
is not supported since *data
contains the import data as it appears in the MIF document. If $MStore
is used, Perl will cause program termination since it will try to execute the
routine "$MStore,$MIFToken{$MImportData}
".
@mif'OpenTokens
array is updated like a stack by MIFread_mif
telling
which tokens are currently opened. MIFread_mif
will die if a pop is done on an
empty @OpenTokens
(i.e. an extra `>' was found). One can check the stack after
parsing is done to determine if tokens were not closed.
MIFread_mif
is not intended as a MIF validator. If the routine dies, it
outputs a terse message. For validation, it is best to use
FrameMaker/Builder.
MIFread_mif
:
$mif'fast
MIFread_mif
will not process `#
' end-of-line
comments. By default, MIFread_mif
strips out all `#
' comments to avoid
any MIF markup that could be contained in them. Setting $fast
to
non-zero approximately doubles speed performance.
$mif'no_import_data
MIFread_mif
will not check for import data.
This is useful if the MIF file contains no import data. There is a slight
increase in performance if this variable is set.
In most cases, setting $fast
is safe to do. If one is parsing MIF generated from
FrameMaker/Builder, the comments in the MIF do not contain markup that will
cause MIFread_mif
behave incorrectly.
MIFread_mif
is invoked. However,
they can be modified within registered token callbacks. For example, one
might want to set $no_import_data
to 1 before calling MIFread_mif
.
Then when the "AFrames
" token callback is called with a mode of
$MOpen
, it can set $no_import_data
back to zero so MIFread_mif
will
catch import data. Then when the "AFrames
" token callback is called
with a mode of $MClose
, it can set $no_import_data
to 1. The same
thing can be done for "Frame
" tokens.
MIFread_mif
tries its best to preserve the original formatting (i.e.
indenting) when storing MIF.
<Comment>
statements are treated like any other MIF statement.
Therefore, if <Comment>
s are embedded in a token specified for storing,
the comments will be preserved. One can register a token callback for
<Comment>
if desired.
MIFread_mif
does not handle MIF macro statements.
<Token & # This comment will NOT get removed # This comment will get removed >
MIFread_mif
treats lines starting with `&
' as import data, and therefore,
does not process it.