"""
A macro mechanism primarily for string replacement in resource descriptors.
"""

#c Copyright 2008-2025, the GAVO project <gavo@ari.uni-heidelberg.de>
#c
#c This program is free software, covered by the GNU GPL.  See the
#c COPYING file in the source distribution.


import datetime
import re
import urllib.request, urllib.parse, urllib.error


from gavo import utils
from gavo.base import attrdef
from gavo.base import common
from gavo.base import complexattrs
from gavo.base import config
from gavo.base import meta
from gavo.base import osinter
from gavo.base import structure
from gavo.utils.parsetricks import (
	ZeroOrMore, Forward,
	ParseResults, ParserElement,
	Regex, Suppress,
	Literal, pyparsingWhitechars)

from gavo.utils.dachstypes import cast, Any, Callable, List, Optional



class MacroError(common.StructureError):
	"""is raised when something bad happens during macro expansion.

	It is constructed with an error message, a macro name, and optionally
	a hint and a position.
	"""
	def __init__(self,
			message: str,
			macroName: str,
			hint: Optional[str] = None,
			pos: Optional[Any] = None) -> None:
		common.StructureError.__init__(
			self, macroName+" failed", pos=pos, hint=hint)
		self.args = (message, macroName, hint, pos)
		self.macroName, self.message = macroName, message

	def __str__(self) -> str:
		pos = f"{self.pos}" if self.pos else "unknown position"
		return f"In Element at {pos}: {self.message}"


class MacroExpander:
	"""is a generic "macro" expander for scripts of all kinds.

	It is loosely inspired by TeX, but of course much simpler.  See the
	syntax below.

	The macros themselves come from a MacroPackage object.  There are
	a few of these around, implementing different functionality depending
	on the script context (i.e., whether it belongs to an RD, a DD, or
	a Table.

	All macros are just functions receiving and returning strings.  The
	arguments are written as {arg1}{arg2}, where you can escape curly
	braces with a backslash.  There must be no whitespace between
	a macro and its first argument.

	If you need to glue together a macro expansion and text following,
	use the glue sequence \\+

	The main entry point to the class is the expand function below,
	taking a string possibly containing macro calls and returning
	a string.

	The construction of such a macro expander is relatively expensive,
	so it pays to cache them.  MacroPackage below has a getExpander
	method that does the caching for you.
	"""
	def __init__(self, package: "MacroPackage") -> None:
		self.package = package
		self._macroGrammar = self._getMacroGrammar()

	def _execMacro(self, s: str, loc: int, toks: ParseResults) -> str:
		toks = toks.asList()
		macName, args = toks[0], toks[1:]
		return self.package.execMacro(macName, args)

	def expand(self, aString: str) -> str:
		return utils.pyparseTransform(self._macroGrammar, aString)

	def _getMacroGrammar(self, debug: bool = False) -> ParserElement:
		with pyparsingWhitechars(" \t"):
			macro = Forward()
			quoteEscape = (Literal("\\{").addParseAction(lambda *args: "{") |
				Literal("\\}").addParseAction(lambda *args: "}"))
			charRun = Regex(r"[^}\\]+").leaveWhitespace()
			argElement = macro | quoteEscape | charRun
			argument = Suppress("{") + ZeroOrMore(argElement) + Suppress("}")
			argument.addParseAction(lambda s, pos, toks: "".join(toks))
			arguments = ZeroOrMore(argument)
			arguments.setWhitespaceChars("")
			macroName = Regex("[A-Za-z_][A-Za-z_0-9]+")
			macroName.setWhitespaceChars("")
			macro << Suppress( "\\" ) + macroName + arguments
			macro.addParseAction(self._execMacro)
			literalBackslash = Literal("\\\\")
			literalBackslash.addParseAction(lambda *args: "\\")
			suppressedLF = Literal("\\\n")
			suppressedLF.addParseAction(lambda *args: " ")
			glue = Literal("\\+")
			glue.addParseAction(lambda *args: "")
			return literalBackslash | suppressedLF | glue | macro


class ExpansionDelegator:
	"""A mixin to make a class expand macros by delegating everything to
	its parent.

	This is intended for base.Structures that have a parent attribute;
	by mixing this in, they use their parents to expand macros for them.
	"""
	def expand(self, aString: str) -> str:
		# parent has to be provided by the class mixing this in.
		return self.parent.expand(aString) # type: ignore


