<Purpose>
    Seash callback to allow user to define a custom variable and assign a value
    to it.
  <Arguments>
    input_dict: Input dictionary generated by seash_dictionary.parse_command().
    environment_dict: Dictionary describing the current seash environment.
    
    For more information, see command_callbacks.py's module docstring.
  <Side Effects>
    A new variable will be added to the uservariables dictionary.
  <Exceptions>
    UserError: The user did not provide a value to assign to the variable
  <Return>
    None

def set_user_variable(input_dict, environment_dict):
  """
  <Purpose>
    Seash callback to allow user to define a custom variable and assign a value
    to it.
  <Arguments>
    input_dict: Input dictionary generated by seash_dictionary.parse_command().
    environment_dict: Dictionary describing the current seash environment.
    
    For more information, see command_callbacks.py's module docstring.
  <Side Effects>
    A new variable will be added to the uservariables dictionary.
  <Exceptions>
    UserError: The user did not provide a value to assign to the variable
  <Return>
    None
  """
  # Iterates through the dictionary to retrieve the variable name
  command_key = input_dict.keys()[0]
  while input_dict[command_key]['name'] is not 'variable_name':
    input_dict = input_dict[command_key]['children']
    variable_name = command_key = input_dict.keys()[0]

  # User may accidentally omit this value, we must catch the exception and
  # return something readable...
  try:
    # Iterates through the dictionary to retrieve the variable value
    while input_dict[command_key]['name'] is not 'variable_value':
      input_dict = input_dict[command_key]['children']
      variable_value = command_key = input_dict.keys()[0]
  except IndexError, e:
    raise seash_exceptions.UserError("Error, expected a value to assign to variable")

  uservariables[variable_name] = variable_value.strip()