Well, I think your interpretation is...err...imaginative, but you're without doubt a very smart person so the docs mustn't be clear enough. I'll make sure the next version leaves no room for misinterpretation:
in reply to (jcwren) Re: Re: Text::Balanced woes..
in thread Text::Balanced woes..
The various "extract_..." subroutines may be used to
extract a delimited substring, possibly after skipping a
specified prefix string. By default, that prefix is
optional whitespace, but you can change it to whatever
you wish (see below).
The substring to be extracted must appear at the
current "pos" location of the string's variable
(or at index zero, if no "pos" position is defined).
In other words, the "extract_..." subroutines *don't*
extract the first occurance of a substring anywhere
in a string (like an unanchored regex would). Rather,
they extract an occurance of the substring appearing
immediately at the current matching position in the
string (like a "\G"-anchored regex would).