Meta utility functions (#449)

* IReference interface

* Implementa IReference and shuffle some interfaces

* E d i t

* Slot change

* More interface shakeup

* Change a lot of stuff

* Break out ReferenceBase and add tests

* Don't forget symbols

* Minor stuff

* Fix lint and format

* Use Python stuff instead of my dumb thing

* Some minor stuff

* vary-meta tests

Author: chrisrink10

src/basilisp/core.lpy

@@ -54,7 +54,9 @@
          (.-meta o)
          nil)))
 
-(def ^{:doc      "Return o with the supplied metadata map assoc'ed into its existing metadata."
+(def ^{:doc      "Return an object of the same type and representing the same value as
+                  o with meta as its metadata. Of Basilisp's builtin types, only those
+                  implementing the interface IWithMeta support `with-meta`."
        :arglists '([o meta])}
   with-meta
   (fn* with-meta [o meta]
@@ -180,6 +182,14 @@
   (fn apply [f & args]
     (basilisp.lang.runtime/apply f args)))
 
+(def ^{:doc      "Return an object of the same type and representing the same value as o
+                  (as by `with-meta`) with the new object's metadata set to the value of
+                  `(apply f (meta o) & args)`."
+       :arglists '([o f & args])}
+  vary-meta
+  (fn* vary-meta [o f & args]
+       (with-meta o (apply f (meta o) args))))
+
 (def ^{:doc      "Concatenate the sequences given by seqs into a single Seq."
        :arglists '([& seqs])}
   concat
@@ -281,9 +291,12 @@
           fmeta (if (map? (first body))
                   (first body)
                   nil)
+          fname  (if fmeta
+                   (vary-meta name conj fmeta)
+                   name)
           fname  (if doc
-                   (with-meta name (assoc fmeta :doc doc))
-                   (with-meta name fmeta))
+                   (vary-meta fname assoc :doc doc)
+                   (vary-meta fname conj fmeta))
           body   (if fmeta
                    (rest body)
                    body)
@@ -296,7 +309,7 @@
                               (conj sigs (ffirst arities)))
                        (apply list sigs)))
                    (list (first body)))
-          fname  (with-meta fname {:arglists (list 'quote fsigs)})
+          fname  (vary-meta fname assoc :arglists (list 'quote fsigs))
           body   (if multi?
                    body
                    (cons
@@ -416,8 +429,8 @@
                    (rest body)
                    body)
           fname  (if doc
-                   (with-meta name (assoc fmeta :doc doc :macro true))
-                   (with-meta name (assoc fmeta :macro true)))
+                   (vary-meta name assoc :doc doc :macro true)
+                   (vary-meta name assoc :macro true))
           multi? (list? (first body))
           fsigs  (if multi?
                    (loop [arities body
@@ -427,7 +440,7 @@
                               (conj sigs (ffirst arities)))
                        `(quote ~(apply list sigs))))
                    `(quote ~(list (first body))))
-          fname  (with-meta fname {:arglists fsigs})
+          fname  (vary-meta fname assoc :arglists fsigs)
 
           add-implicit-args (fn [body]
                               (cons
@@ -2953,6 +2966,23 @@
                                                   ctx
                                                   module)))
 
+;;;;;;;;;;;;;;;;;;;
+;; Ref Utilities ;;
+;;;;;;;;;;;;;;;;;;;
+
+(defn alter-meta!
+  "Atomically swap the metadata on reference o to the result of (apply f m args) where
+  m is the current metadata of o. f should be free of side effects. References include
+  atoms, namespaces, and vars."
+  [o f & args]
+  (apply-method o alter-meta f args))
+
+(defn reset-meta!
+  "Atomically swap the metadata on reference o to meta. References include
+  atoms, namespaces, and vars."
+  [o meta]
+  (.reset-meta o meta))
+
 ;;;;;;;;;;;;;;;;;;;
 ;; Var Utilities ;;
 ;;;;;;;;;;;;;;;;;;;
@@ -4025,7 +4055,7 @@
 
         interfaces (concat interfaces
                            '[basilisp.lang.interfaces/IPersistentMap
-                             basilisp.lang.interfaces/IMeta
+                             basilisp.lang.interfaces/IWithMeta
                              basilisp.lang.interfaces/IRecord
                              python/object])
 
@@ -4149,10 +4179,9 @@
           (+ ~(count field-kw-set)
              (count ~'_recmap)))
 
-         ;; IMeta
+         ;; IWithMeta
          (~'with-meta [~this-gs new-meta#]
-          (->> (merge (or ~'meta {}) new-meta#)
-               (evolve ~this-gs "meta")))
+          (evolve ~this-gs "meta" new-meta#))
 
          ;; IRecord
          (~' ^:classmethod create [cls# ~map-gs]

src/basilisp/lang/atom.py

@@ -1,17 +1,22 @@
-from typing import Callable, Generic, TypeVar
+import threading
+from typing import Callable, Generic, Optional, TypeVar
 
 import atomos.atom
 
-from basilisp.lang.interfaces import IDeref
+from basilisp.lang.interfaces import IDeref, IPersistentMap
+from basilisp.lang.reference import ReferenceBase
 
 T = TypeVar("T")
 
 
-class Atom(IDeref[T], Generic[T]):
-    __slots__ = ("_atom",)
+class Atom(IDeref[T], ReferenceBase, Generic[T]):
+    __slots__ = ("_atom", "_meta", "_lock")
 
+    # pylint: disable=assigning-non-slot
     def __init__(self, state: T) -> None:
-        self._atom = atomos.atom.Atom(state)  # pylint: disable=assigning-non-slot
+        self._atom = atomos.atom.Atom(state)
+        self._meta: Optional[IPersistentMap] = None
+        self._lock = threading.Lock()
 
     def compare_and_set(self, old, new):
         return self._atom.compare_and_set(old, new)

src/basilisp/lang/compiler/analyzer.py

@@ -113,7 +113,7 @@
     Vector as VectorNode,
     WithMeta,
 )
-from basilisp.lang.interfaces import IMeta, IRecord, ISeq, IType
+from basilisp.lang.interfaces import IMeta, IRecord, ISeq, IType, IWithMeta
 from basilisp.lang.runtime import Var
 from basilisp.lang.typing import LispForm, ReaderForm
 from basilisp.lang.util import count, genname, munge
@@ -236,9 +236,7 @@ def _warn_unused_names(self):
             if entry.warn_if_unused and not entry.used:
                 code_loc = (
                     Maybe(entry.symbol.meta)
-                    .map(
-                        lambda m: f": {m.val_at(reader.READER_LINE_KW)}"  # type: ignore
-                    )
+                    .map(lambda m: f": {m.val_at(reader.READER_LINE_KW)}")
                     .or_else_get("")
                 )
                 logger.warning(
@@ -514,15 +512,16 @@ def has_meta_prop(o: Union[IMeta, Var]) -> bool:
 def _loc(form: Union[LispForm, ISeq]) -> Optional[Tuple[int, int]]:
     """Fetch the location of the form in the original filename from the
     input form, if it has metadata."""
-    try:
-        meta = form.meta  # type: ignore
-        line = meta.get(reader.READER_LINE_KW)  # type: ignore
-        col = meta.get(reader.READER_COL_KW)  # type: ignore
-    except AttributeError:
-        return None
-    else:
-        assert isinstance(line, int) and isinstance(col, int)
-        return line, col
+    # Technically, IMeta is sufficient for fetching `form.meta` but the
+    # reader only applies line and column metadata to IWithMeta instances
+    if isinstance(form, IWithMeta):
+        meta = form.meta
+        if meta is not None:
+            line = meta.get(reader.READER_LINE_KW)
+            col = meta.get(reader.READER_COL_KW)
+            if isinstance(line, int) and isinstance(col, int):
+                return line, col
+    return None
 
 
 def _with_loc(f: AnalyzeFunction):
@@ -655,7 +654,7 @@ def _def_ast(  # pylint: disable=too-many-branches,too-many-locals
     def_loc = _loc(form) or (None, None)
     def_node_env = ctx.get_node_env()
     def_meta = _clean_meta(
-        name.meta.update(
+        name.meta.update(  # type: ignore [union-attr]
             lmap.map(
                 {
                     COL_KW: def_loc[1],
@@ -1222,9 +1221,7 @@ def _deftype_ast(  # pylint: disable=too-many-branches
             field_default = (
                 Maybe(field.meta)
                 .map(
-                    lambda m: m.val_at(  # type: ignore
-                        SYM_DEFAULT_META_KEY, __DEFTYPE_DEFAULT_SENTINEL
-                    )
+                    lambda m: m.val_at(SYM_DEFAULT_META_KEY, __DEFTYPE_DEFAULT_SENTINEL)
                 )
                 .value
             )

src/basilisp/lang/compiler/generator.py

@@ -405,17 +405,15 @@ def _is_dynamic(v: Var) -> bool:
     Var access."""
     return (
         Maybe(v.meta)
-        .map(lambda m: m.get(SYM_DYNAMIC_META_KEY, None))  # type: ignore
+        .map(lambda m: m.get(SYM_DYNAMIC_META_KEY, None))
         .or_else_get(False)
     )
 
 
 def _is_redefable(v: Var) -> bool:
     """Return True if the Var can be redefined."""
     return (
-        Maybe(v.meta)
-        .map(lambda m: m.get(SYM_REDEF_META_KEY, None))  # type: ignore
-        .or_else_get(False)
+        Maybe(v.meta).map(lambda m: m.get(SYM_REDEF_META_KEY, None)).or_else_get(False)
     )
 
 

src/basilisp/lang/interfaces.py

@@ -2,13 +2,15 @@
 from abc import ABC, abstractmethod
 from typing import (
     AbstractSet,
+    Callable,
     Generic,
     Iterable,
     Iterator,
     Mapping,
     Optional,
     Sequence,
     TypeVar,
+    Union,
 )
 
 from basilisp.lang.obj import LispObject as _LispObject, seq_lrepr
@@ -77,14 +79,33 @@ class IMeta(ABC):
     def meta(self) -> Optional["IPersistentMap"]:
         raise NotImplementedError()
 
+
+T_with_meta = TypeVar("T_with_meta", bound="IWithMeta")
+
+
+class IWithMeta(IMeta):
+    __slots__ = ()
+
     @abstractmethod
-    def with_meta(self, meta: "IPersistentMap") -> "IMeta":
+    def with_meta(self: T_with_meta, meta: "Optional[IPersistentMap]") -> T_with_meta:
         raise NotImplementedError()
 
 
 ILispObject = _LispObject
 
 
+class IReference(IMeta):
+    __slots__ = ()
+
+    @abstractmethod
+    def alter_meta(self, f: Callable[..., "IPersistentMap"], *args) -> "IPersistentMap":
+        raise NotImplementedError()
+
+    @abstractmethod
+    def reset_meta(self, meta: "IPersistentMap") -> "IPersistentMap":
+        raise NotImplementedError()
+
+
 class IReversible(Generic[T]):
     __slots__ = ()
 
@@ -113,11 +134,14 @@ def val_at(self, k: K, default: Optional[V] = None) -> Optional[V]:
         raise NotImplementedError()
 
 
+T_pcoll = TypeVar("T_pcoll", bound="IPersistentCollection", covariant=True)
+
+
 class IPersistentCollection(ISeqable[T]):
     __slots__ = ()
 
     @abstractmethod
-    def cons(self, *elems: T) -> "IPersistentCollection[T]":
+    def cons(self: T_pcoll, *elems: T) -> "T_pcoll":
         raise NotImplementedError()
 
     @staticmethod
@@ -126,13 +150,16 @@ def empty() -> "IPersistentCollection[T]":
         raise NotImplementedError()
 
 
+T_assoc = TypeVar("T_assoc", bound="IAssociative")
+
+
 class IAssociative(
     ILookup[K, V], Mapping[K, V], IPersistentCollection[IMapEntry[K, V]]
 ):
     __slots__ = ()
 
     @abstractmethod
-    def assoc(self, *kvs) -> "IAssociative[K, V]":
+    def assoc(self: T_assoc, *kvs) -> T_assoc:
         raise NotImplementedError()
 
     @abstractmethod
@@ -144,6 +171,9 @@ def entry(self, k: K) -> Optional[IMapEntry[K, V]]:
         raise NotImplementedError()
 
 
+T_stack = TypeVar("T_stack", bound="IPersistentStack")
+
+
 class IPersistentStack(IPersistentCollection[T]):
     __slots__ = ()
 
@@ -152,30 +182,45 @@ def peek(self) -> Optional[T]:
         raise NotImplementedError()
 
     @abstractmethod
-    def pop(self) -> "IPersistentStack[T]":
+    def pop(self: T_stack) -> T_stack:
         raise NotImplementedError()
 
 
 class IPersistentList(ISequential, IPersistentStack[T]):
     __slots__ = ()
 
 
+T_map = TypeVar("T_map", bound="IPersistentMap")
+
+
 class IPersistentMap(ICounted, IAssociative[K, V]):
     __slots__ = ()
 
     @abstractmethod
-    def dissoc(self, *ks: K) -> "IPersistentMap[K, V]":
+    def cons(  # type: ignore[override]
+        self: T_map, *elems: Union[IMapEntry[K, V], "IPersistentMap[K, V]"]
+    ) -> T_map:
+        raise NotImplementedError()
+
+    @abstractmethod
+    def dissoc(self: T_map, *ks: K) -> T_map:
         raise NotImplementedError()
 
 
+T_set = TypeVar("T_set", bound="IPersistentSet")
+
+
 class IPersistentSet(AbstractSet[T], ICounted, IPersistentCollection[T]):
     __slots__ = ()
 
     @abstractmethod
-    def disj(self, *elems: T) -> "IPersistentSet[T]":
+    def disj(self: T_set, *elems: T) -> T_set:
         raise NotImplementedError()
 
 
+T_vec = TypeVar("T_vec", bound="IPersistentVector")
+
+
 class IPersistentVector(
     Sequence[T],
     IAssociative[int, T],
@@ -187,11 +232,15 @@ class IPersistentVector(
     __slots__ = ()
 
     @abstractmethod
-    def cons(self, *elems: T) -> "IPersistentVector[T]":  # type: ignore
+    def assoc(self: T_vec, *kvs) -> T_vec:  # type: ignore[override]
+        raise NotImplementedError()
+
+    @abstractmethod
+    def cons(self: T_vec, *elems: T) -> T_vec:  # type: ignore[override]
         raise NotImplementedError()
 
     @abstractmethod
-    def seq(self) -> "ISeq[T]":  # type: ignore
+    def seq(self) -> "ISeq[T]":  # type: ignore[override]
         raise NotImplementedError()