class MacroPackage(common.StructCallbacks):
	r"""A function dispatcher for MacroExpander.

	Basically, you inherit from this class and define macro_xxx functions.
	MacroExpander can then call \xxx, possibly with arguments.
	"""
	def getSourcePosition(self) -> str:
		# This is supposed to be mixed into structs, which I don't think
		# I can convey to mypy
		return super().getSourcePosition() # type: ignore

	def __findMacro(self, macName: str) -> Callable[..., str]:
		fun = getattr(self, "macro_"+macName, None)
		if fun is not None:
			return fun
		
		# this is a bit of a hack so subordinate objects see macDefs from
		# their RDs; generally, we don't inherit macros, as they are bound
		# to types in DaCHS.
		if hasattr(self, "rd"):
			fun = getattr(self.rd, "macro_"+macName, None)
		if fun is not None:
			return fun

		raise MacroError(
			"No macro \\%s available in a %s context"%(
				macName, self.__class__.__name__),
			macName,
			pos=self.getSourcePosition(),
			hint="%s objects have the following macros: %s."%(
				self.__class__.__name__, ", ".join(self.listMacros())))

	def listMacros(self) -> List[str]:
		return [n[6:] for n in dir(self) if n.startswith("macro_")]

	def execMacro(self, macName: str, args: List[str]) -> str:
		fun = self.__findMacro(macName)
		try:
			return fun(*args)
		except TypeError:
			raise utils.logOldExc(MacroError(
				"Invalid macro arguments to \\%s: %s"%(macName, args), macName,
				hint="You supplied too few or too many arguments"))
		except utils.Error:
			raise
		except Exception as msg:
			argRepr = "}{".join(utils.safe_str(a) for a in args)
			if argRepr:
				argRepr = "{%s}"%argRepr

			raise utils.logOldExc(MacroError(
				"While expanding macro \\%s%s: %s"%(macName, argRepr, msg),
				macName,
				pos=self.getSourcePosition(),
				hint="This means that the code dealing with your arguments"
				" was throroughly confused by what you passed.  If you really"
				" cannot see why it was, file a bug."))

	def getExpander(self) -> MacroExpander:
		try:
			return self.__macroExpander
		except AttributeError:
			self.__macroExpander: MacroExpander = MacroExpander(self)
			return self.getExpander()

	def expand(self, stuff: str) -> str:
		return self.getExpander().expand(stuff)

	def macro_quote(self, arg: str) -> str:
		"""returns the argument in quotes (with internal quotes backslash-escaped
		if necessary).
		"""
		return '"%s"'%(arg.replace('"', '\\"'))

	def macro_sqlquote(self, arg: str) -> str:
		"""returns the argument as a quoted string, unless it is 'NULL' or
		None, in which case just NULL is returned.

		We also escape % (as %%) because where DaCHS uses this, the strings
		will go through psycopg, and naked percents will make it try argument
		replacement.
		"""
		if arg is None or arg=='NULL':
			return "NULL"
		return "'%s'"%arg.replace("'", "''").replace('%', '%%')

	def macro_sql_standardPubDID(self, fromCol: str = "accref") -> str:
		"""returns a SQL expression returning a DaCHS standard pubDID generated
		from the accref (or something overridden) column.

		This is convenient in obscore or ssa views when the underlying table
		just has accrefs.  If your code actually uses the pubDID to search
		in the table (and it probably shouldn't), better use an actual column
		and index it.
		"""
		auth = config.get("ivoa", "authority")
		return "'ivo://%s/~?' || gavo_urlescape(%s)"%(
			auth.replace("'", "''"),
			fromCol)

	def macro_reSub(self, pattern: str, replacement: str, string: str) -> str:
		"""returns the string with the python RE pattern replaced with
		replacement.

		This is directly handed through to python re.sub, so you can (but
		probably shouldn't) play all the RE tricks you can in python (e.g.,
		back references).

		If you find yourself having to use reSub, you should regard that as
		an alarm sign that you're probably doing it wrong.
		
		Oh: closing curly braces can be included in the argument by
		backslash-escaping them.
		"""
		return re.sub(pattern, replacement, string)

	def macro_if(self, cond: str, val: str) -> str:
		"""returns val if cond is not either empty or 0 after stripping,
		the empty string otherwise.
		"""
		if cond.strip() in ('', '0'):
			return ""
		return val


