# Copyright (C) 2011 David Maxwell
# 
# This file is part of PISM.
# 
# PISM is free software; you can redistribute it and/or modify it under the
# terms of the GNU General Public License as published by the Free Software
# Foundation; either version 3 of the License, or (at your option) any later
# version.
# 
# PISM is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
# details.
# 
# You should have received a copy of the GNU General Public License
# along with PISM; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

import PISM

"""Helper functions to make working with the PISM/PETSc option system more pythonic."""


def OptionsGroup(com=None,prefix="",title=""):
  """Replacement for the C-based ``PetscOptionsBegin/End`` macros which,
suprisingly, actually implement a loop that gets run three times. 
We emulate the loop on the python side via the construct::

  for o in OptionsGroup(comm,prefix,title):
    <Calls to determine options>

The  ``o`` returned by the iterator is always ``None`` and is
not intended to be meaningful.  The iterator ensures that
the ``<Calls to determine options>`` is repeated just as it would be 
within the loop created by the ``PetscOptionsBegin/End`` macros.

:param com: MPI Comm used for messaging.
:param prefix: Prefix to be prepended to all option names.
:param title:  Short discriptive text for the options group.
"""
  if com is None:
    com = PISM.Context().com
  PISM.cpp.optionsGroupBegin(com,prefix,title,"");
  while(PISM.cpp.optionsGroupContinue()):
    yield None
    PISM.cpp.optionsGroupNext()
  PISM.cpp.optionsGroupEnd()

def optionsIntWasSet(option,text,default=None):
  """Determines if an integer-valued command-line option was set.
  
  :param option:  Name of command-line option.
  :param text:    Description of option.
  :param default: Default value if option was not set.
  :returns: Tuple ``(value,wasSet)`` where ``value`` is the value that was set (or the ``default`` value if it was not)
            and ``wasSet`` is a boolean that is ``True`` if the command line option was set explicitly.
  """

  (result,is_set)=PISM.cpp._optionsInt(option,text)
  if not is_set:
    result = default
  return (result,is_set)
def optionsInt(*args,**kwargs):
  """Same as :func:`optionsIntWasSet` but only returns the integer value."""
  return optionsIntWasSet(*args,**kwargs)[0]

def optionsRealWasSet(option,text,default=None):
  """Determines if a real-valued command line option was set.
  
  :param option:  Name of command line option.
  :param text:    Description of option.
  :param default: Default value if option was not set.
  :returns: Tuple ``(value,wasSet)`` where ``value`` is the value that was set (or the ``default`` value if it was not)
            and ``wasSet`` is a boolean that is ``True`` if the command line option was set explicitly.
  """

  (result,is_set)=PISM.cpp._optionsReal(option,text)
  if not is_set:
    result = default
  return (result,is_set)
def optionsReal(*args,**kwargs):
  """Same as :func:`optionsRealWasSet` but only returns the real value."""
  return optionsRealWasSet(*args,**kwargs)[0]

def optionsStringWasSet(option,text,default=None):
  """Determines if a string-valued command line option was set.
  
  :param option:  Name of command line option.
  :param text:    Description of option.
  :param default: Default value if option was not set.
  :returns: Tuple ``(value,wasSet)`` where ``value`` is the value that was set (or the ``default`` value if it was not)
            and ``wasSet`` is a boolean that is ``True`` if the command line option was set explicitly.
  """
  (result,is_set)=PISM.cpp._optionsString(option,text)
  if not is_set:
    result = default
  return (result,is_set)
def optionsString(*args,**kwargs):
  """Same as :func:`optionsStringWasSet` but only returns the string value."""
  return optionsStringWasSet(*args,**kwargs)[0]

