"  Call perldoc(1) on a given word assuming it is a module, failing that assume
"  word is function (-f), failing that is question (-q).
"
"  If optional context is given -- matching one of mod(ule)?, func(tion)?, or
"  q(uestion)? -- perldoc is called only in that context.
function! Perldoc( string, ... )

  "  No context specified, try all.
  if ! exists( 'a:1' )

    exec ':!perldoc ' . a:string
    \ . ' || perldoc -f ' . a:string
    \ . ' || perldoc -q ' . a:string

    return
  endif

  "  Let's see if we get lucky with the given context.
  let opt =
    \ a:1 =~? '^mod' ? ''
      \ : a:1 =~? '^func' ? '-f'
        \ : a:1 =~? '^q' ? '-q'
          \ : a:1

  exec ':!perldoc ' . opt . ' ' . a:string
  unlet opt

  return
endfunction

"  Given a module name, returns the list of all the parts of the name.  If
"  'A::B::C' is given, then ['A', 'A::B', 'A::B::C'] is returned.
"
"  If second optional argument is a number, then the token at that position is
"  returned.  Else argument is considered a pattern and first match is returned.
"  An empty string is returned if there is no match.
function! Tokenize_Perlmod( string, ... )

  let tokes = [ a:string ]
  let pos = strridx( a:string , '::' )

  while pos != -1

    let tokes = insert( tokes , strpart( a:string , 0 , pos ) )
    let start = pos - 2
    let pos = strridx( a:string , '::' , start )
  endwhile

  unlet start
  unlet pos

  "for t in tokes
  "  echo t
  "endfor

  "  No choice was presented.
  if ! exists( 'a:1' )
    return tokes
  endif

  "  Either a number was given or a pattern to select the first matching token.
  try

    throw a:1
  catch /^-\?\d\+$/

    return get( tokes , a:1 , '' )
  catch /./

    for t in tokes

      if t =~ a:1

        return t
      endif
    endfor
    return ''

  finally

    unlet tokes
  endtry
endfunction