docs: def vm_state(name='', cwd=None):
      '''
      Return list of information for all the vms indicating their state.
  
      If you pass a VM name in as an argument then it will return info
      for just the named VM, otherwise it will return all VMs defined by
      the Vagrantfile in the `cwd` directory.
  
      CLI Example:
  
      .. code-block:: bash
  
          salt '*' vagrant.vm_state <name>  cwd=/projects/project_1
  
      returns a list of dictionaries with machine name, state, provider,
      and salt_id name.
  
      .. code-block:: python
  
          datum = {'machine': _, # Vagrant machine name,
                   'state': _, # string indicating machine state, like 'running'
                   'provider': _, # the Vagrant VM provider
                   'name': _} # salt_id name
  
      Known bug: if there are multiple machines in your Vagrantfile, and you request
      the status of the ``primary`` machine, which you defined by leaving the ``machine``
      parameter blank, then you may receive the status of all of them.
      Please specify the actual machine name for each VM if there are more than one.
  
      '''
  
      if name:
          vm_ = get_vm_info(name)
          machine = vm_['machine']
          cwd = vm_['cwd'] or cwd  # usually ignore passed-in cwd
      else:
          if not cwd:
              raise SaltInvocationError(
                  'Path to Vagranfile must be defined, but cwd={}'.format(cwd))
          machine = ''
  
      info = []
      cmd = 'vagrant status {}'.format(machine)
      reply = __salt__['cmd.shell'](cmd, cwd)
      log.info('--->\n%s', reply)
      for line in reply.split('\n'):  # build a list of the text reply
          tokens = line.strip().split()
          if len(tokens) > 1 and tokens[-1].endswith(')'):
              try:
                  datum = {'machine': tokens[0],
                           'state': ' '.join(tokens[1:-1]),
                           'provider': tokens[-1].lstrip('(').rstrip(')'),
                           'name': get_machine_id(tokens[0], cwd)
                           }
                  info.append(datum)
              except IndexError:
                  pass
      return info