#!/usr/bin/env python

"""
Copyright (c) 2006-2024 sqlmap developers (https://sqlmap.org/)
See the file 'LICENSE' for copying permission
"""

import re  # 导入re模块，用于正则表达式操作

from lib.core.common import Backend  # 导入Backend类，用于获取后端数据库信息
from lib.core.convert import getBytes  # 导入getBytes函数，用于将字符串转换为字节
from lib.core.data import conf  # 导入conf对象，存储全局配置信息
from lib.core.enums import DBMS  # 导入DBMS枚举类，定义数据库类型
from lib.core.exception import SqlmapUndefinedMethod  # 导入SqlmapUndefinedMethod异常类，表示未定义的方法

class Syntax(object):
    """
    This class defines generic syntax functionalities for plugins.
    这个类定义了插件的通用语法功能。
    """

    def __init__(self):
        pass  # 初始化方法，此处为空

    @staticmethod
    def _escape(expression, quote=True, escaper=None):
        """
        Internal method to escape a given expression.
        内部方法，用于转义给定的表达式。

        Args:
            expression (str): The expression to escape. 要转义的表达式。
            quote (bool, optional): Whether to handle quoting. 是否处理引号。默认为True
            escaper (function, optional): The function to use for escaping. 用于转义的函数。默认为None
        
        Returns:
            str: 转义后的表达式
        """
        retVal = expression  # 初始化返回值

        if quote:  # 如果需要处理引号
            for item in re.findall(r"'[^']*'+", expression):  # 查找所有单引号包裹的内容
                original = item[1:-1]  # 获取引号内的原始内容
                if original:  # 如果原始内容不为空
                    if Backend.isDbms(DBMS.SQLITE) and "X%s" % item in expression:
                        continue # 如果是SQLite数据库，且表达式中包含X'...'的格式，则跳过
                    if re.search(r"$$(SLEEPTIME|RAND)", original) is None:  # 检查原始内容是否包含[SLEEPTIME]或[RAND]标记，例如'[SLEEPTIME]'
                        replacement = escaper(original) if not conf.noEscape else original  # 如果配置中没有设置noEscape，则使用转义函数进行转义，否则不转义
                        
                        if replacement != original:  # 如果转义后的内容与原始内容不同
                            retVal = retVal.replace(item, replacement)  # 则替换表达式中的原始内容为转义后的内容
                        elif len(original) != len(getBytes(original)) and "n'%s'" % original not in retVal and Backend.getDbms() in (DBMS.MYSQL, DBMS.PGSQL, DBMS.ORACLE, DBMS.MSSQL):
                             # 如果原始内容的字节长度与字符串长度不同，且不是n'...'格式，且数据库为MySQL，PostgreSQL，Oracle，MSSQL中的一种
                            retVal = retVal.replace("'%s'" % original, "n'%s'" % original) # 则将表达式中的原始内容替换为n'...'格式，以支持Unicode字符
        else:  # 如果不需要处理引号
            retVal = escaper(expression) # 使用转义函数进行转义

        return retVal # 返回转义后的表达式

    @staticmethod
    def escape(expression, quote=True):
        """
        Generic method to escape a given expression.
        通用方法，用于转义给定的表达式。

        Args:
            expression (str): The expression to escape. 要转义的表达式。
            quote (bool, optional): Whether to handle quoting. 是否处理引号。默认为True
        
        Raises:
            SqlmapUndefinedMethod: 如果没有在具体数据库插件中定义escape方法，则抛出此异常
        """
        errMsg = "'escape' method must be defined "
        errMsg += "inside the specific DBMS plugin"
        raise SqlmapUndefinedMethod(errMsg)  # 抛出异常，表示未在具体DBMS插件中定义此方法