woql_query.py

import datetime as dt
import json

# import pprint
import re
import warnings

from .woql_core import _copy_dict, _path_tokenize, _path_tokens_to_json

UPDATE_OPERATORS = [
    "AddTriple",
    "DeleteTriple",
    "AddQuad",
    "DeleteQuad",
    "DeleteObject",
    "UpdateObject",
]

SHORT_NAME_MAPPING = {
    "type": "rdf:type",
    "label": "rdfs:label",
    "Class": "owl:Class",
    "DatatypeProperty": "owl:DatatypeProperty",
    "ObjectProperty": "owl:ObjectProperty",
    "Document": "terminus:Document",
    "abstract": "terminus:Document",
    "comment": "rdfs:comment",
    "range": "rdfs:range",
    "domain": "rdfs:domain",
    "subClassOf": "rdfs:subClassOf",
    "boolean": "xsd:boolean",
    "string": "xsd:string",
    "integer": "xsd:integer",
    "decimal": "xsd:decimal",
    "email": "xdd:email",
    "json": "xdd:json",
    "dateTime": "xsd:dateTime",
    "date": "xsd:date",
    "coordinate": "xdd:coordinate",
    "line": "xdd:coordinatePolyline",
    "polygon": "xdd:coordinatePolygon",
}


class Var:
    def __init__(self, name):
        self.name = name

    def __str__(self):
        return self.name

    def to_dict(self):
        return {"@type": "Value", "variable": self.name}


class Vars:
    def __init__(self, *args):
        for arg in args:
            setattr(self, arg, Var(arg))


# Global counter for unique variable names
_unique_var_counter = 0


def _reset_unique_var_counter(value=0):
    """Reset the unique variable counter to a specific value.

    Parameters
    ----------
    value : int
        The value to reset the counter to (default 0)
    """
    global _unique_var_counter
    _unique_var_counter = value


class VarsUnique:
    """Generate unique variable names to prevent variable name collisions.

    Unlike Vars which uses the provided names directly, VarsUnique appends
    a unique counter suffix to each variable name. This is useful for
    library functions that need to avoid variable name collisions with
    the calling context.

    Example
    -------
    >>> v = VarsUnique('x', 'y', 'z')
    >>> print(v.x.name)  # 'x_1'
    >>> print(v.y.name)  # 'y_2'
    >>> v2 = VarsUnique('x')  # Different call
    >>> print(v2.x.name)  # 'x_3' (different from v.x)
    """

    def __init__(self, *args):
        global _unique_var_counter
        for arg in args:
            _unique_var_counter += 1
            unique_name = f"{arg}_{_unique_var_counter}"
            setattr(self, arg, Var(unique_name))


class Doc:
    def __init__(self, dictionary):
        self.dictionary = dictionary
        self.encoded = self._convert(dictionary)

    def __str__(self):
        return str(self.dictionary)

    def to_dict(self):
        return self.encoded

    def _convert(self, obj):
        if type(obj) is str:
            return {"@type": "Value", "data": {"@type": "xsd:string", "@value": obj}}
        elif type(obj) is bool:
            return {"@type": "Value", "data": {"@type": "xsd:boolean", "@value": obj}}
        elif type(obj) is int:
            return {"@type": "Value", "data": {"@type": "xsd:integer", "@value": obj}}
        elif type(obj) is float:
            return {"@type": "Value", "data": {"@type": "xsd:decimal", "@value": obj}}
        elif obj is None:
            return None
        elif type(obj) is list:
            ls = []
            for elt in obj:
                ls.append(self._convert(elt))
            return {"@type": "Value", "list": ls}
        elif isinstance(obj, Var):
            return {"@type": "Value", "variable": obj.name}
        elif type(obj) is dict:
            keys = obj.keys()
            pairs = []
            for key in keys:
                v = obj[key]
                val = self._convert(v)
                pairs.append({"@type": "FieldValuePair", "field": key, "value": val})
            return {
                "@type": "Value",
                "dictionary": {"@type": "DictionaryTemplate", "data": pairs},
            }


