r'''
    Defines a new VM with specified arguments, but does not start it.

    :param name: the Salt_id node name you wish your VM to have.

    Each machine must be initialized individually using this function
    or the "vagrant.running" function, or the vagrant.init execution module call.

    This command will not change the state of a running or paused machine.

    Possible keyword arguments:

    - cwd: The directory (path) containing the Vagrantfile
    - machine: ('') the name of the machine (in the Vagrantfile) if not default
    - vagrant_runas: ('root') the username who owns the vagrantbox file
    - vagrant_provider: the provider to run the VM (usually 'virtualbox')
    - vm: ({}) a dictionary containing these or other keyword arguments

    .. code-block:: yaml

        node_name1:
          vagrant.initialized
            - cwd: /projects/my_project
            - vagrant_runas: my_username
            - machine: machine1

        node_name2:
          vagrant.initialized
            - cwd: /projects/my_project
            - vagrant_runas: my_username
            - machine: machine2

        start_nodes:
          vagrant.start:
            - name: node_name?

def initialized(name, **kwargs):
    r'''
    Defines a new VM with specified arguments, but does not start it.

    :param name: the Salt_id node name you wish your VM to have.

    Each machine must be initialized individually using this function
    or the "vagrant.running" function, or the vagrant.init execution module call.

    This command will not change the state of a running or paused machine.

    Possible keyword arguments:

    - cwd: The directory (path) containing the Vagrantfile
    - machine: ('') the name of the machine (in the Vagrantfile) if not default
    - vagrant_runas: ('root') the username who owns the vagrantbox file
    - vagrant_provider: the provider to run the VM (usually 'virtualbox')
    - vm: ({}) a dictionary containing these or other keyword arguments

    .. code-block:: yaml

        node_name1:
          vagrant.initialized
            - cwd: /projects/my_project
            - vagrant_runas: my_username
            - machine: machine1

        node_name2:
          vagrant.initialized
            - cwd: /projects/my_project
            - vagrant_runas: my_username
            - machine: machine2

        start_nodes:
          vagrant.start:
            - name: node_name?
    '''
    ret = {'name': name,
           'changes': {},
           'result': True,
           'comment': 'The VM is already correctly defined'
           }

    # define a machine to start later
    ret, kwargs = _find_init_change(name, ret, **kwargs)

    if ret['changes'] == {}:
        return ret

    kwargs['start'] = False
    __salt__['vagrant.init'](name, **kwargs)
    ret['changes'][name] = 'Node initialized'
    ret['comment'] = 'Node {0} defined but not started.'.format(name)

    return ret