def optionsIntArrayWasSet(option,text,default=None):
  """Determines if an integer-array-valued command line option was set.
  
  :param option:  Name of command line option.
  :param text:    Description of option.
  :param default: Default value if option was not set.
  :returns: Tuple ``(value,wasSet)`` where ``value`` is the value that was set (or the ``default`` value if it was not)
            and ``wasSet`` is a boolean that is ``True`` if the command line option was set explicitly.
  """
  val = PISM.cpp._optionsIntArray(option,text)
  is_set = val[-1]
  result = val[:-1]
  if not is_set:
    result = default
  return (result,is_set)
def optionsIntArray(*args,**kwargs):
  """Same as :func:`optionsIntArrayWasSet` but only returns the integer array."""
  return optionsIntArrayWasSet(*args,**kwargs)[0]

def optionsRealArrayWasSet(option,text,default=None):
  """Determines if a real-array-valued command line option was set.
  
  :param option:  Name of command line option.
  :param text:    Description of option.
  :param default: Default value if option was not set.
  :returns: Tuple ``(value,wasSet)`` where ``value`` is the value that was set (or the ``default`` value if it was not)
            and ``wasSet`` is a boolean that is ``True`` if the command line option was set explicitly.
  """
  val = PISM.cpp._optionsRealArray(option,text)
  is_set = val[-1]
  result = val[:-1]
  if not is_set:
    result = default
  return (result,is_set)
def optionsRealArray(*args,**kwargs):
  """Same as :func:`optionsRealArrayWasSet` but only returns the real array."""
  return optionsRealArrayWasSet(*args,**kwargs)[0]

def optionsStringArrayWasSet(option,text,default=None):
  """Determines if a string-array-valued command line option was set.
  
  :param option:  Name of command line option.
  :param text:    Description of option.
  :param default: Default value if option was not set.
  :returns: Tuple ``(value,wasSet)`` where ``value`` is the value that was set (or the ``default`` value if it was not)
            and ``wasSet`` is a boolean that is ``True`` if the command line option was set explicitly.
  """
  origDefault = default
  if default is None:
    default = ""
  val = PISM.cpp._optionsStringArray(option,text,default)
  is_set = val[-1]
  result = val[:-1]
  if not is_set:
    result = origDefault
  else:
    result = [r for r in result[0]]
  return (result,is_set)
def optionsStringArray(*args,**kwargs):
  """Same as :func:`optionsStringArrayWasSet` but only returns the string array."""
  return optionsStringArrayWasSet(*args,**kwargs)[0]


def optionsListWasSet(com,option,text,opt_set,default):
  """Determines if a string command line option was set, where the string can be one of a few legal options.
  
  :param option:  Name of command line option.
  :param text:    Description of option.
  :param opt_set: List of legal string values.
  :param default: Default value.
  :returns: Tuple ``(value,wasSet)`` where ``value`` is the value that was set (or the ``default`` value if it was not)
            and ``wasSet`` is a boolean that is ``True`` if the command line option was set explicitly.
  """
  val = PISM.cpp._optionsList(com,option,text,opt_set,default)
  return (val[0],val[1])
def optionsList(*args,**kwargs):
  """Same as :func:`optionsListWasSet` but only returns the option value."""
  return optionsListWasSet(*args,**kwargs)[0]


def optionsFlag(option,text,default=False):
  """Determines if a flag command line option  of the  form ``-foo`` or ``-no_foo`` was set.
The option value is 
  
  :param option:  Name of command line option.
  :param text:    Description of option.
  :param default: Default value.
  :returns: ``True`` if ``-foo`` was set and ``False`` if ``-no_foo`` was set.  If
            neither is set, the `default` is used, and if both are set a :exc:`RuntimeError` is raised.
  """

  if option[0] == '-':
    option=option[1:]
  true_set = PISM.optionsIsSet("-"+option)
  false_set = PISM.optionsIsSet("-no_"+option)

  if true_set and false_set:
    raise RuntimeError("Command line options inconsistant: both -%s and -no_%s are set" % (option,option) )

  if true_set: return True
  if false_set: return False
  return default