Usage: (extract file-name marker-fmt [ caveat ] [ default ])
This function is used to help construct output files that may contain
text that is carried from one version of the output to the next.
The first two arguments are required, the second are optional:
The file-name argument is used to name the file that
contains the demarcated text.
The marker-fmt is a formatting string that is used to construct
the starting and ending demarcation strings. The sprintf function is
given the marker-fmt with two arguments. The first is either
"START" or "END". The second is either "DO NOT CHANGE THIS COMMENT"
or the optional caveat argument.
caveat is presumed to be absent if it is the empty string
(""). If absent, “DO NOT CHANGE THIS COMMENT” is used
as the second string argument to the marker-fmt.
When a default argument is supplied and no pre-existing text
is found, then this text will be inserted between the START and END
markers.
The resulting strings are presumed to be unique within
the subject file. As a simplified example:
will result in the following text being inserted into the output:
// START - SOMETHING - DO NOT CHANGE THIS COMMENT
example default
// END - SOMETHING - DO NOT CHANGE THIS COMMENT
The “example default” string can then be carried forward to
the next generation of the output, provided the output
is not named "fname" and the old output is renamed to
"fname" before AutoGen-eration begins.
NB:
You can set aside previously generated source files inside the pseudo
macro with a Guile/scheme function, extract the text you want to keep
with this extract function. Just remember you should delete it at the
end, too. Here is an example from my Finite State Machine generator:
This code will move the two previously produced output files to files
named ".fsm.head" and ".fsm.code". At the end of the ’c’ output
processing, I delete them.
also NB:
This function presumes that the output file ought to be editable so
that the code between the START and END marks can be edited
by the template user. Consequently, when the (extract ...) function
is invoked, if the writable option has not been specified, then
it will be set at that point. If this is not the desired behavior, the
--not-writable command line option will override this.
Also, you may use the guile function (chmod "file" mode-value)
to override whatever AutoGen is using for the result mode.
Arguments:
file-name - name of file with text
marker-fmt - format for marker text
caveat - Optional - warn about changing marker
default - Optional - default initial text