class WOQLQuery:
    def __init__(self, query=None, graph="schema"):
        """defines the internal functions of the woql query object - the language API is defined in WOQLQuery

        Parameters
        ----------
        query: dict
               json-ld query for initialisation
        graph: str
               graph that this query is appled to, default to be schema/main"""
        if query:
            self._query = query
        else:
            self._query = {}
        self._cursor = self._query
        self._chain_ended = False
        self._contains_update = False
        self._triple_builder_context = {}
        self._vocab = SHORT_NAME_MAPPING
        self._update_operators = UPDATE_OPERATORS

        # alias
        self.subsumption = self.sub
        self.equals = self.eq
        self.substring = self.substr
        self.update = self.update_document  # self.update_object
        self.delete = self.delete_document  # self.delete_object
        self.read = self.read_document  # self.read_object
        self.insert = self.insert_document
        self.optional = self.opt
        self.idgenerator = self.idgen
        self.concatenate = self.concat
        self.typecast = self.cast

        # attribute for schema
        self._graph = graph

    def __add__(self, other):
        """Creates a logical AND with the argument passed, for WOQLQueries.

        Parameters
        ----------
        other : WOQLQuery object

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        return WOQLQuery().woql_and(self, other)

    def __and__(self, other):
        """Creates a logical AND with the argument passed, for WOQLQueries.

        Parameters
        ----------
        other : WOQLQuery object

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        return WOQLQuery().woql_and(self, other)

    def __or__(self, other):
        """Creates a logical OR with the argument passed, for WOQLQueries.

        Parameters
        ----------
        other : WOQLQuery object

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        return WOQLQuery().woql_or(self, other)

    def __invert__(self):
        """Creates a logical Not with the argument passed, for WOQLQueries.

        Parameters
        ----------
        other : WOQLQuery object

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        return WOQLQuery().woql_not(self)

    def _add_sub_query(self, sub_query=None):
        """Internal library function which adds a subquery and sets the cursor"""
        if sub_query:
            self._cursor["query"] = self._coerce_to_dict(sub_query)
        else:
            initial_object = {}
            self._cursor["query"] = initial_object
            self._cursor = initial_object
        return self

    def _contains_update_check(self, json=None):
        """Does this query contain an update"""
        if not json:
            json = self._query
        if not isinstance(json, dict):
            return False
        if json["@type"] in self._update_operators:  # won't work
            return True
        if json.get("consequent") and self._contains_update_check(json["consequent"]):
            return True
        if json.get("query"):
            return self._contains_update_check(json["query"])
        if json.get("and"):
            for item in json["and"]:
                if self._contains_update_check(item):
                    return True
        if json.get("or"):
            for item in json["or"]:
                if self._contains_update_check(item):
                    return True

        return False

    def _updated(self):
        """Called to inidicate that this query will cause an update to the DB"""
        self._contains_update = True
        return self

    # A bunch of internal functions for formatting values for JSON-LD translation

    def _jlt(self, val, val_type=None):
        """Wraps the passed value in a json-ld literal carriage"""
        if not val_type:
            val_type = "xsd:string"
        elif ":" not in val_type:
            val_type = "xsd:" + val_type
        return {"@type": val_type, "@value": val}

    def _varj(self, varb):
        if isinstance(varb, Var):
            return {"@type": "Value", "variable": varb.name}
        if varb[:2] == "v:":
            varb = varb[2:]
        if type(varb) is str:
            return {"@type": "Value", "variable": varb}
        return varb

    def _coerce_to_dict(self, qobj):
        """Transforms a object representation of a query into a dictionary object if needs be"""
        if hasattr(qobj, "to_dict"):
            return qobj.to_dict()
        if qobj is True:
            return {"@type": "True"}
        return qobj

    def _raw_var(self, varb):
        if isinstance(varb, Var):
            return varb.name
        if varb[:2] == "v:":
            return varb[2:]
        return varb

    def _raw_var_list(self, vl):
        ret = []
        for v in vl:
            ret.append(self._raw_var(v))
        return ret

    def _data_list(self, wvar):
        # TODO: orig is Nonetype
        """takes input that can be either a string (variable name)
        or an array - each element of the array is a member of the list"""
        if type(wvar) is str or isinstance(wvar, Var):
            return self._expand_data_variable(wvar, True)
        if type(wvar) is list:
            ret = []
            for item in wvar:
                co_item = self._clean_data_value(item)
                ret.append(co_item)
            return {"@type": "DataValue", "list": ret}

    def _value_list(self, wvar):
        # TODO: orig is Nonetype
        """takes input that can be either a string (variable name)
        or an array - each element of the array is a member of the list"""
        if type(wvar) is str or isinstance(wvar, Var):
            return self._expand_value_variable(wvar, True)
        if type(wvar) is list:
            ret = []
            for item in wvar:
                co_item = self._clean_object(item)
                ret.append(co_item)
            return ret

    def _asv(self, colname_or_index, vname, obj_type=None):
        """Wraps the elements of an AS variable in the appropriate json-ld"""
        asvar = {}
        if type(colname_or_index) is int:
            asvar["@type"] = "Column"
            asvar["indicator"] = {"@type": "Indicator", "index": colname_or_index}
        elif type(colname_or_index) is str:
            asvar["@type"] = "Column"
            asvar["indicator"] = {"@type": "Indicator", "name": colname_or_index}
        if isinstance(vname, Var):
            vname = vname.name
        elif vname[:2] == "v:":
            vname = vname[2:]
        asvar["variable"] = vname
        if obj_type:
            asvar["type"] = obj_type
        return asvar

    def _wfrom(self, opts):
        """JSON LD Format Descriptor"""
        if opts and opts.get("format"):
            self._cursor["format"] = {
                "@type": "Format",
                "format_type": {"@value": opts["format"], "@type": "xsd:string"},
            }
            if opts.get("format_header"):
                self._cursor["format"]["format_header"] = {
                    "@value": True,
                    "@type": "xsd:boolean",
                }
        return self

    def _arop(self, arg):
        """Wraps arithmetic operators in the appropriate json-ld"""
        if type(arg) is dict:
            if hasattr(arg, "to_dict"):
                return arg.to_dict()
            else:
                return arg
        var = self._clean_arithmetic_value(arg, "xsd:decimal")
        return var

    def _vlist(self, target_list):
        """Wraps value lists in the appropriate json-ld"""
        vl = []
        for item in target_list:
            v = self._expand_value_variable(item)
            vl.append(v)
        return vl

    def _data_value_list(self, target_list):
        dvl = []
        for item in target_list:
            o = self.clean_data_value(item)
            dvl.append(o)
        return dvl

    def _clean_subject(self, obj):
        """Transforms whatever is passed in as the subject into the appropriate json-ld for variable or id"""
        subj = False
        if type(obj) is dict:
            return obj
        elif type(obj) is str:
            if ":" in obj:
                subj = obj
            elif self._vocab and (obj in self._vocab):
                subj = self._vocab[obj]
            else:
                subj = obj
            return self._expand_node_variable(subj)
        elif isinstance(obj, Var):
            return self._expand_node_variable(obj)
        raise ValueError("Subject must be a URI string")

    def _clean_predicate(self, obj):
        """Transforms whatever is passed in as the predicate (id or variable) into the appropriate json-ld form"""
        pred = False
        if type(obj) is dict:
            return obj
        elif type(obj) is str:
            if ":" in obj:
                pred = obj
            elif self._vocab and (obj in self._vocab):
                pred = self._vocab[obj]
            else:
                pred = obj
            return self._expand_node_variable(pred)
        elif isinstance(obj, Var):
            return self._expand_node_variable(obj)
        raise ValueError("Predicate must be a URI string")

    def _clean_path_predicate(self, predicate=None):
        pred = False
        if predicate is not None:
            if ":" in predicate:
                pred = predicate
            elif self._vocab and (predicate in self._vocab):
                pred = self._vocab[predicate]
            else:
                pred = predicate
        return pred

    def _clean_object(self, user_obj, target=None):
        """Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)"""
        obj = {"@type": "Value"}
        if type(user_obj) is str:
            if user_obj[:2] == "v:":
                return self._expand_value_variable(user_obj)
            else:
                obj["node"] = user_obj
        elif type(user_obj) is list:
            elts = []
            for item in user_obj:
                elts.append(self._clean_object(item))
            return elts
        elif isinstance(user_obj, Var):
            return self._expand_value_variable(user_obj)
        elif isinstance(user_obj, Doc):
            return user_obj.encoded
        elif type(user_obj) is float:
            if not target:
                target = "xsd:decimal"
            obj["data"] = self._jlt(user_obj, target)
        elif type(user_obj) is int:
            if not target:
                target = "xsd:integer"
            obj["data"] = self._jlt(user_obj, target)
        elif type(user_obj) is bool:
            if not target:
                target = "xsd:boolean"
            obj["data"] = self._jlt(user_obj, target)
        elif isinstance(user_obj, dt.date):
            if not target:
                target = "xsd:dateTime"
            obj["data"] = self._jlt(user_obj.isoformat(), target)
        elif type(user_obj) is dict:
            if "@value" in user_obj:
                obj["data"] = user_obj
            else:
                return user_obj
        else:
            obj["data"] = self._jlt(str(user_obj))
        return obj

    def _clean_data_value(self, user_obj, target=None):
        """Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)"""
        obj = {"@type": "DataValue"}
        if type(user_obj) is str:
            if user_obj[:2] == "v:":
                return self._expand_data_variable(user_obj)
            else:
                if not target:
                    target = "xsd:string"
                obj["data"] = self._jlt(user_obj, target)
        elif isinstance(user_obj, Var):
            return self._expand_data_variable(user_obj)
        elif type(user_obj) is float:
            if not target:
                target = "xsd:decimal"
            obj["data"] = self._jlt(user_obj, target)
        elif type(user_obj) is int:
            if not target:
                target = "xsd:integer"
            obj["data"] = self._jlt(user_obj, target)
        elif type(user_obj) is bool:
            if not target:
                target = "xsd:boolean"
            obj["data"] = self._jlt(user_obj, target)
        elif isinstance(user_obj, dt.date):
            if not target:
                target = "xsd:dateTime"
            obj["data"] = self._jlt(user_obj.isoformat(), target)
        elif type(user_obj) is dict:
            if "@value" in user_obj:
                obj["data"] = user_obj
            else:
                return user_obj
        else:
            obj["data"] = self._jlt(str(user_obj))
        return obj

    def _clean_arithmetic_value(self, user_obj, target=None):
        """Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)"""
        obj = {"@type": "ArithmeticValue"}
        if type(user_obj) is str:
            if user_obj[:2] == "v:":
                return self._expand_arithmetic_variable(user_obj)
            else:
                obj["data"] = self._jlt(user_obj, target)
        elif type(user_obj) is float:
            if not target:
                target = "xsd:decimal"
            obj["data"] = self._jlt(user_obj, target)
        elif type(user_obj) is int:
            if not target:
                target = "xsd:integer"
            obj["data"] = self._jlt(user_obj, target)
        elif type(user_obj) is bool:
            if not target:
                target = "xsd:boolean"
            obj["data"] = self._jlt(user_obj, target)
        elif isinstance(user_obj, dt.date):
            if not target:
                target = "xsd:dateTime"
            obj["data"] = self._jlt(user_obj.isoformat(), target)
        elif type(user_obj) is dict:
            if "@value" in user_obj:
                obj["data"] = user_obj
            else:
                return user_obj
        else:
            obj["data"] = self._jlt(str(user_obj))
        return obj

    def _clean_node_value(self, user_obj, target=None):
        """Transforms whatever is passed in as the object of a triple into the appropriate json-ld form (variable, literal or id)"""
        obj = {"@type": "NodeValue"}
        if type(user_obj) is str:
            if user_obj[:2] == "v:":
                return self._expand_node_variable(user_obj)
            else:
                obj["node"] = user_obj
        elif isinstance(user_obj, Var):
            return self._expand_node_variable(user_obj)
        elif type(user_obj) is dict:
            return user_obj
        else:
            obj["node"] = user_obj
        return obj

    def _clean_graph(self, graph):
        """Transforms a graph filter by doing nothing"""
        return graph

    def _expand_variable(self, varname, target_type, always=False):
        """Transforms strings that start with v: into variable json-ld structures

        Parameters
        ----------
        varname : str
                  will be transformed if it starts with 'v:'
        always : bool
                 if True it will be transformed no matter it starts with 'v:' or not. Default to be False
        """
        if isinstance(varname, Var):
            return {"@type": target_type, "variable": varname.name}
        if varname[:2] == "v:" or always:
            if varname[:2] == "v:":
                varname = varname[2:]
            return {"@type": target_type, "variable": varname}
        else:
            return {"@type": target_type, "node": varname}

    def _expand_value_variable(self, varname, always=False):
        return self._expand_variable(varname, "Value", always)

    def _expand_node_variable(self, varname, always=False):
        return self._expand_variable(varname, "NodeValue", always)

    def _expand_data_variable(self, varname, always=False):
        return self._expand_variable(varname, "DataValue", always)

    def _expand_arithmetic_variable(self, varname, always=False):
        return self._expand_variable(varname, "ArithmeticValue", always)

    def execute(self, client, commit_msg=None, file_dict=None):
        """Executes the query using the passed client to connect to a server

        Parameters
        ----------
        client: Client object
            client that provide connection to the database for the query to execute.
        commit_msg: str
            optional, commit message for this query. Recommended for query that carrries an update.
        file_dict:
            File dictionary to be associated with post name => filename, for multipart POST

        """
        if commit_msg is None:
            return client.query(self)
        else:
            return client.query(self, commit_msg)

    def to_json(self):
        """Dumps the JSON-LD format of the query in a json string"""
        return self._json()

    def from_json(self, input_json):
        """Set a query from a JSON-LD json string"""
        return self._json(input_json)

    def _json(self, input_json=None):
        """converts back and forward from json
        if the argument is present, the current query is set to it,
        if the argument is not present, the current json version of this query is returned
        """
        if input_json:
            self.from_dict(json.loads(input_json))
            return self
        else:
            return json.dumps(self.to_dict(), sort_keys=True)

    def to_dict(self):
        """Give the dictionary that represents the query in JSON-LD format."""
        return _copy_dict(self._query, True)

    def from_dict(self, dictdata):
        """Set a query from a dictionary that represents the query in JSON-LD format."""
        self._query = _copy_dict(dictdata)
        return self

    def _find_last_subject(self, json):
        """Finds the last woql element that has a subject in it and returns the json for that
        used for triplebuilder to chain further calls - when they may be inside ands or ors or subqueries

        Parameters
        ----------
        json : dict
               dictionary that representing the query in josn-ld"""
        if "and" in json:
            for item in json["and"][::-1]:
                subitem = self._find_last_subject(item)
                if subitem:
                    return subitem
        if "or" in json:
            for item in json["or"][::-1]:
                subitem = self._find_last_subject(item)
                if subitem:
                    return subitem

        if "query" in json:
            item = self._find_last_subject(json["query"])
            if item:
                return item
        if "subject" in json:
            return json
        return False

    def _find_last_property(self, json):
        """Finds the last woql property that has a subject in it and returns the json for that
        used for triplebuilder to chain further calls - when they may be inside ands or ors or subqueries

        Parameters
        ----------
        json : dict
               dictionary that representing the query in josn-ld"""
        if "and" in json:
            for item in json["and"][::-1]:
                subitem = self._find_last_property(item)
                if subitem:
                    return subitem
        if "or" in json:
            for item in json["or"][::-1]:
                subitem = self._find_last_property(item)
                if subitem:
                    return subitem

        if "query" in json:
            item = self._find_last_property(json["query"])
            if item:
                return item
        if "subject" in json and self._is_property_triple(
            json.get("predicate"), json.get("object")
        ):
            return json
        return False

    def _is_property_triple(self, pred, obj):
        if isinstance(pred, dict):
            p = pred.get("node")
        else:
            p = pred
        if isinstance(obj, dict):
            o = obj.get("node")
        else:
            o = obj
        if o == "owl:ObjectProperty" or o == "owl:DatatypeProperty":
            return True
        if p == "rdfs:domain" or p == "rdfs:range":
            return True
        return False

    def _compile_path_pattern(self, pat):
        """Turns a textual path pattern into a JSON-LD description"""
        toks = _path_tokenize(pat)
        if toks:
            return _path_tokens_to_json(toks)
        else:
            raise ValueError("Pattern error - could not be parsed " + pat)

    def load_vocabulary(self, client):
        """Queries the schema graph and loads all the ids found there as vocabulary that can be used without prefixes
        ignoring blank node ids"""
        new_woql = WOQLQuery().quad("v:S", "v:P", "v:O", "schema")
        result = new_woql.execute(client)
        bindings = result.get("bindings", [])
        for each_result in bindings:
            for item in each_result:
                if type(item) is str:
                    spl = item.split(":")
                    if len(spl) == 2 and spl[1] and spl[0] != "_":
                        self._vocab[spl[0]] = spl[1]

    def _wrap_cursor_with_and(self):
        if self._cursor.get("@type") == "And" and self._cursor.get("and"):
            next_item = len(self._cursor.get("and"))
            self.woql_and({})
            self._cursor = self._cursor["and"][next_item]
        else:
            new_json = WOQLQuery().from_dict(self._cursor)
            self._cursor.clear()
            self.woql_and(new_json, {})
            self._cursor = self._cursor["and"][1]

    def using(self, collection, subq=None):
        """Use a specific data product for the enclosed query

        Parameters
        ----------
        collection : str
            the name of the data product
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """

        if collection and collection == "args":
            return ["collection", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Using"
        if not collection or not isinstance(collection, str):
            raise ValueError(
                "The first parameter to using must be a Collection ID (string)"
            )
        self._cursor["collection"] = collection
        return self._add_sub_query(subq)

    def comment(self, comment, subq=None):
        """Adds a text comment to a query - can also be used to wrap any part of a query to turn it off

        Parameters
        ----------
        comment : str
            text comment
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if comment and comment == "args":
            return ["comment", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Comment"
        self._cursor["comment"] = self._jlt(comment)
        return self._add_sub_query(subq)

    def select(self, *args):
        """Filters the query so that only the variables included in [V1...Vn] are returned in the bindings

        Parameters
        ----------
        args
            only these variables are returned

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        """Select the set of variables that the result will return"""
        queries = list(args)
        if queries and queries[0] == "args":
            return ["variables", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Select"
        if queries != [] and not queries:
            raise ValueError("Select must be given a list of variable names")
        if queries == []:
            embedquery = False
        elif hasattr(queries[-1], "to_dict"):
            embedquery = queries.pop()
        else:
            embedquery = False
        self._cursor["variables"] = self._raw_var_list(queries)
        return self._add_sub_query(embedquery)

    def distinct(self, *args):
        """Ensures that the solutions for the variables [V1...Vn] are distinct

        Parameters
        ----------
        args
            The variables to make distinct with the final argument being a query.

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        Example
        -------
        To load a local csv file:
        >>> x,y = WOQLQUery().vars("X","Y")
        >>> WOQLQuery().distinct(x).triple(x,'foo',y)
        See Also
        """
        """Select the set of variables that the result will return"""
        queries = list(args)
        if queries and queries[0] == "args":
            return ["variables", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Distinct"
        if queries != [] and not queries:
            raise ValueError("Distinct must be given a list of variable names")
        if queries == []:
            embedquery = False
        elif hasattr(queries[-1], "to_dict"):
            embedquery = queries.pop()
        else:
            embedquery = False
        self._cursor["variables"] = self._raw_var_list(queries)
        return self._add_sub_query(embedquery)

    def woql_and(self, *args):
        """Creates a logical AND of the arguments
        Commonly used to combine WOQLQueries.

        Parameters
        ----------
        args : WOQLQuery objects
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        queries = list(args)
        if self._cursor.get("@type") and self._cursor["@type"] != "And":
            new_json = WOQLQuery().from_dict(self._cursor)
            self._cursor.clear()
            queries = [new_json] + queries
        if queries and queries[0] == "args":
            return ["and"]
        self._cursor["@type"] = "And"
        if "and" not in self._cursor:
            self._cursor["and"] = []
        for item in queries:
            onevar = self._coerce_to_dict(item)
            if "@type" in onevar and onevar["@type"] == "And" and onevar["and"]:
                for each in onevar["and"]:
                    if each:
                        subvar = self._coerce_to_dict(each)
                        self._cursor["and"].append(subvar)
            else:
                self._cursor["and"].append(onevar)
        return self

    def woql_or(self, *args):
        """Creates a logical OR of the arguments

        Parameters
        ----------
        args : WOQLQuery objects

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        queries = list(args)
        if queries and queries[0] == "args":
            return ["or"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Or"
        if "or" not in self._cursor:
            self._cursor["or"] = []
        for item in queries:
            onevar = self._coerce_to_dict(item)
            self._cursor["or"].append(onevar)
        return self

    def woql_from(self, graph, query=None):
        """Specifies the database URL that will be the default database for the enclosed query

        Parameters
        ----------
        graph : str
            url of the database
        query : WOQLQuery object, optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if graph and graph == "args":
            return ["graph", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "From"
        if not graph or not isinstance(graph, str):
            raise ValueError(
                "The first parameter to from must be a Graph Filter Expression (string)"
            )
        self._cursor["graph"] = graph
        return self._add_sub_query(query)

    def into(self, graph_descriptor, query):
        """Sets the current output graph for writing output to.

        Parameters
        ----------
        graph_descriptor : str
            output graph
        query : WOQLQuery object, optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if graph_descriptor and graph_descriptor == "args":
            return ["graph", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Into"
        if not graph_descriptor or not isinstance(graph_descriptor, str):
            raise ValueError(
                "The first parameter to from must be a Graph Filter Expression (string)"
            )
        self._cursor["graph"] = graph_descriptor
        return self._add_sub_query(query)

    def triple(self, sub, pred, obj, opt=False):
        """Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object)

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI)
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object, can be variable or node or value
        opt : bool
            whether or not this triple is optional, default to be False

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if opt:
            return self.opt().triple(sub, pred, obj)
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Triple"
        self._cursor["subject"] = self._clean_subject(sub)
        self._cursor["predicate"] = self._clean_predicate(pred)
        self._cursor["object"] = self._clean_object(obj)
        return self

    def triple_slice(self, sub, pred, obj, low, high):
        """Creates a triple pattern matching rule for [S, P, O] with a half-open
        value range [low, high) on the object. Returns triples whose typed object
        value falls within the specified range.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object, can be variable or node or value
        low : object
            The inclusive lower bound as a typed value
        high : object
            The exclusive upper bound as a typed value

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "TripleSlice"
        self._cursor["subject"] = self._clean_subject(sub)
        self._cursor["predicate"] = self._clean_predicate(pred)
        self._cursor["object"] = self._clean_object(obj)
        self._cursor["low"] = self._clean_object(low)
        self._cursor["high"] = self._clean_object(high)
        return self

    def quad_slice(self, sub, pred, obj, low, high, graph):
        """Creates a triple pattern matching rule for [S, P, O, G] with a half-open
        value range [low, high) on the object and an explicit graph selector.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object, can be variable or node or value
        low : object
            The inclusive lower bound as a typed value
        high : object
            The exclusive upper bound as a typed value
        graph : str
            Graph resource identifier (e.g. 'instance' or 'schema')

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        self.triple_slice(sub, pred, obj, low, high)
        self._cursor["graph"] = self._clean_graph(graph)
        return self

    def triple_slice_rev(self, sub, pred, obj, low, high):
        """Creates a triple pattern matching rule for [S, P, O] with a half-open
        value range [low, high) on the object, returning results in reverse
        (descending) object order. Same semantics as triple_slice but iterates
        from highest to lowest value.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object, can be variable or node or value
        low : object
            The inclusive lower bound as a typed value
        high : object
            The exclusive upper bound as a typed value

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "TripleSliceRev"
        self._cursor["subject"] = self._clean_subject(sub)
        self._cursor["predicate"] = self._clean_predicate(pred)
        self._cursor["object"] = self._clean_object(obj)
        self._cursor["low"] = self._clean_object(low)
        self._cursor["high"] = self._clean_object(high)
        return self

    def quad_slice_rev(self, sub, pred, obj, low, high, graph):
        """Creates a triple pattern matching rule for [S, P, O, G] with a half-open
        value range [low, high) on the object in reverse order, with an explicit
        graph selector.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object, can be variable or node or value
        low : object
            The inclusive lower bound as a typed value
        high : object
            The exclusive upper bound as a typed value
        graph : str
            Graph resource identifier (e.g. 'instance' or 'schema')

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        self.triple_slice_rev(sub, pred, obj, low, high)
        self._cursor["graph"] = self._clean_graph(graph)
        return self

    def triple_next(self, sub, pred, obj, next_val):
        """Finds the next object value after a reference for a given subject-predicate pair.
        When object is bound and next is free, finds the smallest next > object.
        When next is bound and object is free, finds the largest object < next.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object value or variable
        next_val : object
            Next object value or variable

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "TripleNext"
        self._cursor["subject"] = self._clean_subject(sub)
        self._cursor["predicate"] = self._clean_predicate(pred)
        self._cursor["object"] = self._clean_object(obj)
        self._cursor["next"] = self._clean_object(next_val)
        return self

    def quad_next(self, sub, pred, obj, next_val, graph):
        """Finds the next object value with an explicit graph selector.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object value or variable
        next_val : object
            Next object value or variable
        graph : str
            Graph resource identifier (e.g. 'instance' or 'schema')

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        self.triple_next(sub, pred, obj, next_val)
        self._cursor["graph"] = self._clean_graph(graph)
        return self

    def triple_previous(self, sub, pred, obj, prev_val):
        """Finds the previous object value before a reference for a given subject-predicate pair.
        When object is bound and previous is free, finds the largest previous < object.
        When previous is bound and object is free, finds the smallest object > previous.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object value or variable
        prev_val : object
            Previous object value or variable

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "TriplePrevious"
        self._cursor["subject"] = self._clean_subject(sub)
        self._cursor["predicate"] = self._clean_predicate(pred)
        self._cursor["object"] = self._clean_object(obj)
        self._cursor["previous"] = self._clean_object(prev_val)
        return self

    def quad_previous(self, sub, pred, obj, prev_val, graph):
        """Finds the previous object value with an explicit graph selector.

        Parameters
        ----------
        sub : str
            Subject, has to be a node (URI) or variable
        pred : str
            Predicate, can be variable (prefix with "v:") or node
        obj : str
            Object value or variable
        prev_val : object
            Previous object value or variable
        graph : str
            Graph resource identifier (e.g. 'instance' or 'schema')

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        self.triple_previous(sub, pred, obj, prev_val)
        self._cursor["graph"] = self._clean_graph(graph)
        return self

    def added_triple(self, sub, pred, obj, opt=False):
        """Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added to the current commit.

        Parameters
        ----------
        sub : str
            Subject
        pred : str
            Predicate
        obj : str
            Object
        opt : bool
            weather or not this triple is optional, default to be False

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if opt:
            return self.opt().triple(sub, pred, obj)
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "AddedTriple"
        self._cursor["subject"] = self._clean_subject(sub)
        self._cursor["predicate"] = self._clean_predicate(pred)
        self._cursor["object"] = self._clean_object(obj)
        return self

    def removed_triple(self, sub, pred, obj, opt=False):
        """Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) added to the current commit.

        Parameters
        ----------
        sub : str
            Subject
        pred : str
            Predicate
        obj : str
            Object
        opt : bool
            weather or not this triple is optional, default to be False

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if opt:
            return self.opt().triple(sub, pred, obj)
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "DeletedTriple"
        self._cursor["subject"] = self._clean_subject(sub)
        self._cursor["predicate"] = self._clean_predicate(pred)
        self._cursor["object"] = self._clean_object(obj)
        return self

    def quad(self, sub, pred, obj, graph, opt=False):
        """Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph)

        Parameters
        ----------
        sub : str
            Subject
        pre : str
            Predicate
        obj : str
            Object
        gra : str
            Graph
        opt : bool
            weather or not this quad is optional, default to be False

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if opt:
            return self.opt().quad(sub, pred, obj, graph)
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        arguments = self.triple(sub, pred, obj)
        if sub and sub == "args":
            return arguments.append("graph")
        if not graph:
            raise ValueError(
                "Quad takes four parameters, the last should be a graph filter"
            )
        self._cursor["@type"] = "Triple"
        self._cursor["graph"] = self._clean_graph(graph)
        return self

    def added_quad(self, sub, pred, obj, graph, opt=False):
        """Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) added to the current commit.

        Parameters
        ----------
        sub : str
            Subject
        pre : str
            Predicate
        obj : str
            Object
        gra : str
            Graph
        opt : bool
            weather or not this quad is optional, default to be False

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if opt:
            return self.opt().quad(sub, pred, obj, graph)
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        arguments = self.triple(sub, pred, obj)
        if sub and sub == "args":
            return arguments.append("graph")
        if not graph:
            raise ValueError(
                "Quad takes four parameters, the last should be a graph filter"
            )
        self._cursor["@type"] = "AddedTriple"
        self._cursor["graph"] = self._clean_graph(graph)
        return self

    def removed_quad(self, sub, pred, obj, graph, opt=False):
        """Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) added to the current commit.

        Parameters
        ----------
        sub : str
            Subject
        pre : str
            Predicate
        obj : str
            Object
        gra : str
            Graph
        opt : bool
            weather or not this quad is optional, default to be False

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if opt:
            return self.opt().quad(sub, pred, obj, graph)
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        arguments = self.triple(sub, pred, obj)
        if sub and sub == "args":
            return arguments.append("graph")
        if not graph:
            raise ValueError(
                "Quad takes four parameters, the last should be a graph filter"
            )
        self._cursor["@type"] = "DeletedTriple"
        self._cursor["graph"] = self._clean_graph(graph)
        return self

    def string(self, input_str):
        """Transforms the given string into the proper json-ld form

        Parameters
        ----------
        input_str : str
            the given input string

        Returns
        -------
        dict
        """
        return {"@type": "xsd:string", "@value": input_str}

    def boolean(self, input_bool):
        """Transforms the given bool object into the proper json-ld form

        Parameters
        ----------
        input_bool : bool
            the given input string

        Returns
        -------
        dict
        """
        if input_bool:
            return {"@type": "xsd:boolean", "@value": True}
        else:
            return {"@type": "xsd:boolean", "@value": False}

    def datetime(self, input_obj):
        """Transforms the given datetime object into the proper json-ld form

        Parameters
        ----------
        input_obj : str
            the given input dateTime object or a datetime string format YYYY-MM-DDThh-mm-ssZ

        Returns
        -------
        dict
        """
        if isinstance(input_obj, dt.date):
            return {"@type": "xsd:dateTime", "@value": input_obj.isoformat()}
        elif isinstance(input_obj, str):
            return {"@type": "xsd:dateTime", "@value": input_obj}
        else:
            raise ValueError("Input need to be either string or a datetime object.")

    def date(self, input_obj):
        """Transforms the given date object into the proper json-ld form

        Parameters
        ----------
        input_obj : str
            the given input date object or a date string format YYYY-MM-DD

        Returns
        -------
        dict
        """
        if isinstance(input_obj, dt.date):
            return {"@type": "xsd:date", "@value": input_obj.isoformat()}
        elif isinstance(input_obj, str):
            return {"@type": "xsd:date", "@value": input_obj}
        else:
            raise ValueError("Input need to be either string or a date object.")

    def literal(self, input_val, input_type):
        if ":" not in input_type:
            input_type = "xsd:" + input_type
        return {"@type": input_type, "@value": input_val}

    def iri(self, varname):
        return {
            "@type": "NodeValue",
            "node": varname,
        }

    def sub(self, parent, child):
        """Returns true if child is a sub-class of parent, according to the current DB schema

        Parameters
        ----------
        parent : str
            the parent class to be checked
        child : str, optional
            the child class to be checked

        Returns
        -------
        bool
        """
        if parent and parent == "args":
            return ["parent", "child"]
        if parent is None or child is None:
            raise ValueError("Subsumption takes two parameters, both URIs")
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Subsumption"
        self._cursor["parent"] = self._clean_node_value(parent)
        self._cursor["child"] = self._clean_node_value(child)
        return self

    def eq(self, left, right):
        """Matches if a is equal to b
        Parameters
        ----------
        left : str
            object in the graph
        right : str
            object in the graph
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if left and left == "args":
            return ["left", "right"]
        if left is None or right is None:
            raise ValueError("Equals takes two parameters")
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Equals"
        self._cursor["left"] = self._clean_object(left)
        self._cursor["right"] = self._clean_object(right)
        return self

    def substr(self, string, length, substring, before=0, after=0):
        if string and string == "args":
            return [
                "string",
                "before",
                "length",
                "after",
                "substring",
            ]
        if not substring:
            substring = length
            length = len(substring) + before
        if not string or not substring or not isinstance(substring, str):
            raise ValueError(
                "Substr - the first and last parameters must be strings representing the full and substring variables / literals"
            )
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Substring"
        self._cursor["string"] = self._clean_data_value(string, "xsd:string")
        self._cursor["before"] = self._clean_data_value(
            before, "xsd:nonNegativeInteger"
        )
        self._cursor["length"] = self._clean_data_value(
            length, "xsd:nonNegativeInteger"
        )
        self._cursor["after"] = self._clean_data_value(after, "xsd:nonNegativeInteger")
        self._cursor["substring"] = self._clean_data_value(substring, "xsd:string")
        return self

    def update_object(self, docjson):
        warnings.warn(
            DeprecationWarning("update_object() is deprecated; use update_document()"),
            stacklevel=2,
        )
        return self.update_document(docjson)
        # if docjson and docjson == "args":
        #     return ["document"]
        # if self._cursor.get("@type"):
        #     self._wrap_cursor_with_and()
        # self._cursor["@type"] = "UpdateObject"
        # if isinstance(docjson, str):
        #     doc = self._expand_data_value(docjson)
        # else:
        #     doc = docjson
        # self._cursor["document"] = doc
        # return self._updated()

    def update_document(self, docjson, json_or_iri=None):
        """Update a document in the database

        Parameters
        ----------
        docjson : JSON
            object to be updated
        json_or_iri : str
            the output ID, or a JSON to compare the ID against
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if docjson and docjson == "args":
            return ["document"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "UpdateDocument"
        if isinstance(docjson, str):
            doc = self._expand_value_variable(docjson)
        else:
            doc = docjson
        self._cursor["document"] = doc
        if json_or_iri is not None:
            self._cursor["identifier"] = self._clean_node_value(json_or_iri)
        return self._updated()

    def insert_document(self, docjson, json_or_iri=None):
        """Insert a document into the database

        Parameters
        ----------
        docjson : JSON
            object to be inserted
        json_or_iri : str
            the output ID, or a JSON to compare the ID against
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if docjson and docjson == "args":
            return ["document"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "InsertDocument"
        if isinstance(docjson, str):
            doc = self._expand_value_variable(docjson)
        else:
            doc = docjson
        self._cursor["document"] = doc
        if json_or_iri is not None:
            self._cursor["identifier"] = self._clean_node_value(json_or_iri)
        return self._updated()

    def delete_object(self, json_or_iri):
        warnings.warn(
            DeprecationWarning("delete_object() is deprecated; use delete_document()"),
            stacklevel=2,
        )
        return self.delete_document(json_or_iri)

    def delete_document(self, json_or_iri):
        """Delete a document into the database

        Parameters
        ----------
        docjson : JSON
            object to be deleted
        json_or_iri : str
            the output ID, or a JSON to compare the ID against
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if json_or_iri and json_or_iri == "args":
            return ["document"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "DeleteDocument"
        self._cursor["identifier"] = self._clean_node_value(json_or_iri)
        return self._updated()

    def read_object(self, iri, output_var):
        warnings.warn(
            DeprecationWarning("read_object() is deprecated; use read_document()"),
            stacklevel=2,
        )
        return self.read_document(iri, output_var)
        # if iri and iri == "args":
        #     return ["document"]
        # if self._cursor.get("@type"):
        #     self._wrap_cursor_with_and()
        # self._cursor["@type"] = "ReadObject"
        # self._cursor["document_uri"] = iri
        # self._cursor["document"] = self._expand_data_variable(output_var)
        # return self

    def read_document(self, iri, output_var):
        """Read a document from the database

        Parameters
        ----------
        iri : str
            object to be deleted
        output_var : str
            the document as JSON
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        Example
        -------
        >>> query = (WOQLQuery().triple('v:TermId', 'rdf:type', '@schema:Term') &
                     WOQLQuery().triple('v:TermCountId','term','v:TermId') &
                     WOQLQuery().triple('v:DocumentId', 'terms', 'v:TermCountId') &
                     WOQLQuery().read_document('v:TermId','v:TermDoc'))
        """
        if iri and iri == "args":
            return ["document"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "ReadDocument"
        self._cursor["identifier"] = self._clean_node_value(iri)
        self._cursor["document"] = self._expand_value_variable(output_var)
        return self

    def get(self, as_vars, query_resource=None):
        """Takes an as structure"""
        if as_vars and as_vars == "args":
            return ["columns", "resource"]
        self._cursor["@type"] = "Get"
        if hasattr(as_vars, "to_dict"):
            self._cursor["columns"] = as_vars.to_dict()
        else:
            self._cursor["columns"] = WOQLQuery().woql_as(*as_vars).to_dict()
        if query_resource:
            self._cursor["resource"] = self._coerce_to_dict(query_resource)
        else:
            self._cursor["resource"] = {}
        self._cursor = self._cursor["resource"]
        return self

    def put(self, as_vars, query, query_resource=None):
        """Takes an array of variables, an optional array of column names"""
        if as_vars and as_vars == "args":
            return ["columns", "query", "resource"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Put"
        if hasattr(as_vars, "to_dict"):
            self._cursor["columns"] = as_vars.to_dict()
        else:
            self._cursor["columns"] = WOQLQuery().woql_as(*as_vars).to_dict()
        self._cursor["query"] = self._coerce_to_dict(query)
        if query_resource:
            self._cursor["resource"] = self._coerce_to_dict(query_resource)
        else:
            self._cursor["resource"] = {}
        return self

    def woql_as(self, *args):
        if args and args[0] == "args":
            return [["indexed_as_var", "named_as_var"]]
        if type(self._query) is not list:
            self._query = []
        if type(args[0]) is list:
            if len(args) == 1:
                for i, onemap in enumerate(args[0]):
                    iasv = self._asv(i, onemap)
                    self._query.append(iasv)
            else:
                for onemap in args:
                    if type(onemap) is list and len(onemap) >= 2:
                        if len(onemap) == 2:
                            map_type = False
                        else:
                            map_type = onemap[2]
                        oasv = self._asv(onemap[0], onemap[1], map_type)
                        self._query.append(oasv)
        elif type(args[0]) in [int, str] or isinstance(args[0], Var):
            if len(args) > 2 and type(args[2]) is str:
                oasv = self._asv(args[0], args[1], args[2])
            elif len(args) > 1 and type(args[1]) is str:
                if args[1][:4] == "xsd:" or args[1][:4] == "xdd:":
                    oasv = self._asv(len(self._query), args[0], args[1])
                else:
                    oasv = self._asv(args[0], args[1])
            else:
                oasv = self._asv(len(self._query), args[0])
            self._query.append(oasv)
        elif hasattr(args[0], "to_dict"):
            self._query.append(args[0].to_dict())
        elif type(args[0]) is dict:
            self._query.append(args[0])

        return self

    def file(self, fpath, opts=None):
        """Provides details of a file source in a JSON format that includes a URL property

        Note: CSV files can no longer be read from the filesystem. Only files submitted
        as part of the request can be processed. Use remote() for URLs or submit files
        via the API.

        Parameters
        ----------
        fpath : dict or str
            file data source in a JSON format or file path
        opts : input options
            optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        Example
        -------
        To reference a file (must be submitted with request):
        >>> WOQLQuery().file("/app/local_files/my.csv")
        See Also
        --------
        remote
            If your csv file is a uri then use :meth:`.remote` instead of `.file`.
        """
        if opts is None:
            opts = []
        if fpath and fpath == "args":
            return ["source", "format"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "QueryResource"
        if isinstance(fpath, str):
            self._cursor["source"] = {"@type": "Source", "file": fpath}
        else:
            self._cursor["source"] = fpath
        self._cursor["format"] = "csv"
        if opts:
            self._cursor["options"] = opts
        return self._wfrom(opts)

    def once(self, query=None):
        """Obtains only one result from subquery

        Parameters
        ----------
        query : WOQLQuery object, optional

        Returns
        ----------
        WOQLQuery object
            query object that can be chained and/or executed
        """
        if query and query == "args":
            return ["query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Once"
        return self._add_sub_query(query)

    def remote(self, uri, opts=None):
        """Provides details of a remote data source in a JSON format that includes a URL property

        Parameters
        ----------
        uri : str
            remote data source
        opts : input options
            optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        Examples
        --------
        >>> csv = WOQLQuery().get(
        ...     WOQLQuery().woql_as("Start station", "v:Start_Station").
        ...     woql_as("End station", "v:End_Station").
        ...     woql_as("Start date", "v:Start_Time").
        ...     woql_as("End date", "v:End_Time").
        ...     woql_as("Duration", "v:Duration").
        ...     woql_as("Start station number", "v:Start_ID").
        ...     woql_as("End station number", "v:End_ID").
        ...     woql_as("Bike number", "v:Bike").
        ...     woql_as("Member type", "v:Member_Type")
        ... ).remote("https://terminusdb.com/t/data/bike_tutorial.csv")
        See Also
        --------
        file
            If your csv file is local then use :meth:`.file` instead of `.remote`.
        """
        if uri and uri == "args":
            return ["source", "format", "options"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "QueryResource"
        if isinstance(uri, dict):
            uri["@type"] = "Source"
            self._cursor["source"] = uri
        else:
            self._cursor["source"] = {"@type": "Source", "url": uri}
        self._cursor["format"] = "csv"
        if opts:
            self._cursor["options"] = opts
        return self

    def post(self, fpath, opts=None):
        """Specifies a file to be posted as part of the request for processing.

        Note: CSV files can no longer be read from the filesystem. Only files submitted
        as part of the request can be processed. This method should be used with files
        that are uploaded via the API.

        Parameters
        ----------
        fpath : str or dict
            file path/identifier or dict with file details
        opts : dict, optional
            additional options for file processing

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if fpath and fpath == "args":
            return ["source", "format", "options"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "QueryResource"
        if isinstance(fpath, dict):
            fpath["@type"] = "Source"
            self._cursor["source"] = fpath
        else:
            self._cursor["source"] = {"@type": "Source", "post": fpath}
        self._cursor["format"] = "csv"
        if opts:
            self._cursor["options"] = opts
        return self

    def delete_triple(self, subject, predicate, object_or_literal):
        """Deletes any triples that match the rule [subject, predicate, object]

        Parameters
        ----------
        subject : str
            Subject
        predicate : str
            Predicate
        object_or_literal : str
            Object or Literal

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        Examples
        --------
        This example deletes the comment triple of a particular value from the document
        identified by doc:X:
        >>> update = WOQLQuery().delete_triple("doc:X", "comment", "my comment")
        >>> qry = WOQLQuery().when(True, update)
        >>> client.update(qry.json(), 'MyDatabaseId')
        Note that only triples matching the particular object value will be deleted.
        To delete all triples matching this predicate, (regardless of value) we use a
        when clause, and introduce a variable ``v:any`` which will bind to any value
        for this subject and predicate combination:
        >>> when = WOQLQuery().triple('doc:X', 'comment', 'v:any')
        >>> update = WOQLQuery().delete_triple('doc:X', 'comment', 'v:any')
        >>> qry = WOQLQuery().when(when, update)
        >>> client.update(qry.json(), 'MyDatabaseId')
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        triple_args = self.triple(subject, predicate, object_or_literal)
        if subject and subject == "args":
            return triple_args
        self._cursor["@type"] = "DeleteTriple"
        return self._updated()

    def add_triple(self, subject, predicate, object_or_literal):
        """Adds triples according to the the pattern [subject, predicate, object]

        Parameters
        ----------
        subject : str
            Subject
        predicate : str
            Predicate
        object_or_literal : str
            Object or Literal

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute

        Examples
        --------
        This example adds a triple for a comment predicate and a certain value to the document identified by doc:X:
        >>> update = WOQLQuery().add_triple("doc:X", "comment", "my comment")
        >>> qry = WOQLQuery().when(True, update)
        >>> client.update(qry.json(), 'MyDatabaseId')

        Notes
        --------
        To update an existing triple, it is not just a case of calling `add_triple` again.
        One needs to delete the previous triple first.
        Otherwise two triples with the same predicate but different object values will be present.

        See Also
        --------
        delete_triple
        add_quad
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        triple_args = self.triple(subject, predicate, object_or_literal)
        if subject and subject == "args":
            return triple_args
        self._cursor["@type"] = "AddTriple"
        return self._updated()

    def update_triple(self, subject, predicate, new_object):
        return self.woql_and(
            WOQLQuery().opt(
                WOQLQuery()
                .triple(subject, predicate, "v:AnyObject")
                .delete_triple(subject, predicate, "v:AnyObject")
                .woql_not()
                .triple(subject, predicate, new_object)
            ),
            WOQLQuery().add_triple(subject, predicate, new_object),
        )

    def delete_quad(self, subject, predicate, object_or_literal, graph=None):
        """Deletes any quads that match the rule [subject, predicate, object, graph]

        Parameters
        ----------
        subject : str
            Subject
        predicate : str
            Predicate
        object_or_literal : str
            Object or Literal
        graph : str
            Graph

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        triple_args = self.triple(subject, predicate, object_or_literal)
        if subject and subject == "args":
            return triple_args.append("graph")
        if not graph:
            raise ValueError(
                "Delete Quad takes four parameters, the last should be a graph id"
            )
        self._cursor["@type"] = "DeleteTriple"
        self._cursor["graph"] = self._clean_graph(graph)
        return self._updated()

    def add_quad(self, subject, predicate, object_or_literal, graph):
        """Adds quads according to the pattern [subject, predicate, object, graph]

        Parameters
        ----------
        subject : str
            Subject
        predicate : str
            Predicate
        object_or_literal : str
            Object or Literal
        graph : str
            Graph

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        triple_args = self.triple(subject, predicate, object_or_literal)
        if subject and subject == "args":
            return triple_args.concat(["graph"])
        if not graph:
            raise ValueError(
                "Delete Quad takes four parameters, the last should be a graph id"
            )
        self._cursor["@type"] = "AddTriple"
        self._cursor["graph"] = self._clean_graph(graph)
        return self._updated()

    def update_quad(self, subject, predicate, new_object, graph):
        return self.woql_and(
            WOQLQuery().opt(
                WOQLQuery()
                .quad(subject, predicate, "v:AnyObject", graph)
                .delete_quad(subject, predicate, "v:AnyObject", graph)
                .woql_not()
                .quad(subject, predicate, new_object, graph)
            ),
            WOQLQuery().add_quad(subject, predicate, new_object, graph),
        )

    def trim(self, untrimmed, trimmed):
        """A trimmed version of untrimmed (with leading and trailing whitespace removed) is copied into trimmed

        Parameters
        ----------
        untrimmed : str
            original string
        trimmed : str
            WOQL varible storing the result string

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if untrimmed and untrimmed == "args":
            return ["untrimmed", "trimmed"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Trim"
        self._cursor["untrimmed"] = self._clean_data_value(untrimmed)
        self._cursor["trimmed"] = self._clean_data_value(trimmed)
        return self

    def eval(self, arith, res):
        """Evaluates the Arithmetic Expression Arith and copies the output to variable V

        Parameters
        ----------
        arith : WOQLQuery or dict
            query or JSON-LD representing the query
        res : str
            output variable

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if arith and arith == "args":
            return ["expression", "result"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Eval"
        if hasattr(arith, "to_dict"):
            self._cursor["expression"] = arith.to_dict()
        else:
            self._cursor["expression"] = arith
        self._cursor["result"] = self._clean_arithmetic_value(res)
        return self

    def plus(self, *args):
        """Adds numbers N1...Nn together

        Parameters
        ----------
        args : int or float
            numbers to add together

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        new_args = list(args)
        if new_args and new_args[0] == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Plus"
        self._cursor["left"] = self._arop(new_args.pop(0))
        if len(new_args) > 1:
            self._cursor = self._coerce_to_dict(WOQLQuery().plus(*new_args))
        else:
            self._cursor["right"] = self._arop(new_args[0])
        return self

    def minus(self, *args):
        """Adds numbers N1...Nn together

        Parameters
        ----------
        args : int or float
            numbers to add together

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        new_args = list(args)
        if new_args and new_args[0] == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Minus"
        self._cursor["left"] = self._arop(new_args.pop(0))
        if len(new_args) > 1:
            self._cursor["right"] = self._coerce_to_dict(WOQLQuery().minus(*new_args))
        else:
            self._cursor["right"] = self._arop(new_args[0])
        return self

    def times(self, *args):
        """Multiplies numbers N1...Nn together

        Parameters
        ----------
        args : int or float
            numbers to be multiplied

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        new_args = list(args)
        if new_args and new_args[0] == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Times"
        self._cursor["left"] = self._arop(new_args.pop(0))
        if len(new_args) > 1:
            self._cursor["right"] = self._coerce_to_dict(WOQLQuery().times(*new_args))
        else:
            self._cursor["right"] = self._arop(new_args[0])
        return self

    def divide(self, *args):
        """Divides numbers N1...Nn by each other left, to right precedence

        Parameters
        ----------
        args : int or float
            numbers to be divided

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        new_args = list(args)
        if new_args and new_args[0] == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Divide"
        self._cursor["left"] = self._arop(new_args.pop(0))
        if len(new_args) > 1:
            self._cursor["right"] = self._coerce_to_dict(WOQLQuery().divide(*new_args))
        else:
            self._cursor["right"] = self._arop(new_args[0])
        return self

    def div(self, *args):
        """Division - integer division - args are divided left to right

        Parameters
        ----------
        args : int or float
            numbers for division

        Returns
        -------
        WOQLQuery
            query object that can be chained and/or execute
        """
        new_args = list(args)
        if new_args and new_args[0] == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Div"
        self._cursor["left"] = self._arop(new_args.pop(0))
        if len(new_args) > 1:
            self._cursor["right"] = self._coerce_to_dict(WOQLQuery().div(*new_args))
        else:
            self._cursor["right"] = self._arop(new_args[0])
        return self

    def exp(self, first, second):
        """Raises A to the power of B

        Parameters
        ----------
        first : int or float
            base number
        second : int or float
            power of

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if first and first == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Exp"
        self._cursor["left"] = self._arop(first)
        self._cursor["right"] = self._arop(second)
        return self

    def floor(self, user_input):
        """The floor function of a real number x denotes the greatest integer less than or equal to x.

        Parameters
        ----------
        user_input : int or float
            number whose floor needs to be calculated

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if user_input and user_input == "args":
            return ["argument"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Floor"
        self._cursor["argument"] = self._arop(user_input)
        return self

    def isa(self, element, of_type):
        """Matches if element is a member of a certain type, according to the current state of the DB

        Parameters
        ----------
        element : str
            element to be checked
        of_type : str
            type to be checked

        Returns
        -------
        bool
        """
        if element and element == "args":
            return ["element", "type"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "IsA"
        self._cursor["element"] = self._clean_node_value(element)
        self._cursor["type"] = self._clean_node_value(of_type)
        return self

    def like(self, left, right, dist):
        """Matches left string to right string with a distance

        Parameters
        ----------
        left : str
            first string to compare
        right : str
            second string to compare
        dist : str
            Hamming distance between left and right
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if left and left == "args":
            return ["left", "right", "similarity"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Like"
        self._cursor["left"] = self._clean_data_value(left, "xsd:string")
        self._cursor["right"] = self._clean_data_value(right, "xsd:string")
        if dist:
            self._cursor["similarity"] = self._clean_object(dist, "xsd:decimal")
        return self

    def less(self, left, right):
        """Compares the value of v1 against v2 and returns true if v1 is less than v2

        Parameters
        ----------
        left : str
            first variable to compare
        right : str
            second variable to compare

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if left and left == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Less"
        self._cursor["left"] = self._clean_object(left)
        self._cursor["right"] = self._clean_object(right)
        return self

    def greater(self, left, right):
        """Compares the value of v1 against v2 and returns true if v1 is greater than v2

        Parameters
        ----------
        left : str
            first variable to compare
        right : str
            second variable to compare

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if left and left == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Greater"
        self._cursor["left"] = self._clean_object(left)
        self._cursor["right"] = self._clean_object(right)
        return self

    def opt(self, query=None):
        """The Query in the Optional argument is specified as optional

        Parameters
        ----------
        query : WOQLQuery object

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute

        Examples
        -------
        >>> WOQLQuery().woql_and(WOQLQuery().
        ... triple('v:MandatorySubject','v:MandatoryObject', 'v:MandatoryValue'),
        ... WOQLQuery.opt(WOQLQuery().triple('v:OptionalS', 'v:OptionalObject',
        ... 'v:OptionalValue'))
        ... )
        """
        if query and query == "args":
            return ["query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Optional"
        self._add_sub_query(query)
        return self

    def unique(self, prefix, key_list, uri):
        """Generates an ID for a node as a function of the passed VariableList with a specific prefix (URL base)(A.K.A Hashing) If the values of the passed variables are the same, the output will be the same

        Parameters
        ----------
        prefix : str
            prefix for the id
        key_list : str
            variable to generate id for
        uri : str
            the variable to hold the id

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute

        Examples
        -------
        >>> WOQLQuery().unique("https://base.url",["page","1"],"v:obj_id").execute(client)
        {'@type': 'api:WoqlResponse', 'api:status': 'api:success', 'api:variable_names': ['obj_id'], 'bindings': [{'obj_id': 'https://base.urlacd150a6885f609532931d89844070b1'}], 'deletes': 0, 'inserts': 0, 'transaction_retry_count': 0}
        """
        if prefix and prefix == "args":
            return ["base", "key_list", "uri"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "HashKey"
        self._cursor["base"] = self._clean_data_value(prefix)
        self._cursor["key_list"] = self._data_list(key_list)
        self._cursor["uri"] = self._clean_node_value(uri)
        return self

    def idgen(self, prefix, input_var_list, output_var):
        """Generates an ID for a node as a function of the passed VariableList with a specific prefix (URL base). If the values of the passed variables are the same, the output will be the same

        Parameters
        ----------
        prefix : str
            prefix for the id
        input_var_list : str or list
            variable to generate id for
        output_var : str
            the variable to hold the id

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute

        Examples
        -------
        >>> WOQLQuery().idgen("https://base.url",["page","1"],"v:obj_id").execute(client)
        {'@type': 'api:WoqlResponse', 'api:status': 'api:success', 'api:variable_names': ['obj_id'], 'bindings': [{'obj_id': 'https://base.url_page_1'}], 'deletes': 0, 'inserts': 0, 'transaction_retry_count': 0}
        """
        if prefix and prefix == "args":
            return ["base", "key_list", "uri"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "LexicalKey"
        self._cursor["base"] = self._clean_data_value(prefix)
        self._cursor["key_list"] = self._data_list(input_var_list)
        self._cursor["uri"] = self._clean_node_value(output_var)
        return self

    def idgen_random(self, prefix, uri):
        """Generates a unique ID with cryptographically secure random suffix.

        Uses base64 encoding to generate 16-character random IDs that are
        guaranteed to be unique across executions. Matches the server's
        idgen_random/2 predicate and maintains consistency with the JavaScript client.

        Parameters
        ----------
        prefix : str
            A prefix for the IDs to be generated (e.g. "Person/")
        uri : str
            Variable name or output target for the generated ID

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or executed

        Examples
        -------
        >>> WOQLQuery().idgen_random("Person/", "v:person_id").execute(client)
        {'@type': 'api:WoqlResponse', 'api:status': 'api:success', 'api:variable_names': ['person_id'], 'bindings': [{'person_id': 'Person/aB3dEf9GhI2jK4lM'}], 'deletes': 0, 'inserts': 0, 'transaction_retry_count': 0}
        """
        if prefix and prefix == "args":
            return ["base", "uri"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "RandomKey"
        self._cursor["base"] = self._clean_data_value(prefix)
        self._cursor["uri"] = self._clean_node_value(uri)
        return self

    def random_idgen(self, prefix, uri):
        """Generates a unique ID with cryptographically secure random suffix (alias for idgen_random).

        This is an alias for idgen_random() for compatibility with older code.
        Uses base64 encoding to generate 16-character random IDs that are
        guaranteed to be unique across executions.

        Parameters
        ----------
        prefix : str
            A prefix for the IDs to be generated (e.g. "Person/")
        uri : str
            Variable name or output target for the generated ID

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or executed

        Examples
        -------
        >>> WOQLQuery().random_idgen("Person/", "v:person_id").execute(client)
        {'@type': 'api:WoqlResponse', 'api:status': 'api:success', 'api:variable_names': ['person_id'], 'bindings': [{'person_id': 'Person/aB3dEf9GhI2jK4lM'}], 'deletes': 0, 'inserts': 0, 'transaction_retry_count': 0}
        """
        return self.idgen_random(prefix, uri)

    def upper(self, left, right):
        """Changes a string to upper-case - input is in left, output in right

        Parameters
        ----------
        left : str
            input string
        right : str
            stores output

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if left and left == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Upper"
        self._cursor["left"] = self._clean_data_value(left, "xsd:string")
        self._cursor["right"] = self._clean_data_value(right, "xsd:string")
        return self

    def lower(self, left, right):
        """Changes a string to lower-case - input is in u, output in l

        Parameters
        ----------
        left : str
            input string
        right : str
            stores output

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if left and left == "args":
            return ["left", "right"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Lower"
        self._cursor["left"] = self._clean_data_value(left, "xsd:string")
        self._cursor["right"] = self._clean_data_value(right, "xsd:string")
        return self

    def pad(self, user_input, pad, length, output):
        """
        Pads out the string input to be exactly len long by appending the pad character pad to form output

        Parameters
        ----------
        user_input : str
            input string
        pad : str
            padding character(s)
        length :  int
            length to pad
        output : str
            stores output

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if user_input and user_input == "args":
            return [
                "string",
                "char",
                "times",
                "result",
            ]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Pad"
        self._cursor["string"] = self._clean_data_value(user_input)
        self._cursor["char"] = self._clean_data_value(pad)
        self._cursor["times"] = self._clean_data_value(length, "xsd:integer")
        self._cursor["result"] = self._clean_data_value(output)
        return self

    def split(self, user_input, glue, output):
        """Splits a variable apart (input) into a list of variables (output) by separating the strings together with separator

        Parameters
        ----------
        user_input : str
            input string or WOQL variable "v:"
        glue : str
            character string to separate string into list
        output : str
            WOQL variable that stores output list

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if user_input and user_input == "args":
            return ["string", "pattern", "list"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Split"
        self._cursor["string"] = self._clean_data_value(user_input)
        self._cursor["pattern"] = self._clean_data_value(glue)
        self._cursor["list"] = self._data_list(output)
        return self

    def dot(self, document, field, value):
        """Iterates through a list and returns a value for each member

        Parameters
        ----------
        dictionary
            a WOQL dictionary or variable representing a dictionary
        field : str
            a string representing the field or key to access the dictionary
        value
            a WOQL value representing the result

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Dot"
        self._cursor["document"] = self._expand_value_variable(document)
        self._cursor["field"] = self._clean_data_value(field, "xsd:string")
        self._cursor["value"] = self._expand_value_variable(value)
        return self

    def member(self, member, mem_list):
        """Iterates through a list and returns a value for each member

        Parameters
        ----------
        member : str
            a WOQL variable representing an element of the list
        mem_list : str
            a WOQL list variable

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if member and member == "args":
            return ["member", "list"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Member"
        self._cursor["member"] = self._clean_object(member)
        self._cursor["list"] = self._value_list(mem_list)
        return self

    def set_difference(self, list_a, list_b, result):
        """Computes the set difference between two lists (elements in list_a but not in list_b)

        Parameters
        ----------
        list_a : str or list
            First list or variable
        list_b : str or list
            Second list or variable
        result : str
            Variable to store the result

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if list_a and list_a == "args":
            return ["list_a", "list_b", "result"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "SetDifference"
        self._cursor["list_a"] = self._value_list(list_a)
        self._cursor["list_b"] = self._value_list(list_b)
        self._cursor["result"] = self._value_list(result)
        return self

    def set_intersection(self, list_a, list_b, result):
        """Computes the set intersection of two lists (elements in both list_a and list_b)

        Parameters
        ----------
        list_a : str or list
            First list or variable
        list_b : str or list
            Second list or variable
        result : str
            Variable to store the result

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if list_a and list_a == "args":
            return ["list_a", "list_b", "result"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "SetIntersection"
        self._cursor["list_a"] = self._value_list(list_a)
        self._cursor["list_b"] = self._value_list(list_b)
        self._cursor["result"] = self._value_list(result)
        return self

    def set_union(self, list_a, list_b, result):
        """Computes the set union of two lists (all unique elements from both lists)

        Parameters
        ----------
        list_a : str or list
            First list or variable
        list_b : str or list
            Second list or variable
        result : str
            Variable to store the result

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if list_a and list_a == "args":
            return ["list_a", "list_b", "result"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "SetUnion"
        self._cursor["list_a"] = self._value_list(list_a)
        self._cursor["list_b"] = self._value_list(list_b)
        self._cursor["result"] = self._value_list(result)
        return self

    def set_member(self, element, set_list):
        """Checks if an element is a member of a set (efficient O(log n) lookup)

        Parameters
        ----------
        element : any
            Element to check
        set_list : str or list
            Set (list) to check membership in

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if element and element == "args":
            return ["element", "set"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "SetMember"
        self._cursor["element"] = self._clean_object(element)
        self._cursor["set"] = self._value_list(set_list)
        return self

    def list_to_set(self, input_list, result_set):
        """Converts a list to a set (removes duplicates and sorts)

        Parameters
        ----------
        input_list : str or list
            Input list or variable
        result_set : str
            Variable to store the resulting set

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if input_list and input_list == "args":
            return ["list", "set"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "ListToSet"
        self._cursor["list"] = self._value_list(input_list)
        self._cursor["set"] = self._value_list(result_set)
        return self

    def concat(self, concat_list, result):
        """Concatenates the list of variables into a string and saves the result in v

        Parameters
        ----------
        concat_list : list
            list of variables to concatenate
        result : str
            saves the results

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if concat_list and concat_list == "args":
            return ["list", "concatenated"]
        if type(concat_list) is str:
            slist = re.split("(v:)", concat_list)
            nlist = []
            if slist[0]:
                nlist.append(slist[0])
            for idx, item in enumerate(slist):
                if item and item == "v:":
                    slist2 = re.split(r"([^\w_])", slist[idx + 1])
                    x_var = slist2.pop(0)
                    nlist.append("v:" + x_var)
                    rest = "".join(slist2)
                    if rest:
                        nlist.append(rest)
            concat_list = nlist
        if type(concat_list) is list:
            if self._cursor.get("@type"):
                self._wrap_cursor_with_and()
            self._cursor["@type"] = "Concatenate"
            self._cursor["list"] = self._data_list(concat_list)
            self._cursor["result"] = self._clean_data_value(result)
        return self

    def join(self, user_input, glue, output):
        """
        Joins a list variable together (input) into a string variable (output) by glueing the strings together with glue

        Parameters
        ----------
        user_input : list
            a list of variables
        glue :  str
            jioining character(s)
        output : str
            variable that sotres output

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if user_input and user_input == "args":
            return ["list", "separator", "join"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Join"
        self._cursor["list"] = self._data_list(user_input)
        self._cursor["separator"] = self._clean_data_value(glue)
        self._cursor["result"] = self._clean_data_value(output)
        return self

    def sum(self, user_input, output):
        """
        Joins a list variable containing numbers together (input) into a single number
        containing the sum.

        Parameters
        ----------
        user_input : list
            a variable containing a list of numbers
        output : str
            a variable that stores the output

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if user_input and user_input == "args":
            return ["list", "sum"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Sum"
        self._cursor["list"] = self._data_list(user_input)
        self._cursor["sum"] = self._clean_data_value(output)
        return self

    def slice(self, input_list, result, start, end=None):
        """
        Extracts a contiguous subsequence from a list, following slice() semantics.

        Parameters
        ----------
        input_list : list or str
            A list of values or a variable representing a list
        result : str
            A variable that stores the sliced result
        start : int or str
            The start index (0-based, supports negative indices)
        end : int or str, optional
            The end index (exclusive). If omitted, takes the rest of the list

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute

        Examples
        --------
        >>> WOQLQuery().slice(["a", "b", "c", "d"], "v:Result", 1, 3)  # ["b", "c"]
        >>> WOQLQuery().slice(["a", "b", "c", "d"], "v:Result", -2)    # ["c", "d"]
        """
        if input_list and input_list == "args":
            return ["list", "result", "start", "end"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Slice"
        self._cursor["list"] = self._data_list(input_list)
        self._cursor["result"] = self._clean_data_value(result)
        if isinstance(start, int):
            self._cursor["start"] = self._clean_data_value(
                {"@type": "xsd:integer", "@value": start}
            )
        else:
            self._cursor["start"] = self._clean_data_value(start)
        # end is optional
        if end is not None:
            if isinstance(end, int):
                self._cursor["end"] = self._clean_data_value(
                    {"@type": "xsd:integer", "@value": end}
                )
            else:
                self._cursor["end"] = self._clean_data_value(end)
        return self

    def start(self, start, query=None):
        """Specifies that the start of the query returned

        Parameters
        ----------
        start : int
            index of the frist result got returned
        query : WOQLQuery object, optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if start and start == "args":
            return ["start", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Start"
        self._cursor["start"] = start
        return self._add_sub_query(query)

    def limit(self, limit, query=None):
        """Specifies that only the first Number of rows will be returned

        Parameters
        ----------
        limit : int
            number of maximum results returned
        query : WOQLQuery object, optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if limit and limit == "args":
            return ["limit", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Limit"
        self._cursor["limit"] = limit
        return self._add_sub_query(query)

    def re(self, pattern, reg_str, reg_list):
        warnings.warn(
            DeprecationWarning("re() is deprecated; use regexp()"),
            stacklevel=2,
        )
        return self.regexp(pattern, reg_str, reg_list)

    def regexp(self, pattern, reg_str, reg_list):
        """Regular Expression Call
        pattern is a regex pattern (.*) using normal regular expression syntax, the only unusual thing is that special characters have to be escaped twice, s is the string to be matched and m is a list of matches:
        e.g. WOQLQuery().regexp("(.).*", "hello", ["v:All", "v:Sub"])

        Parameters
        ----------
        pattern : str
            regex pattern
        reg_str : str
            string to be matched
        reg_list : str or list or dict
            store list of matches

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if pattern and pattern == "args":
            return ["pattern", "string", "result"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Regexp"
        self._cursor["pattern"] = self._clean_data_value(pattern, "xsd:string")
        self._cursor["string"] = self._clean_data_value(reg_str, "xsd:string")
        self._cursor["result"] = self._data_list(reg_list)
        return self

    def length(self, var_list, var_len):
        """Length
        Calculates the length of a list

        Parameters
        ----------
        var_list : list
            list of elements
        var_len : num
            number of eleemnts

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if var_list and var_list == "args":
            return ["list", "length"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Length"
        self._cursor["list"] = self._data_list(var_list)
        if type(var_len) is float:
            self._cursor["length"] = self._clean_object(
                var_len, "xsd:nonNegativeInteger"
            )
        elif type(var_len) is str:
            self._cursor["length"] = self._varj(var_len)
        return self

    def woql_not(self, query=None):
        """Creates a logical NOT of the arguments

        Parameters
        ----------
        query : WOQLQuery object, optional

        Returns
        ----------
        WOQLQuery object
            query object that can be chained and/or executed
        """
        if query and query == "args":
            return ["query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Not"
        return self._add_sub_query(query)

    def immediately(self, query=None):
        """Immediately runs side-effects without backtracking

        Parameters
        ----------
        query : WOQLQuery object, optional

        Returns
        ----------
        WOQLQuery object
            query object that can be chained and/or executed
        """
        if query and query == "args":
            return ["query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Immediately"
        return self._add_sub_query(query)

    def count(self, countvar, query=None):
        """Counds the number of solutions in the given query

        Parameters
        ----------
        result : A variable or non-negative integer with the count
        query : The query from which to count the number of results

        Returns
        ----------
        WOQLQuery object
           query object that can be chained and/or executed
        """
        if countvar and countvar == "args":
            return ["count", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Count"
        self._cursor["count"] = self._clean_data_value(countvar)
        return self._add_sub_query(query)

    def cast(self, val, user_type, result, literal_type=None):
        """Changes the type of va to type and saves the return in vb

        Parameters
        ----------
        val : str
            original variable
        user_type : str
            type to be changed
        result: str
            save the return variable
        literal_type: str, optional
            literal type of`val`, can be used to treat `val` as a literal rather than an object or variable in the WOQL query.
            If literal type is "owl:Thing" or "node", `val` will be treated as object in the graph

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if literal_type is not None:
            if (literal_type == "owl:Thing" or literal_type == "node") and isinstance(
                val, str
            ):
                return self.cast({"@type": "Value", "node": val}, user_type, result)
            else:
                return self.cast(self.literal(val, literal_type), user_type, result)
        if val and val == "args":
            return ["value", "type", "result"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Typecast"
        self._cursor["value"] = self._clean_object(val)
        self._cursor["type"] = self._clean_node_value(user_type)
        self._cursor["result"] = self._clean_object(result)
        return self

    def type_of(self, value, vtype):
        """Sets the given value and type for cursor.

        Parameters
        ----------
        value : str
            Value which needs to be set
        vtype : type
            Type which needs to be set

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if value and value == "args":
            return ["value", "type"]
        if not value or not vtype:
            raise ValueError("type_of takes two parameters, both values")
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "TypeOf"
        self._cursor["value"] = self._clean_object(value)
        self._cursor["type"] = self._clean_node_value(vtype)
        return self

    def order_by(self, *args, order="asc"):
        """
        Orders the results by the list of variables including in gvarlist, asc_or_desc is a WOQL.asc or WOQ.desc list of variables

        Parameters
        ----------
        gvarlist : list or dict of WOQLQuery().asc or WOQLQuery().desc objects
        query : WOQLQuery object, optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute

        Examples
        -------
        Examples of 3 different usage patterns of order argument
            >>> test1 = WOQLQuery().select("v:Time").using("_commits").woql_and(
            ...        WOQLQuery().order_by("v:Time", order="asc").triple("v:A", "ref:commit_timestamp", "v:Time")
            ... )
            >>> test2 = WOQLQuery().select("v:Time", "v:Message").using("_commits").woql_and(
            ...     WOQLQuery().order_by("v:Time", "v:Message", order={"v:Time": "desc", "v:Message": "asc"}).woql_and(
            ...         WOQLQuery().triple("v:A", "ref:commit_timestamp", "v:Time"),
            ...         WOQLQuery().triple("v:A", "ref:commit_message", "v:Message")
            ...     )
            ... )
            >>> test3 = WOQLQuery().select("v:Time", "v:Message").using("_commits").woql_and(
            ...     WOQLQuery().order_by("v:Time", "v:Message", order=["desc", "asc"]).woql_and(
            ...         WOQLQuery().triple("v:A", "ref:commit_timestamp", "v:Time"),
            ...         WOQLQuery().triple("v:A", "ref:commit_message", "v:Message")
            ...     )
            ... )
        """

        ordered_varlist = list(args)
        if ordered_varlist and ordered_varlist == "args":
            return ["ordering", "query"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "OrderBy"
        self._cursor["ordering"] = []

        if not ordered_varlist or len(ordered_varlist) == 0:
            raise ValueError(
                "Order by must be passed at least one variable to order the query"
            )

        if type(ordered_varlist[-1]) is dict and hasattr(
            ordered_varlist[-1], "to_dict"
        ):
            embedquery = ordered_varlist.pop()
        else:
            embedquery = False
        # if not isinstance(data["parent"], list):
        if isinstance(order, list):
            if len(args) != len(order):
                raise ValueError("Order array must be same length as variable array")

        for item in ordered_varlist:
            if type(item) is str:
                obj = {
                    "@type": "OrderTemplate",
                    "variable": self._raw_var(item),
                    "order": "asc",
                }
                self._cursor["ordering"].append(obj)
            else:
                self._cursor["ordering"].append(item)
        return self._add_sub_query(embedquery)

    def group_by(self, group_vars, template, output, groupquery=None):
        """
        Groups the results of groupquery together by the list of variables group_vars, using the variable template as a grouping and saves the result into variable output.

        Parameters
        ----------
        group_vars : list or str or Var object
            list of variables to group
        template : dict or list or str
            template of data to group with free variable(s)
        output : str, optional
            output variable
        groupquery : dict, optional

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if group_vars and group_vars == "args":
            return [
                "group_by",
                "template",
                "grouped",
                "query",
            ]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "GroupBy"
        if type(group_vars) is not list:
            group_vars = [group_vars]
        self._cursor["group_by"] = self._raw_var_list(group_vars)
        self._cursor["template"] = self._clean_object(template)
        self._cursor["grouped"] = self._clean_object(output)
        return self._add_sub_query(groupquery)

    def true(self):
        """Sets true for cursor type.

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        self._cursor["@type"] = "True"
        return self

    def path(self, subject, pattern, obj, path=None):
        """
        Create a path object constructed by the rules specified with pattern.

        Parameters
        ----------
        subject : str
            a woql subject, the node that the path started
        pattern : str
            a pattern which specified the edges the path is consisted of.
            It uses pattern construction syntax such as:
            * '(scm:edge1, scm:edge2)+' for repeated pattern,
            * 'scm:edge1|scm:edge2' for 'or' pattern,
            * '<scm:edge' for reverse pattern, and
            * '(scm:edge1)[n,m] for pattern between n and m times'
        obj : str
            a woql object, the node that the path ended
        path: str
            output variable

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if subject and subject == "args":
            return ["subject", "pattern", "object", "path"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Path"
        self._cursor["subject"] = self._clean_subject(subject)
        if type(pattern) is str:
            pattern = self._compile_path_pattern(pattern)
        self._cursor["pattern"] = pattern
        self._cursor["object"] = self._clean_object(obj)
        if path is not None:
            self._cursor["path"] = self._varj(path)
        return self

    def size(self, graph, size):
        """Sets the given graph and size for cursor.

        Parameters
        ----------
        graph: Graph which needs to be set as resource
        size: Size which needs to be set

        Returns
        -------
        WOQLQuery object
                    query object that can be chained and/or execute
        """
        if graph and graph == "args":
            return ["resource", "size"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "Size"
        self._cursor["resource"] = self._clean_graph(graph)
        self._cursor["size"] = self._varj(size)
        return self

    def triple_count(self, graph, triple_count):
        """Sets the given triple count and size for cursor.

        Parameters
        ----------
        graph: Graph which needs to be set as resource
        triple_count: Triple count which needs to be set

        Returns
        -------
        WOQLQuery object
                    query object that can be chained and/or execute
        """
        if graph and graph == "args":
            return ["resource", "triple_count"]
        if self._cursor.get("@type"):
            self._wrap_cursor_with_and()
        self._cursor["@type"] = "TripleCount"
        self._cursor["resource"] = self._clean_graph(graph)
        self._cursor["triple_count"] = self._varj(triple_count)
        return self

    def star(self, graph=None, subj=None, pred=None, obj=None):
        """
        Selects everything as triples in the graph identified by GraphIRI into variables Subj, Pred, Obj - by default they are "v:Subject", "v:Predicate", "v:Object"

        Parameters
        ----------
        GraphIRI : str
            graphIRI
        Subj : str, optional
            target subject
        Pred : str, optional
            target predicate
        Obj : str, optional
            target object

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if subj is None:
            subj = "v:Subject"
        if pred is None:
            pred = "v:Predicate"
        if obj is None:
            obj = "v:Object"
        if graph is None:
            graph = False
        if graph:
            return self.quad(subj, pred, obj, graph)
        else:
            return self.triple(subj, pred, obj)

    def all(self, subj=None, pred=None, obj=None, graph=None):
        """Calls the star method and returns the result of the same.

        Parameters
        ----------
        subj : str, optional
            target subject
        pred : str, optional
            target predicate
        obj : str, optional
            target object
        graph : str
            graphIRI

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        return self.star(subj=subj, pred=pred, obj=obj, graph=graph)

    def graph(self, g):
        """Used to specify that the rest of the query should use the graph g in calls to add_quad, quad, etc
        Parameters
        ----------
        g : str
            target graph
        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        return self._set_context({"graph": g})

    def _get_object(self, s, p):
        """Function to get the object for the given subject and predicate.

        Parameters
        ----------
        s: str
            Subject of the object
        p: str
            Predicate of the object

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        if self._cursor.get("@type") == "And":
            for item in self._cursor["query_list"]:
                subq = item.get("query")
                if self._same_entry(subq.get("subject"), s) and self._same_entry(
                    subq.get("predicate"), p
                ):
                    return subq.get("object")
        return None

    def _same_entry(self, a, b):
        """
        A function to check the given two objects, which can be of different types (str, dict), are equal or not.
        When both the passed objects are dicts, deep comparison is done to check for the equality.

        Parameters
        ----------
        a : str or dict
        b : str or dict

        Returns
        -------
        bool
        """
        if a == b:
            return True
        elif type(a) is dict and type(b) is str:
            return self._string_matches_object(b, a)
        elif type(b) is dict and type(a) is str:
            return self._string_matches_object(a, b)
        elif type(a) is dict and type(b) is dict:
            for k in a:
                if b.get(k) != a.get(k):
                    return False
            for j in b:
                if b.get(j) != a.get(j):
                    return False
            return True

    def _string_matches_object(self, s, obj):
        """
        A function to check if the given string is present in the passed dict or not.

        Parameters
        ----------
        s : str
        obj : dict

        Returns
        -------
        bool
        """
        n = obj.get("node")
        if n is not None:
            return s == n
        v = obj.get("@value")
        if v is not None:
            return s == v
        vn = obj.get("variable")
        if vn is not None:
            return s == "v:" + vn
        return False

    def _add_partial(self, s, p, o, g=None):
        """Adds the query based on action given in builder context.

        Parameters
        ----------
        s : str
            target subject
        p : str
            target predicate
        o : str
            target object
        g : str
            graphIRI

        Returns
        -------
        WOQLQuery object
            query object that can be chained and/or execute
        """
        ctxt = self._triple_builder_context
        if s is None:
            s = ctxt.get("subject")
        if g is None:
            g = ctxt.get("graph")
        lastsubj = self._find_last_subject(self._cursor)
        if s is None and lastsubj:
            s = lastsubj.get("subject")
        t = ctxt.get("action")
        if t is None:
            t = lastsubj.get("@type")
        if g is None and lastsubj:
            gobj = lastsubj.get("graph")
            if gobj is not None:
                g = gobj
        if g is None:
            g = "schema"

        if t == "AddTriple":
            self.woql_and(WOQLQuery().add_triple(s, p, o))
        elif t == "DeleteTriple":
            self.woql_and(WOQLQuery().delete_triple(s, p, o))
        elif t == "AddTriple":
            self.woql_and(WOQLQuery().add_quad(s, p, o, g))
        elif t == "DeleteTriple":
            self.woql_and(WOQLQuery().delete_quad(s, p, o, g))
        elif t == "Triple":
            self.woql_and(WOQLQuery().quad(s, p, o, g))
        else:
            self.woql_and(WOQLQuery().triple(s, p, o))
        return self

    def vars(self, *args):
        """Generate variables to be used in WOQLQueries
        Parameters
        ----------
        args
            string arguments
        Returns
        -------
        tuple/string
            args prefixed with "v:"
        """
        vars_tuple = tuple(Var(arg) for arg in args)
        if len(vars_tuple) == 1:
            vars_tuple = vars_tuple[0]
        return vars_tuple

    def variables(self, *args):
        """Generate variables to be used in WOQLQueries
        Parameters
        ----------
        args
            string arguments
        Returns
        -------
        tuple/string
            args prefixed with "v:"
        """
        vars_tuple = tuple(Var(arg) for arg in args)
        if len(vars_tuple) == 1:
            vars_tuple = vars_tuple[0]
        return vars_tuple

    def localize(self, param_spec):
        """Build a localized scope for variables to prevent leaking local variables to outer scope.

        Returns a tuple (localized_fn, v) where:
        - localized_fn: function that wraps queries with select() (empty variable list) and eq() bindings
        - v: VarsUnique object with unique variable names for use in the inner query

        Parameters with non-None values are bound from outer scope via eq().
        Parameters with None values are local-only variables.

        Parameters
        ----------
        param_spec : dict
            Object mapping parameter names to values (or None for local vars)

        Returns
        -------
        tuple
            (localized_fn, v) where localized_fn wraps queries and v contains unique vars

        Example
        -------
        >>> [localized, v] = WOQLQuery().localize({'consSubject': 'v:list', 'valueVar': 'v:val', 'last_cell': None})
        >>> query = localized(
        ...     WOQLQuery().woql_and(
        ...         WOQLQuery().triple(v.consSubject, 'rdf:type', 'rdf:List'),
        ...         WOQLQuery().triple(v.last_cell, 'rdf:rest', 'rdf:nil')
        ...     )
        ... )
        """
        param_names = list(param_spec.keys())
        v = VarsUnique(*param_names)

        def localized_fn(query=None):
            # Create eq bindings for outer parameters OUTSIDE select()
            # This ensures outer parameters are visible in query results
            outer_eq_bindings = []
            for param_name in param_names:
                outer_value = param_spec[param_name]
                if outer_value is not None:
                    # If the outer value is a variable, add eq(var, var) to register it in outer scope
                    is_var = isinstance(outer_value, Var) or (
                        isinstance(outer_value, str) and outer_value.startswith("v:")
                    )
                    if is_var:
                        outer_eq_bindings.append(
                            WOQLQuery().eq(outer_value, outer_value)
                        )
                    # Bind the unique variable to the outer parameter OUTSIDE the select()
                    outer_eq_bindings.append(
                        WOQLQuery().eq(getattr(v, param_name), outer_value)
                    )

            if query is not None:
                # Functional mode: wrap query in select() with empty variable list
                localized_query = WOQLQuery().select(query)

                if outer_eq_bindings:
                    # Wrap: eq(outer) AND select() { query }
                    return WOQLQuery().woql_and(*outer_eq_bindings, localized_query)
                return localized_query

            # Fluent mode: return wrapper that applies pattern on woql_and()
            class FluentWrapper(WOQLQuery):
                def __init__(wrapper_self, outer_bindings, parent_localized):
                    super().__init__()
                    wrapper_self._outer_eq = outer_bindings
                    wrapper_self._parent_localized = parent_localized

                def woql_and(wrapper_self, *args):
                    inner_query = WOQLQuery().woql_and(*args)
                    localized_query = WOQLQuery().select(inner_query)

                    if wrapper_self._outer_eq:
                        return WOQLQuery().woql_and(
                            *wrapper_self._outer_eq, localized_query
                        )
                    return localized_query

            return FluentWrapper(outer_eq_bindings, self)

        return (localized_fn, v)

    def lib(self):
        """Returns the WOQL library instance for RDFList operations and other library functions.

        Returns
        -------
        WOQLLibrary
            Library object with rdflist_* methods

        Example
        -------
        >>> # Get the first element of an rdf:List
        >>> query = WOQLQuery().lib().rdflist_peek('v:list_head', 'v:first_value')
        """
        return WOQLLibrary()


class WOQLLibrary:
    """Library functions for WOQL including RDF List operations.

    This class provides higher-level WOQL operations built on top of the
    core WOQL primitives. RDFList operations work with rdf:List structures
    using rdf:first, rdf:rest, and rdf:nil predicates.
    """

    def _rdflist_peek_raw(self, cons_subject, value_var):
        """Internal: Get first element without localization."""
        return WOQLQuery().woql_and(
            WOQLQuery().triple(cons_subject, "rdf:type", "rdf:List"),
            WOQLQuery().triple(cons_subject, "rdf:first", value_var),
        )

    def _rdflist_member_raw(self, value, cons_subject, cell_var):
        """Internal: Check if value is member of list without localization."""
        return WOQLQuery().woql_and(
            WOQLQuery().path(cons_subject, "rdf:rest*", cell_var),
            WOQLQuery().triple(cell_var, "rdf:first", value),
        )

    def _rdflist_length_raw(self, cons_subject, length_var, path_var):
        """Internal: Get list length without localization."""
        return WOQLQuery().woql_and(
            WOQLQuery().triple(cons_subject, "rdf:type", "rdf:List"),
            WOQLQuery().path(cons_subject, "rdf:rest*", "rdf:nil", path_var),
            WOQLQuery().length(path_var, length_var),
        )

    def _rdflist_nth0_raw(self, cons_subject, index, value_var):
        """Internal: Get element at 0-indexed position without localization."""
        if index == 0:
            return self._rdflist_peek_raw(cons_subject, value_var)
        path_pattern = f"rdf:rest{{{index},{index}}}"
        return WOQLQuery().woql_and(
            WOQLQuery().triple(cons_subject, "rdf:type", "rdf:List"),
            WOQLQuery().path(cons_subject, path_pattern, "v:_nth_cell"),
            WOQLQuery().triple("v:_nth_cell", "rdf:first", value_var),
        )

    def rdflist_list(self, cons_subject, list_var):
        """Collect all rdf:List elements into a single array.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell (rdf:List head)
        list_var : str or Var
            Variable to bind the resulting list values array

        Returns
        -------
        WOQLQuery
            Query that binds list as array to list_var

        Example
        -------
        >>> query = WOQLQuery().woql_and(
        ...     WOQLQuery().triple('doc:mylist', 'tasks', 'v:list_head'),
        ...     WOQLQuery().lib().rdflist_list('v:list_head', 'v:all_values')
        ... )
        >>> result = client.query(query)
        >>> print(result['bindings'][0]['all_values'])  # ['Task A', 'Task B', 'Task C']
        """
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "listVar": list_var,
                "cell": None,
                "value": None,
            }
        )
        return localized(
            WOQLQuery().group_by(
                [],
                [v.value],
                v.listVar,
                WOQLQuery().woql_and(
                    WOQLQuery().path(v.consSubject, "rdf:rest*", v.cell),
                    WOQLQuery().triple(v.cell, "rdf:first", v.value),
                ),
            )
        )

    def rdflist_peek(self, cons_subject, value_var):
        """Get the first element of an rdf:List (peek operation).

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell
        value_var : str or Var
            Variable to bind the first value

        Returns
        -------
        WOQLQuery
            Query that binds first value to value_var

        Example
        -------
        >>> query = WOQLQuery().lib().rdflist_peek('v:list_head', 'v:first_value')
        >>> result = client.query(query)
        >>> print(result['bindings'][0]['first_value'])  # First element
        """
        (localized, v) = WOQLQuery().localize(
            {"consSubject": cons_subject, "valueVar": value_var}
        )
        return localized(self._rdflist_peek_raw(v.consSubject, v.valueVar))

    def rdflist_last(self, cons_subject, value_var):
        """Get the last element of an rdf:List.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell
        value_var : str or Var
            Variable to bind the last value

        Returns
        -------
        WOQLQuery
            Query that binds last value to value_var

        Example
        -------
        >>> query = WOQLQuery().lib().rdflist_last('v:list_head', 'v:last_value')
        >>> result = client.query(query)
        >>> print(result['bindings'][0]['last_value'])  # Last element
        """
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "valueVar": value_var,
                "last_cell": None,
            }
        )
        return localized(
            WOQLQuery().woql_and(
                WOQLQuery().triple(v.consSubject, "rdf:type", "rdf:List"),
                WOQLQuery().path(v.consSubject, "rdf:rest*", v.last_cell),
                WOQLQuery().triple(v.last_cell, "rdf:rest", "rdf:nil"),
                WOQLQuery().triple(v.last_cell, "rdf:first", v.valueVar),
            )
        )

    def rdflist_nth0(self, cons_subject, index, value_var):
        """Get element at 0-indexed position in an rdf:List.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell
        index : int or str or Var
            0-based index (number or variable)
        value_var : str or Var
            Variable to bind the value at that index

        Returns
        -------
        WOQLQuery
            Query that binds value at index to value_var
        """
        if isinstance(index, int):
            if index < 0:
                raise ValueError("rdflist_nth0 requires index >= 0.")
            (localized, v) = WOQLQuery().localize(
                {
                    "consSubject": cons_subject,
                    "valueVar": value_var,
                }
            )
            return localized(self._rdflist_nth0_raw(v.consSubject, index, v.valueVar))

        # Dynamic index via variable
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "index": index,
                "valueVar": value_var,
                "cell": None,
                "path": None,
            }
        )
        return localized(
            WOQLQuery().woql_and(
                WOQLQuery().triple(v.consSubject, "rdf:type", "rdf:List"),
                WOQLQuery().path(v.consSubject, "rdf:rest*", v.cell, v.path),
                WOQLQuery().length(v.path, v.index),
                WOQLQuery().triple(v.cell, "rdf:first", v.valueVar),
            )
        )

    def rdflist_nth1(self, cons_subject, index, value_var):
        """Get element at 1-indexed position in an rdf:List.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell
        index : int or str or Var
            1-based index (number or variable)
        value_var : str or Var
            Variable to bind the value at that index

        Returns
        -------
        WOQLQuery
            Query that binds value at index to value_var
        """
        if isinstance(index, int):
            if index < 1:
                raise ValueError("rdflist_nth1 requires index >= 1.")
            (localized, v) = WOQLQuery().localize(
                {
                    "consSubject": cons_subject,
                    "valueVar": value_var,
                }
            )
            return localized(
                self._rdflist_nth0_raw(v.consSubject, index - 1, v.valueVar)
            )

        raise ValueError(
            "rdflist_nth1 with variable index not yet supported with localize pattern"
        )

    def rdflist_member(self, cons_subject, value):
        """Traverse an rdf:List and yield each element as a separate binding.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell (rdf:List head)
        value : str or Var
            Variable to bind each value, or value to check membership

        Returns
        -------
        WOQLQuery
            Query that yields/matches list elements

        Example
        -------
        >>> # Get all elements as separate bindings
        >>> query = WOQLQuery().lib().rdflist_member('v:list_head', 'v:item')
        >>> result = client.query(query)
        >>> for binding in result['bindings']:
        ...     print(binding['item'])  # Each element in turn
        """
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "value": value,
                "member_cell": None,
            }
        )
        return localized(
            WOQLQuery().woql_and(
                WOQLQuery().triple(v.consSubject, "rdf:type", "rdf:List"),
                self._rdflist_member_raw(v.value, v.consSubject, v.member_cell),
            )
        )

    def rdflist_length(self, cons_subject, length_var):
        """Get the length of an rdf:List.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell
        length_var : str or Var
            Variable to bind the length

        Returns
        -------
        WOQLQuery
            Query that binds list length to length_var

        Example
        -------
        >>> query = WOQLQuery().lib().rdflist_length('v:list_head', 'v:count')
        >>> result = client.query(query)
        >>> print(result['bindings'][0]['count'])  # e.g., 3
        """
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "lengthVar": length_var,
                "length_path": None,
            }
        )
        return localized(
            self._rdflist_length_raw(v.consSubject, v.lengthVar, v.length_path)
        )

    def rdflist_pop(self, cons_subject, value_var):
        """Pop the first element from an rdf:List in-place.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell
        value_var : str or Var
            Variable to bind the popped value

        Returns
        -------
        WOQLQuery
            Query that pops first element and binds it to value_var

        Example
        -------
        >>> # Pop first element: [A, B, C] -> [B, C], returns A
        >>> query = WOQLQuery().lib().rdflist_pop('v:list_head', 'v:popped')
        >>> result = client.query(query)
        >>> print(result['bindings'][0]['popped'])  # 'A'
        """
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "valueVar": value_var,
                "second_cons": None,
                "new_first": None,
                "new_rest": None,
            }
        )
        return localized(
            WOQLQuery().woql_and(
                WOQLQuery().triple(v.consSubject, "rdf:first", v.valueVar),
                WOQLQuery().triple(v.consSubject, "rdf:rest", v.second_cons),
                WOQLQuery().triple(v.second_cons, "rdf:first", v.new_first),
                WOQLQuery().triple(v.second_cons, "rdf:rest", v.new_rest),
                WOQLQuery().delete_triple(v.second_cons, "rdf:type", "rdf:List"),
                WOQLQuery().delete_triple(v.second_cons, "rdf:first", v.new_first),
                WOQLQuery().delete_triple(v.second_cons, "rdf:rest", v.new_rest),
                WOQLQuery().delete_triple(v.consSubject, "rdf:first", v.valueVar),
                WOQLQuery().delete_triple(v.consSubject, "rdf:rest", v.second_cons),
                WOQLQuery().add_triple(v.consSubject, "rdf:first", v.new_first),
                WOQLQuery().add_triple(v.consSubject, "rdf:rest", v.new_rest),
            )
        )

    def rdflist_push(self, cons_subject, value):
        """Push a new element to the front of an rdf:List in-place.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list cons cell
        value : str or Var or dict
            Value to push to the front

        Returns
        -------
        WOQLQuery
            Query that pushes value to front of list in-place

        Example
        -------
        >>> # Push 'New Item' to front: [A, B] -> [New Item, A, B]
        >>> query = WOQLQuery().lib().rdflist_push('v:list_head',
        ...     WOQLQuery().string('New Item'))
        >>> client.query(query)
        """
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "value": value,
                "old_first": None,
                "old_rest": None,
                "new_cons": None,
            }
        )
        return localized(
            WOQLQuery().woql_and(
                WOQLQuery().triple(v.consSubject, "rdf:first", v.old_first),
                WOQLQuery().triple(v.consSubject, "rdf:rest", v.old_rest),
                WOQLQuery().idgen_random("terminusdb://data/Cons/", v.new_cons),
                WOQLQuery().add_triple(v.new_cons, "rdf:type", "rdf:List"),
                WOQLQuery().add_triple(v.new_cons, "rdf:first", v.old_first),
                WOQLQuery().add_triple(v.new_cons, "rdf:rest", v.old_rest),
                WOQLQuery().delete_triple(v.consSubject, "rdf:first", v.old_first),
                WOQLQuery().delete_triple(v.consSubject, "rdf:rest", v.old_rest),
                WOQLQuery().add_triple(v.consSubject, "rdf:first", v.value),
                WOQLQuery().add_triple(v.consSubject, "rdf:rest", v.new_cons),
            )
        )

    def rdflist_append(self, cons_subject, value, new_cell=None):
        """Append an element to the end of an rdf:List.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list head
        value : str or Var or dict
            Value to append
        new_cell : str or Var, optional
            Variable to bind the new cell

        Returns
        -------
        WOQLQuery
            Query that appends value to end of list

        Example
        -------
        >>> # Append 'Last Item' to end: [A, B] -> [A, B, Last Item]
        >>> query = WOQLQuery().lib().rdflist_append('v:list_head',
        ...     WOQLQuery().string('Last Item'), 'v:new_cell')
        >>> client.query(query)
        """
        if new_cell is None:
            new_cell = "v:_append_new_cell"
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "value": value,
                "newCell": new_cell,
                "last_cell": None,
            }
        )
        return localized(
            WOQLQuery().woql_and(
                WOQLQuery().triple(v.consSubject, "rdf:type", "rdf:List"),
                WOQLQuery().path(v.consSubject, "rdf:rest*", v.last_cell),
                WOQLQuery().triple(v.last_cell, "rdf:rest", "rdf:nil"),
                WOQLQuery().idgen_random("terminusdb://data/Cons/", v.newCell),
                WOQLQuery().delete_triple(v.last_cell, "rdf:rest", "rdf:nil"),
                WOQLQuery().add_triple(v.last_cell, "rdf:rest", v.newCell),
                WOQLQuery().add_triple(v.newCell, "rdf:type", "rdf:List"),
                WOQLQuery().add_triple(v.newCell, "rdf:first", v.value),
                WOQLQuery().add_triple(v.newCell, "rdf:rest", "rdf:nil"),
            )
        )

    def rdflist_clear(self, cons_subject, new_list_var):
        """Delete all cons cells of an rdf:List and return rdf:nil as the new list value.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list head
        new_list_var : str or Var
            Variable to bind rdf:nil (the empty list)

        Returns
        -------
        WOQLQuery
            Query that deletes all cons cells and binds rdf:nil

        Example
        -------
        >>> # Clear the list and update the reference
        >>> query = WOQLQuery().woql_and(
        ...     WOQLQuery().lib().rdflist_clear('v:list_head', 'v:empty'),
        ...     WOQLQuery().delete_triple('doc:obj', 'tasks', 'v:list_head'),
        ...     WOQLQuery().add_triple('doc:obj', 'tasks', 'v:empty')
        ... )
        >>> client.query(query)
        """
        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "newListVar": new_list_var,
                "cell": None,
                "cell_first": None,
                "cell_rest": None,
                "head_first": None,
                "head_rest": None,
            }
        )
        return localized(
            WOQLQuery().woql_and(
                # Bind the new list value (rdf:nil = empty list)
                WOQLQuery().eq(v.newListVar, "rdf:nil"),
                # Delete all triples from tail cons cells
                WOQLQuery().opt(
                    WOQLQuery().woql_and(
                        WOQLQuery().path(v.consSubject, "rdf:rest+", v.cell),
                        WOQLQuery().triple(v.cell, "rdf:type", "rdf:List"),
                        WOQLQuery().triple(v.cell, "rdf:first", v.cell_first),
                        WOQLQuery().triple(v.cell, "rdf:rest", v.cell_rest),
                        WOQLQuery().delete_triple(v.cell, "rdf:type", "rdf:List"),
                        WOQLQuery().delete_triple(v.cell, "rdf:first", v.cell_first),
                        WOQLQuery().delete_triple(v.cell, "rdf:rest", v.cell_rest),
                    )
                ),
                # Delete the head cons cell
                WOQLQuery().triple(v.consSubject, "rdf:type", "rdf:List"),
                WOQLQuery().triple(v.consSubject, "rdf:first", v.head_first),
                WOQLQuery().triple(v.consSubject, "rdf:rest", v.head_rest),
                WOQLQuery().delete_triple(v.consSubject, "rdf:type", "rdf:List"),
                WOQLQuery().delete_triple(v.consSubject, "rdf:first", v.head_first),
                WOQLQuery().delete_triple(v.consSubject, "rdf:rest", v.head_rest),
            )
        )

    def rdflist_empty(self, list_var):
        """Create an empty rdf:List (just rdf:nil).

        Parameters
        ----------
        list_var : str or Var
            Variable to bind to rdf:nil

        Returns
        -------
        WOQLQuery
            Query that creates empty list
        """
        return WOQLQuery().eq(list_var, "rdf:nil")

    def rdflist_is_empty(self, cons_subject):
        """Check if an rdf:List is empty (equals rdf:nil).

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI to check

        Returns
        -------
        WOQLQuery
            Query that succeeds if list is empty
        """
        return WOQLQuery().eq(cons_subject, "rdf:nil")

    def rdflist_slice(self, cons_subject, start, end, result_var):
        """Extract a slice of an rdf:List (range of elements) as an array.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list head
        start : int
            Start index (inclusive)
        end : int
            End index (exclusive)
        result_var : str or Var
            Variable to bind the array of sliced values

        Returns
        -------
        WOQLQuery
            Query that extracts list slice values

        Example
        -------
        >>> # Get elements 1-3 (0-indexed): [A, B, C, D] -> [B, C]
        >>> query = WOQLQuery().lib().rdflist_slice('v:list_head', 1, 3, 'v:slice')
        >>> result = client.query(query)
        >>> print(result['bindings'][0]['slice'])  # ['B', 'C']
        """
        if start < 0 or end < 0:
            raise ValueError("rdflist_slice: negative indices not supported")

        if start >= end:
            (localized, v) = WOQLQuery().localize(
                {
                    "consSubject": cons_subject,
                    "resultVar": result_var,
                }
            )
            return localized(WOQLQuery().eq(v.resultVar, []))

        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "resultVar": result_var,
                "node": None,
                "value": None,
            }
        )

        if start == 0 and end == 1:
            find_nodes = WOQLQuery().eq(v.node, v.consSubject)
        elif start == 0:
            find_nodes = WOQLQuery().path(
                v.consSubject, f"rdf:rest{{0,{end - 1}}}", v.node
            )
        else:
            find_nodes = WOQLQuery().path(
                v.consSubject, f"rdf:rest{{{start},{end - 1}}}", v.node
            )

        return localized(
            WOQLQuery().group_by(
                [],
                [v.value],
                v.resultVar,
                WOQLQuery().woql_and(
                    find_nodes, WOQLQuery().triple(v.node, "rdf:first", v.value)
                ),
            )
        )

    def rdflist_insert(self, cons_subject, position, value, new_node_var=None):
        """Insert a value at a specific position in an rdf:List.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list head
        position : int
            Position to insert at (0-indexed)
        value : str or Var or dict
            Value to insert
        new_node_var : str or Var, optional
            Variable to bind the new node

        Returns
        -------
        WOQLQuery
            Query that inserts value at position
        """
        if position < 0:
            raise ValueError("rdflist_insert requires position >= 0.")

        if new_node_var is None:
            new_node_var = "v:_insert_new_node"

        if position == 0:
            (localized, v) = WOQLQuery().localize(
                {
                    "consSubject": cons_subject,
                    "value": value,
                    "newNodeVar": new_node_var,
                    "old_first": None,
                    "old_rest": None,
                }
            )
            return localized(
                WOQLQuery().woql_and(
                    WOQLQuery().triple(v.consSubject, "rdf:first", v.old_first),
                    WOQLQuery().triple(v.consSubject, "rdf:rest", v.old_rest),
                    WOQLQuery().idgen(
                        "list_node", [v.old_first, v.consSubject], v.newNodeVar
                    ),
                    WOQLQuery().add_triple(v.newNodeVar, "rdf:type", "rdf:List"),
                    WOQLQuery().add_triple(v.newNodeVar, "rdf:first", v.old_first),
                    WOQLQuery().add_triple(v.newNodeVar, "rdf:rest", v.old_rest),
                    WOQLQuery().delete_triple(v.consSubject, "rdf:first", v.old_first),
                    WOQLQuery().delete_triple(v.consSubject, "rdf:rest", v.old_rest),
                    WOQLQuery().add_triple(v.consSubject, "rdf:first", v.value),
                    WOQLQuery().add_triple(v.consSubject, "rdf:rest", v.newNodeVar),
                )
            )

        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "value": value,
                "newNodeVar": new_node_var,
                "pred_node": None,
                "old_rest": None,
            }
        )
        rest_count = position - 1
        path_pattern = (
            "" if rest_count == 0 else f"rdf:rest{{{rest_count},{rest_count}}}"
        )

        if rest_count == 0:
            find_predecessor = WOQLQuery().eq(v.pred_node, v.consSubject)
        else:
            find_predecessor = WOQLQuery().path(
                v.consSubject, path_pattern, v.pred_node
            )

        return localized(
            WOQLQuery().woql_and(
                find_predecessor,
                WOQLQuery().triple(v.pred_node, "rdf:rest", v.old_rest),
                WOQLQuery().idgen("list_node", [v.value, v.pred_node], v.newNodeVar),
                WOQLQuery().delete_triple(v.pred_node, "rdf:rest", v.old_rest),
                WOQLQuery().add_triple(v.pred_node, "rdf:rest", v.newNodeVar),
                WOQLQuery().add_triple(v.newNodeVar, "rdf:type", "rdf:List"),
                WOQLQuery().add_triple(v.newNodeVar, "rdf:first", v.value),
                WOQLQuery().add_triple(v.newNodeVar, "rdf:rest", v.old_rest),
            )
        )

    def rdflist_drop(self, cons_subject, position):
        """Drop/remove a single element from an rdf:List at a specific position.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list head
        position : int
            Position of element to remove (0-indexed)

        Returns
        -------
        WOQLQuery
            Query that removes the element at position
        """
        if position < 0:
            raise ValueError("rdflist_drop requires position >= 0.")

        if position == 0:
            (localized, v) = WOQLQuery().localize(
                {
                    "consSubject": cons_subject,
                    "old_first": None,
                    "rest_node": None,
                    "next_first": None,
                    "next_rest": None,
                }
            )
            return localized(
                WOQLQuery().woql_and(
                    WOQLQuery().triple(v.consSubject, "rdf:first", v.old_first),
                    WOQLQuery().triple(v.consSubject, "rdf:rest", v.rest_node),
                    WOQLQuery().triple(v.rest_node, "rdf:first", v.next_first),
                    WOQLQuery().triple(v.rest_node, "rdf:rest", v.next_rest),
                    WOQLQuery().delete_triple(v.rest_node, "rdf:type", "rdf:List"),
                    WOQLQuery().delete_triple(v.rest_node, "rdf:first", v.next_first),
                    WOQLQuery().delete_triple(v.rest_node, "rdf:rest", v.next_rest),
                    WOQLQuery().delete_triple(v.consSubject, "rdf:first", v.old_first),
                    WOQLQuery().delete_triple(v.consSubject, "rdf:rest", v.rest_node),
                    WOQLQuery().add_triple(v.consSubject, "rdf:first", v.next_first),
                    WOQLQuery().add_triple(v.consSubject, "rdf:rest", v.next_rest),
                )
            )

        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "pred_node": None,
                "drop_node": None,
                "drop_first": None,
                "drop_rest": None,
            }
        )
        rest_count = position - 1
        path_pattern = (
            "" if rest_count == 0 else f"rdf:rest{{{rest_count},{rest_count}}}"
        )

        if rest_count == 0:
            find_predecessor = WOQLQuery().eq(v.pred_node, v.consSubject)
        else:
            find_predecessor = WOQLQuery().path(
                v.consSubject, path_pattern, v.pred_node
            )

        return localized(
            WOQLQuery().woql_and(
                find_predecessor,
                WOQLQuery().triple(v.pred_node, "rdf:rest", v.drop_node),
                WOQLQuery().triple(v.drop_node, "rdf:first", v.drop_first),
                WOQLQuery().triple(v.drop_node, "rdf:rest", v.drop_rest),
                WOQLQuery().delete_triple(v.drop_node, "rdf:type", "rdf:List"),
                WOQLQuery().delete_triple(v.drop_node, "rdf:first", v.drop_first),
                WOQLQuery().delete_triple(v.drop_node, "rdf:rest", v.drop_rest),
                WOQLQuery().delete_triple(v.pred_node, "rdf:rest", v.drop_node),
                WOQLQuery().add_triple(v.pred_node, "rdf:rest", v.drop_rest),
            )
        )

    def rdflist_swap(self, cons_subject, pos_a, pos_b):
        """Swap elements at two positions in an rdf:List.

        Parameters
        ----------
        cons_subject : str or Var
            Variable or IRI of the list head
        pos_a : int
            First position (0-indexed)
        pos_b : int
            Second position (0-indexed)

        Returns
        -------
        WOQLQuery
            Query that swaps elements at the two positions
        """
        if pos_a < 0 or pos_b < 0:
            raise ValueError("rdflist_swap requires positions >= 0.")

        if pos_a == pos_b:
            (localized, v) = WOQLQuery().localize({"consSubject": cons_subject})
            return localized(WOQLQuery().triple(v.consSubject, "rdf:type", "rdf:List"))

        (localized, v) = WOQLQuery().localize(
            {
                "consSubject": cons_subject,
                "node_a": None,
                "node_b": None,
                "value_a": None,
                "value_b": None,
            }
        )

        # Find node at pos_a
        if pos_a == 0:
            find_node_a = WOQLQuery().eq(v.node_a, v.consSubject)
        else:
            find_node_a = WOQLQuery().path(
                v.consSubject, f"rdf:rest{{{pos_a},{pos_a}}}", v.node_a
            )

        # Find node at pos_b
        if pos_b == 0:
            find_node_b = WOQLQuery().eq(v.node_b, v.consSubject)
        else:
            find_node_b = WOQLQuery().path(
                v.consSubject, f"rdf:rest{{{pos_b},{pos_b}}}", v.node_b
            )

        return localized(
            WOQLQuery().woql_and(
                find_node_a,
                find_node_b,
                WOQLQuery().triple(v.node_a, "rdf:first", v.value_a),
                WOQLQuery().triple(v.node_b, "rdf:first", v.value_b),
                WOQLQuery().delete_triple(v.node_a, "rdf:first", v.value_a),
                WOQLQuery().delete_triple(v.node_b, "rdf:first", v.value_b),
                WOQLQuery().add_triple(v.node_a, "rdf:first", v.value_b),
                WOQLQuery().add_triple(v.node_b, "rdf:first", v.value_a),
            )
        )