Api

General

You can create functions and commands to interact directly with VM.

All VM internal variables and functions are stored in a buffer dictionary, b:VM_Selection.

Some examples:

let VM = b:VM_Selection

let Regions = VM.Regions 	" where VM regions are stored
let t1 = Regions[0].txt		" get a region's content by index

" get all regions contents in a list
let regions_text = VM.Global.regions_text()

" process regions contents with a function, creating a new list
let new_text = []
for t in regions_text
    call add(new_text, function(t))
endfor

" fill VM register and paste the new contents
call VM.Edit.fill_register('"', new_text, 0)
normal p

There are many more methods that you can call, and properties that you can edit, but most of them are probably of little use in custom commands.

This is an example function that exchanges region contents in mass, that is, select regions with different contents, and they'll be all swapped:

dog cat dog          cat dog cat
dog cat dog  ---->   cat dog cat
dog cat dog          cat dog cat

fun! VM_mass_transpose()
  if !g:Vm.is_active | return | endif

  let VM = b:VM_Selection
  if len(VM.Regions) == 1 || !g:Vm.extend_mode
    echo "Not possible"
    return
  endif

  let txt = VM.Global.regions_text()

  " create a list of the unique regions contents
  let unique = uniq(copy(txt))

  if len(unique) == 1
    echo "Regions have the same content"
    return
  endif

  " move first unique text to the bottom of the stack, but make a copy first
  let old = copy(unique)
  call add(unique, remove(unique, 0))

  " create new text
  let new_text = []
  for t in txt
    call add(new_text, old[index(unique, t)])
  endfor

  " fill register and paste new text
  call VM.Edit.fill_register('"', new_text, 0)
  normal p
endfun

b:VM_Selection.Regions

A list with current regions. Some region's methods/attributes (region is r):

r.a	starting column
r.b	end column
r.l	starting line
r.L	end line
r.A	starting offset
r.B	final offset
r.txt	text content
r.pat	associated pattern
r.move(motion)	perform motion on region
r.clear()	remove region
r.update()	update region

b:VM_Selection.Global

Mostly functions that affect all regions at once.

update_highlight()
update_and_select_region(...)	select region at cursor or at given position
change_mode()	alternate cursor/extend mode
cursor_mode()	force cursor mode
extend_mode()	force extend mode
new_cursor()	create a cursor at current position
new_region(...)	from current yank marks, or by given positions/offsets
select_region(index)	select region at index
select_region_at_pos(pos)	.. or at position/offset
is_region_at_pos(pos)	check if a region exists at position/offset
regions_text()	a list with regions contents
lines_with_regions(reverse)	a dict: {lnum: [regions], ...}
one_region_per_line()	remove all regions after the first one for each line
split_lines()	split regions that span multiple lines at end of line
merge_regions()	merge overlapping regions