class StandardMacroMixin(MacroPackage):
	"""is  a mixin providing some macros for scripting's MacroExpander.

	The class mixing in needs to provide its resource descriptor in the
	rd attribute.
	"""
	def macro_magicEmpty(self, val: str) -> str:
		"""returns __EMPTY__ if val is empty.

		This is necessary when feeding possibly empty params from mixin
		parameters (don't worry if you don't understand this).
		"""
		if val:
			return val
		else:
			return "__EMPTY__"

	def macro_rdId(self) -> str:
		"""the identifier of the current resource descriptor.
		"""
		# rd must come from the class mixing this in.
		return self.rd.sourceId # type: ignore

	def macro_rdIdDotted(self) -> str:
		"""the identifier for the current resource descriptor with slashes replaced
		with dots (so they work as the "host part" in URIs.
		"""
		# rd must come from the class mixing this in.
		return self.rd.sourceId.replace("/", ".") # type: ignore

	def macro_schema(self) -> str:
		"""the schema of the current resource descriptor.
		"""
		# rd must come from the class mixing this in.
		return self.rd.schema # type: ignore

	def macro_resdir(self) -> str:
		"""the input-relative resource directory of the current resource
		descriptor.

		This never has a trailing slash.
		"""
		# rd must come from the class mixing this in.
		return str(self.rd.getRelResdir()).rstrip("/") # type: ignore

	def macro_RSTservicelink(self,
			serviceId: str,
			title: Optional[str] = None) -> str:
		"""a link to an internal service; id is <rdId>/<serviceId>/<renderer>,
		title, if given, is the anchor text.

		The result is a link in the short form for restructured test.
		"""
		if title is None:
			title = serviceId
		return "`%s <%s>`_"%(title, osinter.makeSitePath(serviceId))

	def macro_RSTtable(self, tableName:str) -> str:
		"""adds an reStructured test link to a tableName pointing to its table
		info.
		"""
		return "`%s <%s>`_"%(tableName,
			osinter.makeSitePath("tableinfo/%s"%tableName))

	def macro_internallink(self, relPath: str) -> str:
		"""an absolute URL from a path relative to the DC root.
		"""
		return osinter.makeAbsoluteURL(relPath, canonical=True)

	def macro_urlquote(self, string: str) -> str:
		"""wraps urllib.quote.
		"""
		return urllib.parse.quote(string)

	def macro_today(self) -> str:
		"""today's date in ISO representation.
		"""
		return str(datetime.date.today())

	def macro_getConfig(self, section: str, name: Optional[str] = None) -> str:
		"""the current value of configuration item {section}{name}.

		You can also only give one argument to access settings from the
		general section.
		"""
		if name is None:
			section, name = "general", section
		val = config.get(section, name)
		if isinstance(val, str):
			return val
		else:
			return str(val)

	def macro_metaString(self,
			metaKey: str,
			default: Optional[str] = None) -> str:
		"""the value of metaKey on the macro expander.

		This will raise an error when the meta Key is not available unless
		you give a default.  It will also raise an error if metaKey is not
		atomic (i.e., single-valued).  Use metaSeq for meta items that
		may have multiple values.

		Because it's sometimes useful, if the expander itself doesn't
		have metadat, this goes up in the RD tree until it finds something
		that has metadata.
		"""
		mc = self
		while mc and not hasattr(mc, "getMeta"):
			# parent is provided by the class mixing this in
			mc = mc.parent # type: ignore

		try:
			try:
				# getMeta is provided by the class mixing this in
				val = mc.getMeta(metaKey, raiseOnFail=True) # type: ignore
			except meta.NoMetaKey:
				if default is not None:
					return default
				raise

			return val.getContent(macroPackage=self
				).replace("\n", " ") # undo default line breaking

		except meta.MetaError as exc:
			exc.carrier = cast(meta.MetaMixin, self)
			exc.key = metaKey
			if hasattr(self, "getSourcePosition"):
				# we're making the attribute for the benefit of the error message
				# formatter.
				exc.pos = self.getSourcePosition() # type: ignore
			raise

	def macro_metaSeq(self,
			metaKey: str,
			default: str = '',
			joiner: str = ', ') -> str:
		"""returns all values of metaKey on the current macro expander joined
		by joiner.

		This will be an empty string if there is no corresponding metadata (or
		default, if passed).
		"""
		# iterMeta provided by the class mixing us in
		vals = list(self.iterMeta(metaKey, propagate=True)) # type:ignore
		if vals:
			return joiner.join(str(val) for val in vals)
		else:
			return default

	def macro_upper(self, aString: str) -> str:
		"""returns aString uppercased.

		There's no guarantees for characters outside ASCII.
		"""
		return aString.upper()

	def macro_lower(self, aString: str) -> str:
		"""returns aString lowercased.

		There's no guarantees for characters outside ASCII.
		"""
		return aString.lower()

	def macro_decapitalize(self, aString: str) -> str:
		"""returns aString with the first character lowercased.
		"""
		if aString:
			return aString[0].lower()+aString[1:]
		return ""

	def macro_test(self, *args: str) -> str:
		"""always "test macro expansion".
		"""
		return "test macro expansion"


@structure.buildstructure
class MacDef(structure.Structure):
	"""A macro definition within an RD.

	The macro defined is available on the parent; macros are expanded
	within the parent (behaviour is undefined if you try a recursive expansion).
	"""
	name_ = "macDef"

	_name = attrdef.UnicodeAttribute("name",
		description="Name the macro will be available as",
		copyable=True,
		default=utils.Undefined)
	_raw = attrdef.BooleanAttribute("raw",
		description="If true, macros in the content will not be expanded in place.",
		copyable=True,
		default=False)
	_content = structure.DataContent(
		description="Replacement text of the macro")

	def validate(self) -> None:
		super().validate()
		if len(self.name)<2:
			raise common.LiteralParseError("name", self.name, hint=
				"Macro names must have at least two characters.")

	def onElementComplete(self) -> None:
		super().onElementComplete()
		# we probably should make clear that MacDef parents need to be
		# MacroExpanders; in practice, that's RD anyway.
		if not self.raw:
			try:
				self.content_: str = cast(MacroExpander, self.parent
					).expand(self.content_)
			except MacroError as ex:
				ex.pos = self.getSourcePosition()
				raise
		def mac() -> str:
			return self.content_
		setattr(self.parent, "macro_"+self.name, mac)


def MacDefAttribute(**kwargs: Any) -> complexattrs.StructListAttribute:
	return complexattrs.StructListAttribute(
		"macDefs",
		childFactory=MacDef,
		**kwargs)
